Targets & cross-compilation on cargo-feature-combinations

Configured targets

Mon, 01 Jan 0001 00:00:00 +0000

Configured targets#

Declaring a target list#

Declare workspace-wide targets in the workspace Cargo.toml:

[workspace.metadata.cargo-fc]
targets = [
 "x86_64-unknown-linux-gnu",
 "x86_64-pc-windows-msvc",
 "aarch64-apple-darwin",
]

Now cargo fc check visits every combination on every target.

Per-package target lists#

A package can override the workspace list, or opt out of it:

[package.metadata.cargo-fc]
# Run this package only on wasm (overrides the workspace list, does not merge).
targets = ["wasm32-unknown-unknown"]

The three states:

Value	Meaning
key missing	inherit the workspace target list
`targets = []`	opt out of the workspace list; use the single effective target
`targets = ["…"]`	this package’s own list (overrides, does not merge)

targets only selects which targets are visited. The target.'cfg(...)' overrides still shape the feature matrix for each concrete target.

Build drivers

Mon, 01 Jan 0001 00:00:00 +0000

Build drivers#

A “driver” is the program cargo fc invokes in place of cargo for each build. The default depends on whether you’re cross-compiling.

Why a driver#

Cross-compiling a crate with native-C build dependencies (for example aws-lc-sys, pulled in via rustls) needs a cross C toolchain — the host cc can’t target another OS. To make that transparent, when any non-host target is planned, cargo fc invokes cargo-zigbuild instead of plain cargo, so zig supplies the cross C compiler and linker for every target.

Installing targets

Mon, 01 Jan 0001 00:00:00 +0000

Installing missing targets#

By default cargo fc does not mutate the Rust toolchain. If a configured target’s rustup component isn’t installed, the build for that target fails as it normally would.

Opt in per invocation#

cargo fc check --install-missing-targets

This installs the missing target components with rustup before running. It’s an explicit opt-in because it may mutate the toolchain and use the network. When a +toolchain override is present, the same override is passed to rustup, so components land in the right toolchain.