Repository files navigation

“Zero setup” cross compilation and “cross testing” of Rust crates

This project is developed and maintained by thecross-rs team.It was previously maintained by the Rust Embedded Working Group Tools team.New contributors are welcome! Please join ourMatrix room and say hi.

`cross test`ing a crate for the aarch64-unknown-linux-gnu target

• cross will provide all the ingredients needed for cross compilation withouttouching your system installation.

• cross provides an environment, cross toolchain and cross compiled libraries,that produces the most portable binaries.

• “cross testing”,cross can test crates for architectures other than i686 andx86_64.

• The stable, beta and nightly channels are supported.

See ourGetting Started guide for detailedinstallation instructions.

• rustup
• A Linux kernel withbinfmt_misc support is required for cross testing.

One of these container engines is required. If both are installed,cross willdefault todocker.

• Docker. Note that on Linux non-sudo users need to be in thedocker group or use rootless docker.Read the container engineinstall guide for the required installation and post-installation steps. Requires version 20.10 (API 1.40) or later.
• Podman. Requires version 3.4.0 or later.

cargo install cross --git https://github.com/cross-rs/cross

It's also possible to directly download the pre-compiledreleasebinaries or usecargo-binstall.

cross has the exact same CLI asCargobut relies on Docker or Podman. For Docker, you'll have to startthe daemon before you can use it.

# (ONCE PER BOOT, on Linux)# Start the Docker daemon, if it's not already running using systemd# on WSL2 and other systems using SysVinit, use `sudo service docker start`.$ 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

Additional documentation can be found on thewiki or thedocs/ subfolder.

You have four options to configurecross. All of these options use the TOMLformat for configuration and the possible configuration values are documentedhere.

You can directly setconfiguration values in yourCargo.tomlfile, under the[workspace.metadata.cross] table, i.e. key prefix. An exampleconfig snippet would look like this:

[workspace.metadata.cross.target.aarch64-unknown-linux-gnu]# Install libssl-dev:arm64, see <https://github.com/cross-rs/cross/blob/main/docs/custom_images.md#adding-dependencies-to-existing-images>pre-build = ["dpkg --add-architecture $CROSS_DEB_ARCH","apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"][workspace.metadata.cross.target.armv7-unknown-linux-gnueabi]image ="my/image:latest"[workspace.metadata.cross.build]env.volumes = ["A_DIRECTORY=/path/to/volume"]

You can put yourconfiguration inside aCross.toml filein your project root directory.

By setting theCROSS_CONFIG environment variable, you can tellcross whereit should search for the config file. This way you are not limited to aCross.toml file in the project root.

Besides the TOML-based configuration files, config can be passed throughenvironment variables, too.

When runningcross from inside a container,cross needs access tothe hosts docker daemon itself. This is normally achieved by mounting thedocker daemons socket/var/run/docker.sock. For example:

$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v .:/project \  -w /project my/development-image:tag cross build --target mips64-unknown-linux-gnuabi64

The image runningcross requires the rust development tools to be installed.

With this setupcross must find and mount the correct host paths into thecontainer used for cross compilation. This includes the original projectdirectory as well as the root path of the parent container to give access tothe rust build tools.

To informcross that it is running inside a container setCROSS_CONTAINER_IN_CONTAINER=true.

A development or CI container can be created like this:

FROM rust:1# set CROSS_CONTAINER_IN_CONTAINER to inform `cross` that it is executed from within a containerENV CROSS_CONTAINER_IN_CONTAINER=true# install `cross`RUN cargo install cross...

Limitations: Finding the mount point for the containers root directory iscurrently only available for the overlayfs2 storage driver. In order to accessthe parent containers rust setup, the child container mounts the parentsoverlayfs. The parent must not be stopped before the child container, as theoverlayfs can not be unmounted correctly by Docker if the child container stillaccesses it.

By default,cross tries to useDocker orPodman, in that order.If you want to choose a container engine explicitly, you can set thebinary name (or path) using theCROSS_CONTAINER_ENGINEenvironment variable.

For example in case you want usePodman, you can setCROSS_CONTAINER_ENGINE=podman.

A target is considered as “supported” ifcross can cross compile a“non-trivial” (binary) crate, usually Cargo, for that target.

Testing support (cross test) is more complicated. It relies onQEMUemulation, so testing may fail due to QEMU bugs rather than bugs in your crate.That said, a target has a ✓ intest column of the table below if it can runthecompiler-builtins test suite.

Also, testing is very slow.cross test runs units testssequentially becauseQEMU gets upset when you spawn multiple threads. This means that, if one of yourunit tests spawns threads, then it's more likely to fail or, worst, neverterminate.

[1] libc = bionic; Only works with native tests, that is, tests that do notdepends on the Android Runtime. For i686 some tests may fails with theerrorassertion failed: signal(libc::SIGPIPE, libc::SIG_IGN) != libc::SIG_ERR, seeissue#140 for more information.

[2] Nostd component available.

[3] For some *BSD and Solaris targets, the libc column indicates the OSrelease version from which libc was extracted.

[4] libc = newlib

[5] Must changeimage = "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos" inCross.toml for[target.x86_64-unknown-linux-gnu] to use theCentOS7-compatible target.

[6] libc = emscripten and GCC = clang

[7] Must changeimage = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos" inCross.toml for[target.aarch64-unknown-linux-gnu] to use theCentOS7-compatible target.

Additional Dockerfiles for other targets can be found incross-toolchains. These includeMSVC and Apple Darwin targets, which we cannot ship pre-built images of.

You can set the QEMU_STRACE variable when you usecross run to get a backtraceof system calls from “foreign” (non x86_64) binaries.

$ cargo new --bin hello && cd $_$ QEMU_STRACE=1 cross run --target aarch64-unknown-linux-gnu9 brk(NULL) = 0x00000040000230009 uname(0x4000823128) = 0(..)9 write(1,0xa06320,14)Hello, world! = 149 sigaltstack(0x4000823588,(nil)) = 09 munmap(0x0000004000b16000,16384) = 09 exit_group(0)

This crate is guaranteed to compile on stable Rust 1.77.2 and up. Itmightcompile with older versions but that may change in any new patch release.

Some cross-compilation targets require a later Rust version, and using Xargorequires a nightly Rust toolchain.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shall bedual licensed as above, without any additional terms or conditions.

Contribution to this crate is organized under the terms of theRust Code ofConduct, the maintainer of this crate, thecross-rs team, promisesto intervene to uphold that code of conduct.