Configuration

Documentation for how to configure cross through config files and environment variables.

Table of Contents

• Config File
• Environment Variables
• Cargo Configuration
• Unstable Features

Config File

You can place a Cross.toml file in the root of your Cargo project or use a CROSS_CONFIG environment variable to tweak cross's behavior.

Format

The cross configuration in the Cross.toml file, can contain the following elements:

build

The build key allows you to set global variables, e.g.:

[build]
xargo = true
default-target = "x86_64-unknown-linux-gnu"

build.env

With the build.env key you can globally set volumes that should be mounted in the Docker container or environment variables that should be passed through.

For example:

[build.env]
volumes = ["VOL1_ARG", "VOL2_ARG=/path/to/volume"]
passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]

Note how in the environment variable passthrough, we can provide a definition for the variable as well. VAR1_ARG will be the value of the environment variable on the host, while VAR2_ARG will be VALUE. Likewise, the path to the volume for VOL1_ARG will be the value of the environment variable on the host, while VOL2_ARG will be /path/to/volume.

target.TARGET

The target key allows you to specify parameters for specific compilation targets.

[target.aarch64-unknown-linux-gnu]
xargo = false              # disable the use of xargo
image = "test-image"       # use a different image for the target
runner = "custom-runner"   # wrapper to run the binary

target.TARGET.env

The target key allows you to specify environment variables that should be used for a specific compilation target. This is similar to build.env, but allows you to be more specific per target.

[target.x86_64-unknown-linux-gnu.env]
volumes = ["VOL1_ARG", "VOL2_ARG=/path/to/volume"]
passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]

Environment Variables

Cross can be further customized by setting certain environment variables.

• CROSS_CONTAINER_ENGINE: The container engine to run cross in. Defaults to docker then podman, whichever is found first (example: docker, see the FAQ).
• XARGO_HOME: Home for xargo (example: ~/.xargo).
• NIX_STORE: The directory for the Nix store (example: /nix/store).
• CROSS_CONTAINER_UID: Set the user identifier for the cross command (example: 1000).
• CROSS_CONTAINER_GID: Set the group identifier for the cross command (example: 1000).
• CROSS_DOCKER_IN_DOCKER: Inform cross that it is running inside a container (example: true, see the FAQ).
• DOCKER_OPTS: Additional arguments to provide to docker run (example: --env MYVAR=1).
• CROSS_CONFIG: Specify cross config behavior (see Config File).
• CROSS_DEBUG: Print debugging information for cross.
• CROSS_COMPATIBILITY_VERSION: Use older cross behavior (example: 0.2.1).
• QEMU_STRACE: Get a backtrace of of system calls from “foreign” (non x86_64) binaries when using cross run.

Cargo Configuration

When cross-compiling, cargo does not use environment variables such as RUSTFLAGS, and must be provided using CARGO_TARGET_${TARGET}_${OPTION}. Please note that some of these may be provided by the image themselves, such as runners, and should be provided with caution. A list of important flags includes:

• CARGO_TARGET_${TARGET}_LINKER: specify a custom linker passed to rustc.
• CARGO_TARGET_${TARGET}_RUNNER: specify the wrapper to run executables.
• CARGO_TARGET_${TARGET}_RUSTFLAGS: add additional flags passed to rustc.

Any of the following flags can be provided, and are converted to uppercase. For example, changing foo-bar would be provided as CARGO_TARGET_${TARGET}_FOO_BAR.

For example, to run binaries on i686-unknown-linux-gnu with Qemu, first create a custom image containing Qemu, and add the following to Cross.toml:

[target.i686-unknown-linux-gnu.env]
passthrough = ["CARGO_TARGET_I686_UNKNOWN_LINUX_GNU_RUNNER"]

Then, run with the following command:

CARGO_TARGET_I686_UNKNOWN_LINUX_GNU_RUNNER=qemu-i386 cross run ...

Unstable Features

Certain unstable features can enable additional functionality useful to cross-compiling. Note that these are unstable, and may be removed at any time (particularly if the feature is stabilized or removed), and will only be used on a nightly channel.

• CROSS_UNSTABLE_ENABLE_DOCTESTS: enable or disable running doctests (example: true).