Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Attributes

The #[cfg] and cfg_attr attributes

Reference for Rust conditional compilation: #[cfg], cfg_attr, the cfg! macro, predicates like all, any, not, target_os, debug_assertions and feature flags.

#[cfg(predicate)] includes the item, statement or expression that follows only if the predicate is true at compile time. When it is false, the code is removed before type checking, so it can mention things that do not exist on the current platform.

#[cfg_attr(predicate, attribute, ...)] applies the listed attributes only when the predicate is true. The cfg!(predicate) macro, by contrast, expands to a plain true or false and keeps both branches in the program, so both branches must still compile.

Rust
#[cfg(target_os = "windows")]
fn platform() -> &'static str { "windows" }

#[cfg(not(target_os = "windows"))]
fn platform() -> &'static str { "something else" }

Try it

Rust cfg attributes and the cfg! macro

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust all, any, not, statements and cfg_attr

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
#[cfg(predicate)]
#[cfg_attr(predicate, attr1, attr2)]
#![cfg(predicate)]          // applies to the enclosing module or crate
cfg!(predicate)             // expands to a bool
Predicate Meaning
name A bare option such as unix, windows, test, debug_assertions
key = "value" For example target_os = "linux", target_arch = "aarch64", target_pointer_width = "32", target_endian, target_family, feature = "name"
all(a, b, ...) True if every predicate is true (an empty list is true)
any(a, b, ...) True if at least one is true (an empty list is false)
not(a) Negation; takes exactly one predicate

Edge cases:

  • A cfg can be written on items, statements, struct fields, enum variants, match arms, function parameters and expressions in some positions.
  • cfg! cannot remove code, so both branches must type-check on every platform.
  • feature = "x" is set by Cargo when feature x is enabled. Without Cargo, pass --cfg 'feature="x"' to rustc.

Usage notes

  • Pair definitions. When you gate a function with #[cfg(x)], provide a #[cfg(not(x))] counterpart with the same signature, or callers on other platforms will not compile.
  • cfg vs cfg!. Use the attribute for code that cannot exist on every target (platform APIs); use the macro for cheap runtime-looking checks.
  • cfg(test) is true only when compiled with --test (what cargo test does). Use #[cfg(test)] mod tests { ... } to keep tests out of normal builds.
  • debug_assertions is on in debug builds and in the runner here; release builds turn it off unless configured.
  • Stable names. Unknown names produce a warning via the unexpected_cfgs lint, which catches typos in feature names; declare custom cfgs in Cargo.toml or a build script.