Summary

This Pull Request adds new documentation to ports/unix/README.md to guide users on how to build a fully statically linked MicroPython executable for the Unix port. The existing documentation for MICROPY_STANDALONE=1 only covers static linking of libffi. However, for deployments to minimal Linux environments (like Buildroot) or for creating truly self-contained binaries, a full static link of all dependencies (including libc, libpthread, etc.) is often required. This change addresses the common issue of binaries failing to run due to missing ld.so or libc mismatches in target environments.

The new section, titled "Fully Static Builds (for minimal environments)", includes:

• Important considerations regarding increased binary size, the lack of runtime library updates, and toolchain support.
• Step-by-step instructions for ensuring the necessary static development packages are installed.
• Guidance on using LDFLAGS_EXTRA="-static" during the build process, including an example for cross-compilation with mipsel-linux-gnu-.
• Methods for verifying the static nature of the built binary using file and ldd.
• Troubleshooting advice, highlighting missing static libraries as a primary cause of linker errors.

Testing

Testing was performed by:

• Building the ports/unix default configuration with LDFLAGS_EXTRA="-static" on a Debian-based Linux system to create a fully static native executable. Verification was done using file and ldd.
• Cross-compiling ports/unix with CROSS_COMPILE=mipsel-linux-gnu- and LDFLAGS_EXTRA="-static" on a Debian-based Linux system (with libc6-dev-mipsel-cross installed) to simulate a static build for an embedded Linux target. Verification was performed using file and attempting to run the binary via qemu-mipsel.

All builds successfully completed, and the resulting executables were confirmed to be statically linked.

For a practical demonstration of a successful static build, please refer to the following workflow run

Trade-offs and Alternatives

The primary trade-off for fully static builds is the increased binary size. Statically linked executables are significantly larger compared to dynamically linked ones because they embed all necessary library code directly. However, this is an acceptable trade-off for users targeting minimal environments where a dynamic linker is unavailable or incompatible, or for situations requiring a single, self-contained executable.

No direct alternatives within the current MicroPython build system were identified for achieving a full static link without passing custom LDFLAGS. The existing MICROPY_STANDALONE=1 flag specifically addresses libffi's static linking, not the entire binary's dependencies on system libraries. This documentation clarifies the existing mechanism (LDFLAGS_EXTRA) for this specific use case.

Relative issues: #17399, #17353