QUERY · ISSUE

docs: pots/unix (standalone) has no instructions to build static linked micropython instance

openby o-murphyopened 2025-05-30updated 2025-07-07

docsport-unix

Documentation URL

https://github.com/micropython/micropython/blob/master/ports/unix/README.md

Description

The ports/unix instructions not provide a way to build micropython with LDFLAGS -static to link ld statically. So even if you trying to build standalone binary it still build dynamic linked instance (e.g. ld.so.1). Dynamic linking to system ld.so.1 makes impossible to run binary on systems like Buildroot Linux

For make fully standalone static linked build you should directly modify Makefile cause make not handle LDFLAGS and docs not give instructions for this case.

Relative to issue: https://github.com/micropython/micropython/issues/17353

Code of Conduct

Yes, I agree

CANDIDATE · PULL REQUEST

unix: Extend README with fully static builds section.

openby o-murphyopened 2025-06-08updated 2025-09-21

docsport-unix

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.