Skip to content

Configuration

Jump to bottom
Alexander Huszagh edited this page Jun 3, 2022 · 32 revisions

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

Table of Contents

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                                   # enable the use of xargo by default
default-target = "x86_64-unknown-linux-gnu"    # use this target if none is explicitly provided

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).

Basics

Advanced

Cross Development

Clone this wiki locally