skip to content

A Cargo build script enables a NEON code path with cargo::rustc-cfg; why must it read CARGO_CFG_TARGET_ARCH instead of cfg!, and what else must it print?

level: seniorimportance: should knowfreq 20%

answer

  1. two machines in one build
  2. the script runs on the host
  3. Cargo describes the target in env vars
  4. declare custom cfgs since 1.80
  5. declare on every run

basics

~20 s

A build script is compiled for and runs on the host, so cfg! describes the host, not the target being built; CARGO_CFG_TARGET_ARCH describes the target. Since Cargo 1.80 it must also print cargo::rustc-check-cfg=cfg(tinyz_neon) on every run, or rustc warns.

solid answer

~40 s

In `cargo build --target wasm32-wasip1` on an aarch64 Mac, `build.rs` is compiled for and runs on the Mac, so `cfg!(target_arch = "aarch64")` inside it is `true` while the crate is being built for `wasm32`. Cargo describes the real target in `CARGO_CFG_*` variables (`CARGO_CFG_TARGET_ARCH=wasm32`, plus `TARGET=wasm32-wasip1`), so the script reads those and prints `cargo::rustc-cfg=tinyz_neon` only when the target is aarch64. Since Cargo 1.80 check-cfg is on by default: an undeclared custom name makes rustc warn ``unexpected `cfg` condition name: `tinyz_neon` ``, so the script also prints `cargo::rustc-check-cfg=cfg(tinyz_neon)`, unconditionally, because declaring it only when it is set still warns on the other targets. `rustc-cfg` only passes `--cfg` to this package's crates; it cannot enable a Cargo feature or an optional dependency.

code

rust · 14 lines
rust
// build.rs
use std::env;

fn main() {
    println!("cargo::rerun-if-changed=build.rs");
    // Declare every custom cfg on every run, whether or not it is set.
    println!("cargo::rustc-check-cfg=cfg(tinyz_neon)");

    // The target being compiled for, not the machine running this script.
    let arch = env::var("CARGO_CFG_TARGET_ARCH").unwrap();
    if arch == "aarch64" {
        println!("cargo::rustc-cfg=tinyz_neon");
    }
}

go deeper

for a junior

Recall that a build script can set a cfg for the crate with cargo::rustc-cfg and that #[cfg] in code then sees it.

for a middle

Explain the host and target split, why CARGO_CFG_* and TARGET describe the target, and why cfg! in build.rs does not.

for a senior

Ship the full pattern: read the target from CARGO_CFG_*, declare every custom cfg unconditionally with rustc-check-cfg, and verify with a --target build.

for a principal

Prefer Cargo features for choices users make and build-script cfgs only for facts about the target or environment, and keep that split consistent.

