MUSL Linux Support #69
Description
musl Linux Support (Static Builds)
Goal: Enable fully-static encoderfile binaries targeting musl-based Linux distributions.
Encoderfile aims to be a single-file, dependency-free deployment artifact. While Rust’s musl targets make static builds straightforward, ONNX Runtime currently complicates this—its build process and some of its assumptions are closely tied to glibc. Several community members have reported success compiling ONNX Runtime for musl, but there’s no standard or documented approach.
A minimal musl-compatible build is still a win—we don’t need full ORT functionality to support this target.
This issue tracks investigation and potential support for musl-based builds.
Background
Encoderfile packages transformer encoders into a standalone executable using ONNX Runtime under the hood. Supporting musl Linux would allow Encoderfile to run cleanly in:
- minimal container images (e.g.,
scratch,distroless, Alpine) - static or sealed deployment environments
- embedded or security-restricted systems
Having a statically linked, musl-based binary fits Encoderfile’s design goals: predictable, hermetic, and free of external dependencies at runtime.
Current Challenges
Static builds work well in Rust, but ONNX Runtime presents several obstacles:
- The standard ORT build configuration expects glibc.
- Some kernels and ops depend on glibc-specific APIs.
- Contrib ops and certain execution providers fail to compile under musl.
- Cross-compilation (e.g., x86_64 → aarch64-musl) introduces additional friction.
- Even successful builds may result in missing symbols or runtime errors.
These aren’t Encoderfile-specific limits—they come from upstream ONNX Runtime assumptions.
What Would Help
If you have experience with any of the following, input would be extremely valuable:
- building ONNX Runtime against musl toolchains
- configuring ORT’s CMake build for musl
- producing minimal/static ORT builds that work under musl
- knowing which components or kernels need to be disabled for compatibility
The end goal is to make something like:
cargo build --target x86_64-unknown-linux-musl --release
produce a functional Encoderfile binary.
Possible Approaches
We’re currently exploring:
- Creating custom ORT build scripts that use musl toolchains
- Using ORT’s minimal build mode to reduce incompatible ops
- Disabling problematic execution providers
- Adding a documented, reproducible musl build pipeline
- Publishing prebuilt ORT artifacts compiled against musl
Feedback on which direction is most realistic would be helpful.
Why It Matters
Supporting musl expands Encoderfile’s portability and makes it easier to run in environments where static binaries are preferred or required. It aligns with the project’s goals of simplicity, predictability, and low operational overhead.
If you’ve attempted musl builds of ONNX Runtime—successful or not—please share any insights or references.