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?
answer
- two machines in one build
- the script runs on the host
- Cargo describes the target in env vars
- declare custom cfgs since 1.80
- declare on every run
basics
~20 sA 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 sIn `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// 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
Recall that a build script can set a cfg for the crate with cargo::rustc-cfg and that #[cfg] in code then sees it.
Explain the host and target split, why CARGO_CFG_* and TARGET describe the target, and why cfg! in build.rs does not.
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.
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.