## Two machines in one build Every Cargo build involves a **host**, the machine running Cargo, and a **target**, the platform the package is compiled for. Usually they are the same, but with `cargo build --target ...` they differ. A **build script** always belongs to the host: Cargo compiles `build.rs` for the host and runs it there, because it has to execute during the build. Its build dependencies are compiled for the host too. That makes `#[cfg]` and `cfg!` inside `build.rs` misleading. They are evaluated when the script is compiled, for the host, so on an aarch64 Mac building for `wasm32-wasip1`, `cfg!(target_arch = "aarch64")` in the script is `true` although the crate is being built for `wasm32`. How `#[cfg]` itself works in code belongs to the Rust language material on conditional compilation; the Cargo point is which machine the script describes. ## Reading the target: CARGO_CFG_* Cargo passes the **target's** configuration to the script as environment variables, one per cfg option, with the name uppercased and dashes turned into underscores: - `CARGO_CFG_TARGET_ARCH`, for example `aarch64` or `wasm32`; - `CARGO_CFG_TARGET_OS`, for example `macos`, `linux` or `wasi`; - `CARGO_CFG_TARGET_FAMILY`, which may hold several values joined by commas, such as `unix,wasm`, so a script must split it instead of comparing the whole string; - `CARGO_CFG_TARGET_FEATURE`, the enabled CPU features, also comma-separated; - boolean options such as `CARGO_CFG_UNIX` or `CARGO_CFG_WINDOWS`, present only when set. `TARGET` gives the full triple and `HOST` the compiler's own triple. Values a target lacks are simply absent, and some cfgs, such as `test`, are never provided. The Cargo book points at the `build-rs` crate for a typed wrapper over these variables. ## Passing a decision to the crate: cargo::rustc-cfg Having decided, the script tells rustc with `cargo::rustc-cfg=KEY` or `cargo::rustc-cfg=KEY="VALUE"`. Cargo turns that into `--cfg` for the package's crates, and the code selects an implementation with `#[cfg(tinyz_neon)]` and `#[cfg(not(tinyz_neon))]`. Limits worth knowing: | `cargo::rustc-cfg` can | `cargo::rustc-cfg` cannot | |---|---| | set a bare name such as `tinyz_neon` | enable a Cargo feature from `[features]` | | set a key-value pair such as `tinyz_kernel="neon"` | activate an optional dependency | | affect this package's crates | reach the crates of other packages | Cargo features also travel as cfgs, in the form `feature="name"`, but setting such a cfg from a script does not change dependency resolution; it only fools the code. ## Declaring it: cargo::rustc-check-cfg Since **Cargo 1.80**, Cargo passes `--check-cfg` to every rustc and rustdoc invocation, so rustc knows the expected cfg names and values and warns, through the `unexpected_cfgs` lint, about any it does not expect. A custom name from a build script is unknown unless the script declares it: 1. Print `cargo::rustc-check-cfg=cfg(tinyz_neon)` for a bare name, or `cfg(tinyz_kernel, values("neon", "portable"))` for a key with values. 2. Print it **on every run**, whatever the script decides. The Cargo reference asks for all possible cfgs and values to be declared regardless of which are enabled; a declaration inside the `if` still warns when building for a target where the branch is not taken. 3. Keep the `rustc-check-cfg` and `rustc-cfg` lines next to each other so a typo shows up in review. Without the declaration, rustc's warning itself lists the remedies: adding the `println!` to the build script, or an `unexpected_cfgs` entry with `check-cfg` in the manifest's lints table, which the material on Cargo's lints covers. The Cargo reference marks the instruction as respected as of Cargo 1.80. ## Putting it together The resulting script, shown in the examples, reads `CARGO_CFG_TARGET_ARCH`, declares `tinyz_neon` unconditionally, and sets it only for aarch64 targets. Run on that Mac, `cargo test` takes the NEON path, and `cargo build --target wasm32-wasip1` takes the portable one with no warnings. Two habits make this kind of script trustworthy: - **Build for a second target in CI.** A native build on one machine never exercises the branch the script did not take, so a host-versus-target mix-up or a missing declaration only shows up under `--target`. Each target gets its own output under `target/<triple>/`, so the script runs and caches its decision separately per target. - **Print what the script decided while debugging.** A temporary `cargo::warning=` line with `TARGET` and the chosen cfg shows the decision on the terminal for a local package, and `cargo build -vv` shows every line the script printed.

  • How do you declare a custom cfg that takes values, such as tinyz_kernel = "neon" or "portable"?
    Print `cargo::rustc-check-cfg=cfg(tinyz_kernel, values("neon", "portable"))` on every run, then set one with `cargo::rustc-cfg=tinyz_kernel="neon"`. rustc then warns about an unknown name and also about an unlisted value: `#[cfg(tinyz_kernel = "nenon")]` gets ``unexpected `cfg` condition value: `nenon` ``.
  • Why compare CARGO_CFG_TARGET_FAMILY carefully instead of with ==?
    Options with several values are joined into one variable with commas; a target can report `unix,wasm`. Split on commas and look for the value you need, or a check for `unix` silently fails on such targets.
  • Can the script read the enabled Cargo features, and may it switch one on?
    It can read them: each enabled feature appears as `CARGO_FEATURE_<NAME>`, uppercased with dashes as underscores. It cannot switch one on; `cargo::rustc-cfg` never affects dependency resolution, so features and optional dependencies stay as the command line and manifests chose them.

  • cfg!(target_os) inside build.rs reports the platform being compiled for.
  • Build scripts are compiled for the --target triple, like the crate.
  • cargo::rustc-cfg=feature="simd" turns on the simd Cargo feature.
  • Declaring a custom cfg only when it is set is enough for check-cfg.
  • CARGO_CFG_TARGET_FAMILY always holds exactly one value.

Assumes Cargo 1.99; check-cfg became the default, and cargo::rustc-check-cfg stable, in Cargo 1.80.