In a Rust service built with Cargo, what goes in `.cargo/config.toml` so that `cargo build` and `cargo test` target aarch64 Linux from a laptop?
answer
- the config file, not the manifest
- a default triple for every command
- a table keyed by the triple
- a linker driver and an emulator wrapper
basics
~10 sSet [build] target to aarch64-unknown-linux-gnu, then add a [target.aarch64-unknown-linux-gnu] table whose linker names a cross linker such as aarch64-linux-gnu-gcc and whose runner names an emulator, which cargo run, test and bench use.
solid answer
~30 s`.cargo/config.toml` describes how this checkout builds, so cross-compiling settings live there; `Cargo.toml` has no linker key and warns about one as an unused manifest key. `[build] target = "aarch64-unknown-linux-gnu"` makes that triple the default for every command, with output under `target/aarch64-unknown-linux-gnu/`. A `[target.aarch64-unknown-linux-gnu]` table then sets `linker`, which Cargo passes to rustc as `-C linker=...`, and `runner`, a wrapper such as `qemu-aarch64 -L /usr/aarch64-linux-gnu` that `cargo run`, `cargo test` and `cargo bench` invoke with the compiled executable as its first argument. Every key also has an environment form, such as `CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER`, for CI images that bring their own toolchain.
code
toml · 7 lines# .cargo/config.toml at the repository root
[build]
target = "aarch64-unknown-linux-gnu"
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
runner = "qemu-aarch64 -L /usr/aarch64-linux-gnu"go deeper
Know that cross-compiling settings go in .cargo/config.toml, not Cargo.toml, and name the two keys: build.target and the linker under the triple's table.
Explain how Cargo applies each key: the default triple, -C linker on every rustc line for that triple, the runner wrapping run, test and bench, and the CARGO_TARGET_ environment forms.
Cover what the table does not reach: host-built build scripts and proc macros, C compilers in dependencies, system libraries in the sysroot, and per-machine overrides through environment variables.
Decide what the repository config commits to and what each laptop or CI image supplies, so one checkout builds the same way everywhere without hard-coding anyone's toolchain path.
## Why the settings live in config, not in Cargo.toml Cargo reads two kinds of TOML file, and cross-compiling belongs to only one of them: - **`Cargo.toml`**, the manifest, describes the package: its name, its dependencies, its features. It is published with the crate and means the same thing on every machine. - **`.cargo/config.toml`** describes how builds run in this directory tree: which target to build by default, which linker and wrapper programs to call, where sources come from. Checked into the repository, it applies to everyone who runs Cargo inside it. A linker path is a fact about a machine, not about a package, so `Cargo.toml` has no place for it. Put `[target.aarch64-unknown-linux-gnu] linker = "..."` in the manifest and Cargo 1.99.1 says `warning: Cargo.toml: unused manifest key: target.aarch64-unknown-linux-gnu.linker` and ignores it. (A `[target.'cfg(...)'.dependencies]` table in the manifest is a different feature: it chooses dependencies per platform, which belongs with dependency specifications.) ## The three keys a cross build needs | Key | What Cargo does with it | Environment form | |---|---|---| | `build.target` | default triple for build, check, run, test and the rest; `--target` overrides it, `cargo install` ignores it | `CARGO_BUILD_TARGET` | | `target.<triple>.linker` | passed to rustc as `-C linker=...` whenever that triple is compiled | `CARGO_TARGET_<TRIPLE>_LINKER` | | `target.<triple>.runner` | the program that `cargo run`, `cargo test` and `cargo bench` call, with the executable as an argument | `CARGO_TARGET_<TRIPLE>_RUNNER` | In an environment name the triple is upper-cased and its dashes become underscores: `CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUNNER`. ## What happens during the build 1. Cargo resolves the target: the `--target` flag if given, else `build.target` from config or `CARGO_BUILD_TARGET`, else the host. 2. Every rustc invocation for the package and its normal dependencies receives `--target aarch64-unknown-linux-gnu` and `-C linker=aarch64-linux-gnu-gcc`; `cargo build -v` prints both on each command line. 3. Build scripts and procedural macros are compiled for the host, because they run during the build. The aarch64 table does not apply to them. 4. For `cargo run`, `cargo test` and `cargo bench`, Cargo starts the runner with the path of the compiled executable followed by the program's own arguments. Without a runner, Cargo executes the binary directly, which fails for a foreign architecture. The host is a target like any other: a `[target.aarch64-apple-darwin]` table on an aarch64 macOS laptop applies to plain `cargo build` runs with no `--target` at all. To confirm what Cargo resolved, run `cargo build -v` and read one rustc command line; the `--target` and `-C linker=` arguments are printed there, and a configured runner appears in the `Running` line of `cargo run`. ## Paths, names and families of targets - A value without a path separator, such as `aarch64-linux-gnu-gcc`, is looked up on `PATH`. - A relative value with a separator, such as `tools/link.sh`, is resolved from the directory that contains `.cargo/`, so it works from any subdirectory. - `runner` may be a space-separated string or an array; use the array form when the program's path contains spaces. - A `[target.'cfg(target_os = "linux")']` table sets the same keys for a whole family of triples. If a triple table and a `cfg` table both set `linker` or `runner`, the triple wins; two matching `cfg` tables that both set `linker`, or both set `runner`, are an error, while `rustflags` from every matching table are joined. - `cfg` tables match only the compiler's built-in configuration and `--cfg` flags: not `debug_assertions`, not `test`, not Cargo features, not values from build scripts. ## Where it still goes wrong - **C code in dependencies.** The linker setting does not choose the C compiler that a dependency's build script calls; that is configured separately, as the build-script material covers. - **System libraries.** Anything the binary links against, such as OpenSSL, must exist for aarch64 Linux in the cross toolchain's sysroot. - **A config the build never reads.** Cargo finds `.cargo/config.toml` by walking up from the directory it is started in, so a CI step that runs Cargo from a parent directory with `--manifest-path` silently builds for the host instead. - **Tests under emulation.** With a runner, `cargo test` launches each test binary through the emulator, so tests run, only more slowly. - **Per-developer differences.** A team that needs one linker on Linux laptops and another on macOS can keep the shared keys in the repository config and let each machine override them through its own config or environment.
- A teammate puts `linker = "aarch64-linux-gnu-gcc"` under `[target.aarch64-unknown-linux-gnu]` in `Cargo.toml`. What happens?Cargo ignores it and warns `unused manifest key: target.aarch64-unknown-linux-gnu.linker`. The manifest's `[target]` tables only hold platform-specific dependency tables; linker, runner and rustflags are configuration and belong in `.cargo/config.toml` or the matching `CARGO_TARGET_<TRIPLE>_*` environment variables.
- How does a CI image use its own cross linker without editing the repository's config?It exports `CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER` with its linker's name or path. Environment variables take precedence over every config file, so the image's value replaces the repository's `linker` for that triple only, while the rest of `.cargo/config.toml` still applies.
- Does setting `[build] target` change what `cargo install` builds?No. The config reference marks `build.target` as ignored by `cargo install`, which builds for the host unless you pass `--target` on its command line. That keeps a repository's cross-compiling default from installing a tool that the developer's own machine cannot run.
- The linker for a target is set in Cargo.toml next to the dependencies.
- A runner only affects cargo run; cargo test still executes test binaries directly.
- build.target forces --target, so it cannot be overridden from the command line.
- The [target.<triple>] linker also links build scripts and procedural macros.
- Relative linker paths in config are resolved from whatever directory cargo runs in.