"Zero setup" cross compilation and "cross testing" of Rust crates
Disclaimer: Only works on a x86_64 Linux host (e.g. Travis CI is supported)
crosswill provide all the ingredients needed for cross compilation without touching your system installation.
crossprovides an environment, cross toolchain and cross compiled libraries (e.g. OpenSSL), that produces the most portable binaries.
crosscan test crates for architectures other than i686 and x86_64.
The stable, beta and nightly channels are supported.
$ cargo install cross
cross has the exact same CLI as Cargo
but as it relies on Docker you'll have to start the daemon before you can use
# (ONCE PER BOOT) # Start the Docker daemon, if it's not already running $ sudo systemctl start docker # MAGIC! This Just Works $ cross build --target aarch64-unknown-linux-gnu # EVEN MORE MAGICAL! This also Just Works $ cross test --target mips64-unknown-linux-gnuabi64 # Obviously, this also Just Works $ cross rustc --target powerpc-unknown-linux-gnu --release -- -C lto
You can place a
Cross.toml file in the root of your Cargo project to tweak
Custom Docker images
The default Docker image that
cross uses provides a C environment that tries
to cover the most common cross compilation cases. However, it can't cover every
single use case out there. When the default image is not enough, you can use the
target.$TARGET.image field in
Cross.toml to use custom Docker image for a
[target.aarch64-unknown-linux-gnu] image = "my/image:tag"
In the example above,
cross will use a image named
my/image:tag instead of
the default one. Normal Docker behavior applies, so:
Docker will first look for a local image named
If it doesn't find a local image, then it will look in Docker Hub.
image:tagis specified, then Docker won't look in Docker Hub.
tagis omitted, then Docker will use the
It's recommended to base your custom image on the default Docker image that
$VERSION is cross's version).
This way you won't have to figure out how to install a cross C toolchain in your
custom image. Example below:
FROM japaric/aarch64-unknown-linux-gnu:v0.1.4 RUN dpkg --add-architecture arm64 && \ apt-get update && \ apt-get install libfoo:arm64
$ docker build -t my/image:tag path/to/where/the/Dockerfile/resides
Use Xargo instead of Cargo
cargo to build your Cargo project unless you are
building for one of the
thumbv*-none-eabi* targets; in that case, it uses
xargo. However, you can use the
Cross.toml to force the use of
# all the targets will use `xargo` [build] xargo = true
# only this target will use `xargo` [target.aarch64-unknown-linux-gnu] xargo = true
xargo = false has no effect as you can't use
cargo with targets
that only support
A target is considered as "supported" if
cross can cross compile a
"non-trivial" (binary) crate, usually Cargo, for that target.
Testing support is more complicated. It relies on QEMU user emulation, so
testing may sometimes fail due to QEMU bug sand not because there's a bug in the
crate. That being said,
cross test is assumed to "work" (
test column in the
table below) if it can successfully
Also, testing is very slow.
cross will actually run units tests sequentially
because QEMU gets upset when you spawn several threads. This also means that, if
one of your unit tests spawns several threads then it's more likely to fail or,
worst, "hang" (never terminate).
 For *BSD targets, the libc column indicates the OS release version from where libc was extracted.
std component available as of 2017-01-10
Caveats / gotchas
crosswill mount the Cargo project as READ ONLY. Thus, if any crate attempts to modify its "source", the build will fail. Well behaved crates should only ever write to
$OUT_DIRand never modify
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.