rust-musl-cross

🚀 Help me to become a full-time open-source developer by sponsoring me on GitHub

Docker images for compiling static Rust binaries using musl-cross-make, inspired by rust-musl-builder

Prebuilt images

Currently we have the following prebuilt Docker images on Docker Hub, supports x86_64(amd64) and aarch64(arm64) architectures.

Rust toolchain	Cross Compile Target	Docker Image Tag
stable	aarch64-unknown-linux-musl	aarch64-musl
stable	arm-unknown-linux-musleabi	arm-musleabi
stable	arm-unknown-linux-musleabihf	arm-musleabihf
stable	armv5te-unknown-linux-musleabi	armv5te-musleabi
stable	armv7-unknown-linux-musleabi	armv7-musleabi
stable	armv7-unknown-linux-musleabihf	armv7-musleabihf
stable	i586-unknown-linux-musl	i586-musl
stable	i686-unknown-linux-musl	i686-musl
stable	loongarch64-unknown-linux-musl	loongarch64-musl
nightly	mips-unknown-linux-musl	mips-musl
nightly	mips64-openwrt-linux-musl	mips64-openwrt-musl
nightly	mips64-unknown-linux-muslabi64	mips64-muslabi64
nightly	mips64el-unknown-linux-muslabi64	mips64el-muslabi64
nightly	mipsel-unknown-linux-musl	mipsel-musl
nightly	powerpc64-unknown-linux-musl	powerpc64-musl
stable	powerpc64le-unknown-linux-musl	powerpc64le-musl
stable	riscv64gc-unknown-linux-musl	riscv64gc-musl
nightly	s390x-unknown-linux-musl	s390x-musl
stable	x86_64-unknown-linux-musl	x86_64-musl

To use armv7-unknown-linux-musleabihf target for example, first pull the image:

docker pull ghcr.io/rust-cross/rust-musl-cross:armv7-musleabihf
# Also available on Docker Hub
# docker pull messense/rust-musl-cross:armv7-musleabihf

Then you can do:

alias rust-musl-builder='docker run --rm -it -v "$(pwd)":/home/rust/src ghcr.io/rust-cross/rust-musl-cross:armv7-musleabihf'
rust-musl-builder cargo build --release

This command assumes that $(pwd) is readable and writable. It will output binaries in armv7-unknown-linux-musleabihf. At the moment, it doesn't attempt to cache libraries between builds, so this is best reserved for making final release builds.

Docker-convention alias tags

Several images are also published under Docker-convention tag names that match Docker's TARGETARCH build arg (e.g. amd64, arm64). The alias tag format is <TARGETARCH>-musl:

Primary tag	Alias tag
aarch64-musl	arm64-musl
x86_64-musl	amd64-musl
i686-musl	386-musl
loongarch64-musl	loong64-musl
powerpc64-musl	ppc64-musl
powerpc64le-musl	ppc64le-musl
mips64-muslabi64	mips64-musl
mips64el-muslabi64	mips64le-musl
mipsel-musl	mipsle-musl
riscv64gc-musl	riscv64-musl

This lets multi-platform Dockerfiles use TARGETARCH directly without any explicit build args:

ARG TARGETARCH=amd64
FROM ghcr.io/rust-cross/rust-musl-cross:${TARGETARCH}-musl AS builder

Docker sets TARGETARCH automatically from the native runner platform, so the same docker buildx build --platform linux/amd64,linux/arm64 command selects the right image on each platform with no extra configuration.

Note: The arm variants (arm-musleabi, arm-musleabihf, armv7-musleabi, armv7-musleabihf, armv5te-musleabi) are not aliased because they all map to GOARCH=arm, making a single canonical arm-musl alias ambiguous.

How it works

rust-musl-cross uses musl-libc, musl-gcc with the help of musl-cross-make to make it easy to compile, and the new rustup target support.

Use beta/nightly Rust

Currently we install stable Rust by default, if you want to switch to beta/nightly Rust, you can do it by extending from our Docker image, for example to use beta Rust for target x86_64-unknown-linux-musl:

FROM ghcr.io/rust-cross/rust-musl-cross:x86_64-musl
RUN rustup update beta && \
    rustup target add --toolchain beta x86_64-unknown-linux-musl

Strip binaries

You can use the musl-strip command inside the image to strip binaries, for example:

docker run --rm -it -v "$(pwd)":/home/rust/src ghcr.io/rust-cross/rust-musl-cross:armv7-musleabihf musl-strip /home/rust/src/target/release/example

License

Licensed under The MIT License