This is a Linux Docker image based on ekidd/rust-musl-builder but using the latest Debian 12-slim (Bookworm).
It contains essential tools for cross-compile Rust projects such as Linux static binaries via musl-libc / musl-gcc (x86_64-unknown-linux-musl
) and macOS binaries (x86_64-apple-darwin
) via osxcross just using the same Linux image.
The Docker image is multi-arch (amd64
and arm64
) so you can use them in native environments.
Also, it is possible to cross-compile arm64
Linux or Darwin apps from the x86_64
Docker image variant.
By default, the working directory is /root/src
.
Below are the default toolchains included in the Docker image.
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
sh -c "cargo build --release --target x86_64-unknown-linux-musl"
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
sh -c "cargo build --release --target x86_64-unknown-linux-gnu"
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
sh -c "cargo build --release --target x86_64-apple-darwin"
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
sh -c "cargo build --release --target aarch64-unknown-linux-gnu"
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
sh -c "cargo build --release --target aarch64-unknown-linux-musl"
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
sh -c "cargo build --release --target aarch64-apple-darwin"
It's known that the CARGO_HOME
points to $HOME/.cargo
by default (/root/.cargo
in this case). However, if you want to use a custom Cargo home directory then make sure to copy the Cargo config
file to the particular directory like cp "$HOME/.cargo/config" "$CARGO_HOME/"
before to cross-compile your program. Otherwise, you could face a linking error when for example you want to cross-compile to an x86_64-apple-darwin
target.
You can also use the image as a base for your Dockerfile:
FROM joseluisq/rust-linux-darwin-builder:1.80.1
You can also use o32-clang(++) and o64-clang(++) as a normal compiler.
Notes:
- The current 11.3 SDK does not support i386 anymore. Use <= 10.13 SDK if you rely on i386 support.
- The current 11.3 SDK does not support libstdc++ anymore. Use <= 10.13 SDK if you rely on libstdc++ support.
Examples:
Example usage:
Example 1: CC=o32-clang ./configure --host=i386-apple-darwin22.4
Example 2: CC=i386-apple-darwin22.4-clang ./configure --host=i386-apple-darwin22.4
Example 3: o64-clang -Wall test.c -o test
Example 4: x86_64-apple-darwin22.4-strip -x test
!!! Use aarch64-apple-darwin22.4-* instead of arm64-* when dealing with Automake !!!
!!! CC=aarch64-apple-darwin22.4-clang ./configure --host=aarch64-apple-darwin22.4 !!!
!!! CC="aarch64-apple-darwin22.4-clang -arch arm64e" ./configure --host=aarch64-apple-darwin22.4 !!!
Below is a simple example of using a Makefile
to cross-compile a Rust app.
Notes:
- A hello world app is used.
- A custom directory is used below as a working directory instead of
/root/src
.
Create a Makefile:
compile:
@docker run --rm -it \
-v $(PWD):/app/src \
-w /app/src \
joseluisq/rust-linux-darwin-builder:1.80.1 \
make cross-compile
.PHONY: compile
cross-compile:
@echo
@echo "1. Cross compiling example..."
@rustc -vV
@echo
@echo "2. Compiling application (linux-musl x86_64)..."
@cargo build --manifest-path=tests/hello-world/Cargo.toml --release --target x86_64-unknown-linux-musl
@du -sh tests/hello-world/target/x86_64-unknown-linux-musl/release/helloworld
@echo
@echo "3. Compiling application (apple-darwin x86_64)..."
@cargo build --manifest-path=tests/hello-world/Cargo.toml --release --target x86_64-apple-darwin
@du -sh tests/hello-world/target/x86_64-apple-darwin/release/helloworld
.PHONY: cross-compile
Just run the makefile compile
target, then you will see two release binaries x86_64-unknown-linux-musl
and x86_64-apple-darwin
.
make compile
# 1. Cross compiling example...
# rustc 1.80.1 (3f5fd8dd4 2024-08-06)
# binary: rustc
# commit-hash: 3f5fd8dd41153bc5fdca9427e9e05be2c767ba23
# commit-date: 2024-08-06
# host: x86_64-unknown-linux-gnu
# release: 1.80.1
# LLVM version: 18.1.7
# 2. Compiling application (linux-musl x86_64)...
# Finished release [optimized] target(s) in 0.01s
# 1.2M tests/hello-world/target/x86_64-unknown-linux-musl/release/helloworld
# 3. Compiling application (apple-darwin x86_64)...
# Finished release [optimized] target(s) in 0.01s
# 240K tests/hello-world/target/x86_64-apple-darwin/release/helloworld
For more details take a look at Cross-compiling Rust from Linux to macOS by James Waples.
See joseluisq/rust-linux-darwin-builder#7
If some of your crates require C bindings and you run into a compilation or linking error, try to use Clang for C/C++ builds.
For example to cross-compile to Macos:
CC=o64-clang \
CXX=o64-clang++ \
cargo build --target x86_64-apple-darwin
# Or
cargo build --target aarch64-apple-darwin
Until
v1.42.0
of this project, one old OpenSSL releasev1.0.2
was used.
Now, sincev1.43.x
or greater, OpenSSLv1.1.1
(LTS) is used which is supported until2023-09-11
.
View more at https://www.openssl.org/policies/releasestrat.html.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in current work by you, as defined in the Apache-2.0 license, shall be dual licensed as described below, without any additional terms or conditions.
Feel free to send some Pull request or file an issue.
This work is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0).
© 2019-present Jose Quintana