unix: Expand the build steps in the README.

- Present the default build dependencies in one place at the top, and make
  a separate section about building standalone.

- Add steps for the "minimal" variant as well.

- Document that building standalone requires autoconf and libtool.

- Allow MICROPY_STANDALONE to be set as an environment variable.

Fixes issue #11313.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

ports/unix/README.md

@@ -1,17 +1,59 @@
-The Unix version
+MicroPython Unix port
-----------------
+=====================
 
-The "unix" port requires a standard Unix-like environment with gcc and GNU
+The "unix" port runs in standard Unix-like environments including Linux, BSD,
-make. This includes Linux, BSD, macOS, and Windows Subsystem for Linux. The
+macOS, and Windows Subsystem for Linux.
-x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well as
+
-ARM and MIPS. Making a full-featured port to another architecture requires
+The x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
+as ARM and MIPS. Extending the unix port to another architecture requires
 writing some assembly code for the exception handling and garbage collection.
 Alternatively, a fallback implementation based on setjmp/longjmp can be used.
 
-To build (see section below for required dependencies):
+Building
+--------
+
+### Dependencies
+
+To build the unix port locally then you will need:
+
+* git command line executable, unless you downloaded a source .tar.xz file from
+  https://micropython.org/download/
+* gcc (or clang for macOS) toolchain
+* GNU Make
+* Python 3.x
+
+To build the default "standard" variant and configuration, then you will also
+need:
+
+* `pkg-config` tool
+* `libffi` library and headers
+
+On Debian/Ubuntu/Mint and related Linux distros, you can install all these
+dependencies with a command like:
+
+```
+# apt install build-essential git python3 pkg-config libbfi-dev
+```
+
+(See below for steps to build either a standalone or minimal MicroPython
+executable that doesn't require system `libffi` or `pkg-config`.)
+
+### Default build steps
+
+To set up the environment for building (not needed every time), starting from
+the top-level MicroPython directory:
 
     $ cd ports/unix
+    $ make -C ../../mpy-cross
     $ make submodules
+
+The `mpy-cross` step builds the [MicroPython
+cross-compiler](https://github.com/micropython/micropython/?tab=readme-ov-file#the-micropython-cross-compiler-mpy-cross).
+The `make submodules` step can be skipped if you didn't clone the MicroPython
+source from git.
+
+Next, to build the actual executable (still in the `ports/unix` directory):
+
     $ make
 
 Then to give it a try:
@@ -45,40 +87,59 @@ Browse available modules at
 [Package management](https://docs.micropython.org/en/latest/reference/packages.html)
 for more information about `mip`.
 
-External dependencies
+### Minimal Variant
----------------------
 
-The `libffi` library and `pkg-config` tool are required. On Debian/Ubuntu/Mint
+The "standard" variant of MicroPython is the default. It enables most features,
-derivative Linux distros, install `build-essential`(includes toolchain and
+including external modules interfaced using `libffi`. To instead build the
-make), `libffi-dev`, and `pkg-config` packages.
+"minimal" variant, which disables almost all optional features and modules:
-
-Other dependencies can be built together with MicroPython. This may
-be required to enable extra features or capabilities, and in recent
-versions of MicroPython, these may be enabled by default. To build
-these additional dependencies, in the unix port directory first execute:
 
+    $ cd ports/unix
     $ make submodules
+    $ make VARIANT=minimal
 
-This will fetch all the relevant git submodules (sub repositories) that
+The executable will be built at `build-minimal/micropython`.
-the port needs.  Use the same command to get the latest versions of
-submodules as they are updated from time to time. After that execute:
 
-    $ make deplibs
+Additional variants can be found in the `variants` sub-directory of the port,
+although these are mostly of interest to MicroPython maintainers.
 
-This will build all available dependencies (regardless whether they are used
+### Standalone build
-or not). If you intend to build MicroPython with additional options
+
-(like cross-compiling), the same set of options should be passed to `make
+By default, the "standard" variant uses `pkg-config` to link to the system's
-deplibs`. To actually enable/disable use of dependencies, edit the
+shared `libffi` library.
+
+It is possible to instead build a standalone MicroPython where `libffi` is built
+from source and linked statically into the `micropython` executable. This is
+mostly useful for embedded or cross-compiled applications.
+
+Building standalone requires `autoconf` and `libtool` to also be installed.
+
+To build standalone:
+
+    $ export MICROPY_STANDALONE=1
+    $ make submodules                # fetches libffi submodule
+    $ make deplibs                   # build just the external libraries
+    $ make                           # build MicroPython itself
+
+`make deplibs` causes all supported external libraries (currently only `libffi`)
+to be built inside the build directory, so it needs to run again only after
+`make clean`.
+
+If you intend to build MicroPython with additional options (like
+cross-compiling), the same set of options should be passed to both `make
+deplibs` and `make`.
+
+### Other dependencies
+
+To actually enable/disable use of dependencies, edit the
 `ports/unix/mpconfigport.mk` file, which has inline descriptions of the
 options. For example, to build the SSL module, `MICROPY_PY_SSL` should be
 set to 1.
 
-Debug Symbols
+### Debug Symbols
--------------
 
 By default, builds are stripped of symbols and debug information to save size.
 
-To build a debuggable version of the Unix port, there are two options
+To build a debuggable version of the Unix port, there are two options:
 
 1. Run `make [other arguments] DEBUG=1`. Note setting `DEBUG` also reduces the
    optimisation level, so it's not a good option for builds that also want the

ports/unix/mpconfigport.mk

@@ -37,7 +37,7 @@ MICROPY_PY_JNI = 0
 
 # Avoid using system libraries, use copies bundled with MicroPython
 # as submodules (currently affects only libffi).
-MICROPY_STANDALONE = 0
+MICROPY_STANDALONE ?= 0
 
 MICROPY_ROM_TEXT_COMPRESSION = 1