Skip to content

unix: Extend README with fully static builds section. #17456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

unix: Extend README with fully static builds section. #17456

wants to merge 1 commit into from
+75 −7

Conversation

o-murphy
Copy link

@o-murphy o-murphy commented Jun 8, 2025 •
edited
Loading

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

@o-murphy o-murphy marked this pull request as ready for review June 8, 2025 01:27
@codecov Codecov
Copy link

codecov bot commented Jun 8, 2025 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.54%. Comparing base (5f058e9) to head (e8fd35c).
Report is 81 commits behind head on master.

Additional details and impacted files 
@@           Coverage Diff           @@
##           master   #17456   +/-   ##
=======================================
  Coverage   98.54%   98.54%           
=======================================
  Files         169      169           
  Lines       21943    21943           
=======================================
  Hits        21623    21623           
  Misses        320      320

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions GitHub Actions
Copy link

github-actions bot commented Jun 8, 2025

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
     mimxrt:    +0 +0.000% TEENSY40
        rp2:    +0 +0.000% RPI_PICO_W
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
  qemu rv32:    +0 +0.000% VIRT_RV32

@o-murphy o-murphy changed the title Extended ports/unix/README.md. Fully Static Builds section ports/unix: Extend README with fully static builds section Jun 8, 2025
@o-murphy o-murphy changed the title ports/unix: Extend README with fully static builds section unix: Extend README with fully static builds section. Jun 8, 2025
@o-murphy
unix: Extend README with fully static builds section.
e8fd35c 
Add a new section to `ports/unix/README.md` that describes
how to perform fully static builds of the MicroPython unix
port. This provides clearer guidance for advanced users
and CI configurations, improving documentation clarity.

Fixes micropython#17399, micropython#17353

Signed-off-by: o-murphy <[email protected]>
@jonnor
Copy link
Contributor

jonnor commented Jun 9, 2025

Hi @o-murphy thank you for this MR. The documentation looks comprehensive and well-structured. Thumbs up from me :)

One thing I am not sure about is the formatting of the steps - does that render well in Github? I would maybe expect using a Markdown header for each line, over bold.

@o-murphy
Copy link
Author

o-murphy commented Jun 9, 2025 •
edited
Loading

Hi @o-murphy thank you for this MR. The documentation looks comprehensive and well-structured. Thumbs up from me :)

One thing I am not sure about is the formatting of the steps - does that render well in Github? I would maybe expect using a Markdown header for each line, over bold.

It looks like padded numeric sections for each step with the same paddings for code blocks, good I mean, but If you wish I can change it

image

So do you want me to change 1, 2, 3 to section headers like bellow?

#### Ensure Static Library Development Packages:
...
#### Build MicroPython with `LDFLAGS_EXTRA="-static"`:
...
#### Verification
...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
docs port-unix
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@o-murphy @jonnor