Skip to content

Configuration

Jump to bottom
Alexander Huszagh edited this page Jun 16, 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]
build-std = false                              # do not build the std library. has precedence over xargo
xargo = true                                   # enable the use of xargo by default
default-target = "x86_64-unknown-linux-gnu"    # use this target if none is explicitly provided
pre-build = [                                  # additional commands to run prior to building the package
    "dpkg --add-architecture $CROSS_DEB_ARCH", 
    "apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
]

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.

build.dockerfile

The build.dockerfile key lets you provide a custom Docker image for all targets, except those specified target.TARGET.dockerfile. You probably do not mean to use this. The value can be provided as either a table or a string. If build.dockerfile is set to a string, it's equivalent to setting build.dockerfile.file to that value. For example, using only a string:

[build]
dockerfile = "./Dockerfile"

Or using a table:

[build.dockerfile]
file = "./Dockerfile"         # the dockerfile to use relative to the `Cargo.toml`
context = "."                 # the context folder to build the script in. defaults to `.`
build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg

target.TARGET

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

[target.aarch64-unknown-linux-gnu]
build-std = false          # always build the std library. has precedence over xargo
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"]

target.TARGET.dockerfile

The target.(...).dockerfile key lets you provide a custom Docker image for the given target. The value can be provided as either a table or a string. If target.TARGET.dockerfile is set to a string, it's equivalent to setting target.(...).dockerfile.file to that value. For example, using only a string:

[target.aarch64-unknown-linux-gnu]
dockerfile = "./Dockerfile"

Or using a table:

[target.aarch64-unknown-linux-gnu.dockerfile]
file = "./Dockerfile"         # the dockerfile to use relative to the `Cargo.toml`
context = "."                 # the context folder to build the script in. defaults to `.`
build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg

Custom Images

Custom images generated from config dockerfile or pre-build keys will export CROSS_DEB_ARCH, which allows you to install packages from Ubuntu/Debian repositories without having to specify the exact architecture. For example, to install OpenSSL for the target, you can do:

[target.aarch64-unknown-linux-gnu]
pre-build = [
  "dpkg --add-architecture $CROSS_DEB_ARCH", 
  "apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
]

Here, CROSS_DEB_ARCH will automatically evaluate to arm64, without you having to explicitly provide it.

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_CONTAINER_IN_CONTAINER: Inform cross that it is running inside a container (example: true, see the FAQ).
  • CROSS_CONTAINER_OPTS: Additional arguments to provide to the container engine during $engine run (example: --env MYVAR=1 where engine=docker).
  • 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).
  • CROSS_CUSTOM_TOOLCHAIN: Specify that rustup is using a custom toolchain, and therefore should not try to add targets/install components. Useful with cargo-bisect-rustc.
  • QEMU_STRACE: Get a backtrace of of system calls from “foreign” (non x86_64) binaries when using cross run.
  • CARGO_BUILD_TARGET: Sets the default target, similar to specifying --target.

All config file options can also be specified using environment variables. For example, setting CROSS_BUILD_XARGO=1 is identical to setting build.xargo = true, and CROSS_TARGET_AARCH64_UNKNOWN_LINUX_GNU_XARGO=1 is identical to target.aarch64-unknown-linux-gnu.xargo = true.

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