skip to content

Why do a Cargo project's `[target.aarch64-unknown-linux-gnu] rustflags` vanish in a CI job that exports `RUSTFLAGS="-D warnings"`, and how do you fix it?

level: seniorimportance: should knowfreq 22%

answer

  1. flag sources do not merge
  2. first source present wins
  3. an exported variable outranks the file
  4. deny warnings without touching rustflags

basics

~10 s

Cargo takes extra rustc flags from one source only: CARGO_ENCODED_RUSTFLAGS, else RUSTFLAGS, else matching [target] rustflags, else build.rustflags. RUSTFLAGS in CI replaces the config's flags; deny warnings through build.warnings instead.

solid answer

~30 s

Cargo does not merge flag sources. It checks four in order and uses the first one present: `CARGO_ENCODED_RUSTFLAGS`, `RUSTFLAGS`, all matching `[target.<triple>]` and `[target.'cfg(...)']` `rustflags` joined together, and last `build.rustflags`. Exporting `RUSTFLAGS` in CI therefore drops the config's `-C target-cpu=neoverse-n1` without a word, and `cargo build -v` shows rustc lines without it; the `linker` key survives because it is not a rustflags source. The fix is to stop competing for the slot: set `CARGO_BUILD_WARNINGS=deny` (the `build.warnings` key, stable since Cargo 1.97), or move CI-only flags into `CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUSTFLAGS`, which joins the config's target flags instead of replacing them.

code

console · 3 lines
console
$ CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUSTFLAGS="-D warnings" cargo build -v 2>&1 | grep -o -e '-C target-cpu=[a-z0-9-]*' -e '-D warnings' | sort -u
-C target-cpu=neoverse-n1
-D warnings

go deeper

for a junior

Know that RUSTFLAGS passes extra flags to rustc and that .cargo/config.toml can hold rustflags too; the two do not combine.

for a middle

Recite the four rustflags sources in order and explain that the first one present wins, with matching [target] tables joined among themselves.

for a senior

Diagnose the silent loss with cargo build -v, then fix it without competing for the slot: build.warnings, a per-triple CARGO_TARGET_ variable or the [lints] table. Mention host artifacts and dependency rebuilds.

for a principal

Set a team rule for where compiler flags live, config, manifest lints or profiles, so CI never needs a blanket RUSTFLAGS that overrides what the repository declares.

