Getting Started

New to cross? Cross-compilation? Container engines? Here's how to get up-and-running.

Table of Contents

• Installing Cross
• Installing A Container Engine
• Cross-Compiling Your First Package

Installing Cross

Installing Rust via Rustup

cross requires a rustup installation of Rust. To do so, the recommended instructions are documented here, but might differ on some platforms. For UNIX-like systems, run the following command in a terminal and follow the instructions to install Rust and add Rust to the path:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download rustup-init.exe or following the other installation methods, say, to install from a package manager.

On some platforms, such as NixOS, you might need to use a package manager since the default rustup install will fail. On NixOS, you should run the following, which will install rustup and the latest stable release of Rust.

nix-env -i rustup
rustup toolchain install stable

Note that you might need additional tools on some platforms to get rustc and cargo working. On UNIX-like systems, this generally means an install of GCC or Clang. For example, on NixOS you will likely need to install GCC via nix-env -i gcc and then go into a GCC and Rust shell (nix-shell -p gcc rustup). On Alpine, you'll need to run apk add libgcc gcc musl-dev. Exact instructions will differ by OS and Linux distro, feel free to ask on the discussion or our Matrix room if you have any questions.

Installing Cross

Once cargo is installed via rustup, and the necessary additional tools are present, you can now install cross via cargo:

cargo install cross
# Optionally, if you have cargo-binstall, you can install via pre-built binary
cargo binstall cross

Once cross is installed, you need a container engine and you can start cross-compiling.

Installing A Container Engine

On Windows and macOS, we generally recommend you use Docker unless you know what you're doing. Docker Desktop install instructions can be found here. On Linux, you can either install via Docker Engine, Docker Desktop or Podman. We generally recommend Podman, since it runs rootless by default. If you choose to use Docker, make sure you add users to the docker group so it can be run without sudo (note that this has security implications) or use rootless^† Docker.

If you use Docker Desktop for Windows, ensure you're using the WSL2. Follow the WSL2 installation instructions to enable the WSL2 backend in docker.

Once your container engine is installed, you can check that it is running via:

# or use podman, if installed
$ docker ps -a

^†Using rootless docker also requires setting the environment variable CROSS_ROOTLESS_CONTAINER_ENGINE=1.

Cross-Compiling Your First Package

Once both cross and the container engine are installed, you can build your first package: this is all that's required.

$ cargo init --bin hello
$ cd hello
$ cross run --target aarch64-unknown-linux-gnu
   Compiling hello v0.1.0 (/project)
    Finished dev [unoptimized + debuginfo] target(s) in 0.64s
     Running `/linux-runner aarch64 /target/aarch64-unknown-linux-gnu/debug/hello`
Hello, world!

This will automatically install the Rust target required and the Docker image containing the toolchain to cross-compile your target.

If you get an error similar to error: toolchain 'stable-x86_64-unknown-linux-gnu' does not support components, try reinstalling that toolchain with rustup.

$ rustup toolchain uninstall stable-x86_64-unknown-linux-gnu
$ rustup toolchain install stable-x86_64-unknown-linux-gnu --force-non-host