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.
#[cfg(target_os = "windows")] fn platform() -> &'static str { "windows" } #[cfg(not(target_os = "windows"))] fn platform() -> &'static str { "something else" }
Try it
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.
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
#[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
cfgcan 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 featurexis enabled. Without Cargo, pass--cfg 'feature="x"'torustc.
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. cfgvscfg!. 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(whatcargo testdoes). Use#[cfg(test)] mod tests { ... }to keep tests out of normal builds.debug_assertionsis 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_cfgslint, which catches typos in feature names; declare custom cfgs inCargo.tomlor a build script.