## The symptom A team cross-compiles a service for aarch64 Linux servers and tunes code generation in the repository's `.cargo/config.toml`: ```toml [build] target = "aarch64-unknown-linux-gnu" [target.aarch64-unknown-linux-gnu] linker = "aarch64-linux-gnu-gcc" rustflags = ["-C", "target-cpu=neoverse-n1"] ``` Laptop builds use the flag. The CI job also exports `RUSTFLAGS="-D warnings"` so that any warning fails the build, and from then on CI binaries are built for the generic aarch64 CPU. Nothing warns about it. ## Four sources, and only one is used Cargo's reference for `build.rustflags` lists four **mutually exclusive** sources of extra rustc flags, checked in this order. The first one present is used and the rest are ignored: 1. The `CARGO_ENCODED_RUSTFLAGS` environment variable, flags separated by the 0x1f byte. 2. The `RUSTFLAGS` environment variable, split on whitespace. 3. Every `target.<triple>.rustflags` and `target.<cfg>.rustflags` entry that matches the target, **joined together**. 4. The `build.rustflags` config value. So `RUSTFLAGS` does not add `-D warnings` to the config's flags; it **replaces** them. With cargo 1.99.1 the verbose output shows it directly: ```console $ cargo build -v 2>&1 | grep -o -e '-C target-cpu=[a-z0-9-]*' -e '-D warnings' | sort -u -C target-cpu=neoverse-n1 $ RUSTFLAGS="-D warnings" cargo build -v 2>&1 | grep -o -e '-C target-cpu=[a-z0-9-]*' -e '-D warnings' | sort -u -D warnings ``` The `linker` setting is untouched, because it reaches rustc through its own `-C linker=...` argument rather than through any rustflags source. ## Other consequences of the same rule - **`[target]` rustflags shadow `build.rustflags`.** A project with both gets only the target table's flags when that table matches; `CARGO_BUILD_RUSTFLAGS`, the environment form of source 4, is ignored in that case too. - **Several matching `[target]` tables combine.** A triple table and a `cfg(target_os = "linux")` table both contribute, because source 3 is the joined set. - **Host artifacts may not see the flags.** With `--target` or `build.target`, flags go only to code compiled for the target; build scripts and procedural macros, built for the host, receive none. Without a target, all compiler invocations get them. - **Changing the flags recompiles dependencies.** A build with a different `RUSTFLAGS` value rebuilds the whole dependency graph under the new flags, which is why toggling it between CI steps costs time. ## Fixes, from cleanest to bluntest | Approach | Keeps the config's flags? | Notes | |---|---|---| | `CARGO_BUILD_WARNINGS=deny`, or `[build] warnings = "deny"` | yes | Cargo-side setting, stable since Cargo 1.97; affects lint warnings of local packages only and recompiles nothing | | A `[lints]` table in the manifest | yes | sets lint levels in the package itself, as the lints material covers | | `CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUSTFLAGS="-D warnings"` | yes | environment form of `target.<triple>.rustflags`; joined with the config's target flags | | Repeat every config flag inside `RUSTFLAGS` | only by copying | works, but the copy drifts as soon as someone edits the config | The third row was checked the same way: with that variable exported, rustc receives both `-C target-cpu=neoverse-n1` and `-D warnings`. ## Where each kind of flag belongs Most `RUSTFLAGS` uses in CI have a better home, and moving them there removes the competition for the single slot: - **Optimisation, debug info, LTO** belong in Cargo profiles, which Cargo turns into the right rustc flags itself. - **Lint levels** belong in the manifest's `[lints]` table or in `build.warnings`. - **Target CPU and target features** belong in the `[target.<triple>]` rustflags of the repository config, where every machine sees them. - **The linker** belongs in the `linker` key rather than in a `-C linker` flag. - **One-off experiments**, such as trying a new code-generation option locally, are where `RUSTFLAGS` is still the quickest tool. ## How to diagnose it next time When a code-generation or linker-argument flag seems to disappear: 1. Run the failing build with `-v` and read one rustc command line for the package. 2. Print the job's environment and look for `RUSTFLAGS`, `CARGO_ENCODED_RUSTFLAGS` and `CARGO_BUILD_RUSTFLAGS`. 3. Check whether a `[target]` table matches, which would hide `build.rustflags`. The underlying lesson is that `RUSTFLAGS` is a low-level override. Cargo's own reference recommends against passing flags that Cargo manages itself, such as optimisation levels, which belong in profiles, and the same caution applies to letting one environment variable silently decide every compiler flag a build gets.

  • Why does `CARGO_BUILD_RUSTFLAGS="-D warnings"` not help when the config has a matching `[target]` rustflags table?
    `CARGO_BUILD_RUSTFLAGS` is the environment form of `build.rustflags`, the fourth and last source. When any `[target]` rustflags entry matches, source three is used and source four is never consulted, so the variable is ignored. Use the per-triple variable `CARGO_TARGET_<TRIPLE>_RUSTFLAGS`, which joins the config's target flags.
  • With `--target` given, do build scripts receive flags from `RUSTFLAGS`?
    No. When a target is set by `--target` or `build.target`, Cargo passes extra flags only to compilations for that target; build scripts and procedural macros, compiled for the host, get none. Without a target they do get them, because host and target artifacts are then shared. Passing `--target` with the host triple is the documented way to keep flags away from build scripts.

  • RUSTFLAGS adds its flags on top of whatever .cargo/config.toml specifies.
  • build.rustflags and [target] rustflags are always concatenated.
  • RUSTFLAGS also overrides the linker setting under [target.<triple>].
  • Changing RUSTFLAGS only recompiles the current crate, not its dependencies.
  • CARGO_BUILD_RUSTFLAGS can append to a matching [target] rustflags table.

Assumes Cargo 1.99.1; the build.warnings config key and CARGO_BUILD_WARNINGS used in the fix are stable since Cargo 1.97.