Skip to content

Update cfg_attr to use the attribute template #1879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jul 1, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 37 additions & 31 deletions src/conditional-compilation.md
Original file line number Diff line number Diff line change
Expand Up @@ -385,52 +385,58 @@ The `cfg` attribute is allowed anywhere attributes are allowed.
r[cfg.cfg_attr]
### The `cfg_attr` attribute

r[cfg.cfg_attr.intro]
The *`cfg_attr` [attribute]* conditionally includes attributes based on a configuration predicate.

> [!EXAMPLE]
> The following module will either be found at `linux.rs` or `windows.rs` based on the target.
>
> <!-- ignore: `mod` needs multiple files -->
> ```rust,ignore
> #[cfg_attr(target_os = "linux", path = "linux.rs")]
> #[cfg_attr(windows, path = "windows.rs")]
> mod os;
> ```

r[cfg.cfg_attr.syntax]
The syntax for the `cfg_attr` attribute is:

```grammar,configuration
@root CfgAttrAttribute -> `cfg_attr` `(` ConfigurationPredicate `,` CfgAttrs? `)`

CfgAttrs -> Attr (`,` Attr)* `,`?
```

r[cfg.cfg_attr.general]
The `cfg_attr` [attribute] conditionally includes [attributes] based on a
configuration predicate.
r[cfg.cfg_attr.allowed-positions]
The `cfg_attr` attribute is allowed anywhere attributes are allowed.

r[cfg.cfg_attr.duplicates]
Multiple `cfg_attr` attributes may be specified.

r[cfg.cfg_attr.behaviour]
When the configuration predicate is true, this attribute expands out to the
attributes listed after the predicate. For example, the following module will
either be found at `linux.rs` or `windows.rs` based on the target.
r[cfg.cfg_attr.attr-restriction]
The [`crate_type`] and [`crate_name`] attributes cannot be used with `cfg_attr`.

<!-- ignore: `mod` needs multiple files -->
```rust,ignore
#[cfg_attr(target_os = "linux", path = "linux.rs")]
#[cfg_attr(windows, path = "windows.rs")]
mod os;
```
r[cfg.cfg_attr.behavior]
When the configuration predicate is true, `cfg_attr` expands out to the attributes listed after the predicate.

r[cfg.cfg_attr.attribute-list]
Zero, one, or more attributes may be listed. Multiple attributes will each be
expanded into separate attributes. For example:

<!-- ignore: fake attributes -->
```rust,ignore
#[cfg_attr(feature = "magic", sparkles, crackles)]
fn bewitched() {}

// When the `magic` feature flag is enabled, the above will expand to:
#[sparkles]
#[crackles]
fn bewitched() {}
```
Zero, one, or more attributes may be listed. Multiple attributes will each be expanded into separate attributes.

> [!EXAMPLE]
> <!-- ignore: fake attributes -->
> ```rust,ignore
> #[cfg_attr(feature = "magic", sparkles, crackles)]
> fn bewitched() {}
>
> // When the `magic` feature flag is enabled, the above will expand to:
> #[sparkles]
> #[crackles]
> fn bewitched() {}
> ```

> [!NOTE]
> The `cfg_attr` can expand to another `cfg_attr`. For example, `#[cfg_attr(target_os = "linux", cfg_attr(feature = "multithreaded", some_other_attribute))]` is valid. This example would be equivalent to `#[cfg_attr(all(target_os = "linux", feature ="multithreaded"), some_other_attribute)]`.

r[cfg.cfg_attr.restriction]
The `cfg_attr` attribute is allowed anywhere attributes are allowed.

The [`crate_type`] and [`crate_name`] attributes cannot be used with `cfg_attr`.

r[cfg.macro]
### The `cfg` macro

Expand Down