Skip to content

document cfg conditions on inline assembly templates and operands #2063

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 6 commits into from
Nov 26, 2025
Merged

document cfg conditions on inline assembly templates and operands #2063

merged 6 commits into from
Nov 26, 2025

Conversation

@folkertdev
Copy link
Contributor

@folkertdev folkertdev commented Oct 24, 2025 •
edited by traviscross
Loading

Reference PR for:

@rustbot rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Oct 24, 2025
@folkertdev folkertdev mentioned this pull request Oct 24, 2025
Merged
traviscross
traviscross reviewed Oct 24, 2025
View reviewed changes
petrochenkov
petrochenkov reviewed Oct 25, 2025
View reviewed changes
@folkertdev folkertdev force-pushed the asm-cfg branch 4 times, most recently from 8fc2f56 to 58e0705 Compare October 25, 2025 14:29
@ehuss ehuss added the S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository label Oct 30, 2025
ehuss
ehuss reviewed Oct 30, 2025
View reviewed changes
@folkertdev folkertdev force-pushed the asm-cfg branch 2 times, most recently from 841e6ba to 99014a3 Compare October 30, 2025 19:00
@rustbot
Copy link
Collaborator

rustbot commented Nov 16, 2025

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

@traviscross
Remove stray comma from info string
0de8337 
There was a stray comma on this info string.  Let's remove it.
@traviscross
Revise starts-with-template example
a1fa462 
This test is believed to fail, so we should mark it with
`compile_fail` rather than `ignore`.

Let's wrap the comment.

The compiler's error message, in this case, doesn't add any insight;
let's remove the details of that.
@traviscross
Remove stray comma
921222e 
The sentence "Other attributes are parsed but rejected" has a two-part
compound predicate; that is, the subject is used for two verbs,
separated by a coordinating conjunction ("but"), and is not repeated.
In these cases, a comma is omitted before the coordinating
conjunction, so let's remove the comma.
@traviscross
Add note about restrictions on asm attributes
447b76c 
We have a list that describes where attributes may be applied.  We're
adding inline assembly template strings and operands to that list, but
only certain attributes may be used, and other caveats apply.  Let's
note that there are restrictions and link to the relevant section for
more details, as we do already for certain other items on this list.

It may be important, normatively, to note this restriction here if we
now or later refer to some attribute as being accepted anywhere that
attributes are allowed.
@traviscross
Add admonition about asm attribute implementation
ac44a37 
The implementation of attributes for asm macro template strings and
operands doesn't use the normal system in `rustc` for handling
attributes.  This leads to the limitations and may lead to subtle
divergences in behavior.  Let's make a note about this.

For background, see:

- rust-lang#2063 (comment)
- rust-lang/rust#147736 (comment)
@traviscross traviscross removed the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Nov 16, 2025
@traviscross
Copy link
Contributor

traviscross commented Nov 16, 2025

I've pushed a series of revisions. Some of this is editorial; some has potential normative effect on other parts of the document where we may refer to other attributes as being accepted wherever attributes are allowed. For details, see the commit messages.

With these revisions, this looks good to me.

matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Nov 25, 2025
@matthiaskrgr
Rollup merge of rust-lang#147736 - folkertdev:stabilize-asm-cfg, r=jd…
04e4f95 
…onszelmann

Stabilize `asm_cfg`

tracking issue: rust-lang#140364
closes rust-lang#140364

Reference PR:

- rust-lang/reference#2063

# Request for Stabilization

## Summary

The `cfg_asm` feature allows `#[cfg(...)]` and `#[cfg_attr(...)]` on  the arguments of the assembly macros, for instance:

```rust
asm!( // or global_asm! or naked_asm!
    "nop",
    #[cfg(target_feature = "sse2")]
    "nop",
    // ...
    #[cfg(target_feature = "sse2")]
    a = const 123, // only used on sse2
);
```

## Semantics

Templates, operands, `options` and `clobber_abi` in the assembly macros (`asm!`, `naked_asm!` and `global_asm!`) can be annotated with `#[cfg(...)]` and `#[cfg_attr(...)]`. When the condition evaluates to true, the annotated argument has no effect, and is completely ignored when expanding the assembly macro.
## Documentation

reference PR: rust-lang/reference#2063

## Tests

- [tests/ui/asm/cfg.rs](https://github.com/rust-lang/rust/blob/master/tests/ui/asm/cfg.rs) checks that `cfg`'d arguments where the condition evaluates to false have no effect
- [tests/ui/asm/cfg-parse-error.rs](https://github.com/rust-lang/rust/blob/master/tests/ui/asm/cfg.rs) checks the parsing rules (parsing effectively assumes that the cfg conditions are all true)

## History

- rust-lang#140279
- rust-lang#140367

# Resolved questions

**how are other attributes handled**

Other attributes are parsed,  but explicitly rejected.

# unresolved questions

**operand before template**

The current implementation expects at least one template string before any operands. In the example below, if the `cfg` condition evaluates to true, the assembly block is ill-formed. But even when it evaluates to `false` this block is rejected, because the parser still expects just a template (a template is parsed as an expression and then validated to ensure that it is or expands to a string literal).

Changing how this works is difficult.
```rust
// This is rejected because `a = out(reg) x` does not parse as an expresion.
asm!(
	#[cfg(false)]
	a = out(reg) x, //~ ERROR expected token: `,`
	"",
);
```

**lint on positional arguments?**

Adding a lint to warn on the definition or use of positional arguments being `cfg`'d out was discussed in rust-lang#140279 (comment) and subsequent comments. Such a lint is not currently implemented, but that may not be a blocker based on the comments there.

r? `@traviscross` (I'm assuming you'll reassign as needed)
rust-timer added a commit to rust-lang/rust that referenced this pull request Nov 25, 2025
@rust-timer
Unrolled build for #147736
ba01420 
Rollup merge of #147736 - folkertdev:stabilize-asm-cfg, r=jdonszelmann

Stabilize `asm_cfg`

tracking issue: #140364
closes #140364

Reference PR:

- rust-lang/reference#2063

# Request for Stabilization

## Summary

The `cfg_asm` feature allows `#[cfg(...)]` and `#[cfg_attr(...)]` on  the arguments of the assembly macros, for instance:

```rust
asm!( // or global_asm! or naked_asm!
    "nop",
    #[cfg(target_feature = "sse2")]
    "nop",
    // ...
    #[cfg(target_feature = "sse2")]
    a = const 123, // only used on sse2
);
```

## Semantics

Templates, operands, `options` and `clobber_abi` in the assembly macros (`asm!`, `naked_asm!` and `global_asm!`) can be annotated with `#[cfg(...)]` and `#[cfg_attr(...)]`. When the condition evaluates to true, the annotated argument has no effect, and is completely ignored when expanding the assembly macro.
## Documentation

reference PR: rust-lang/reference#2063

## Tests

- [tests/ui/asm/cfg.rs](https://github.com/rust-lang/rust/blob/master/tests/ui/asm/cfg.rs) checks that `cfg`'d arguments where the condition evaluates to false have no effect
- [tests/ui/asm/cfg-parse-error.rs](https://github.com/rust-lang/rust/blob/master/tests/ui/asm/cfg.rs) checks the parsing rules (parsing effectively assumes that the cfg conditions are all true)

## History

- #140279
- #140367

# Resolved questions

**how are other attributes handled**

Other attributes are parsed,  but explicitly rejected.

# unresolved questions

**operand before template**

The current implementation expects at least one template string before any operands. In the example below, if the `cfg` condition evaluates to true, the assembly block is ill-formed. But even when it evaluates to `false` this block is rejected, because the parser still expects just a template (a template is parsed as an expression and then validated to ensure that it is or expands to a string literal).

Changing how this works is difficult.
```rust
// This is rejected because `a = out(reg) x` does not parse as an expresion.
asm!(
	#[cfg(false)]
	a = out(reg) x, //~ ERROR expected token: `,`
	"",
);
```

**lint on positional arguments?**

Adding a lint to warn on the definition or use of positional arguments being `cfg`'d out was discussed in #140279 (comment) and subsequent comments. Such a lint is not currently implemented, but that may not be a blocker based on the comments there.

r? `@traviscross` (I'm assuming you'll reassign as needed)
@ehuss ehuss added this pull request to the merge queue Nov 26, 2025
Merged via the queue into rust-lang:master with commit f2ac173 Nov 26, 2025
8 of 10 checks passed
github-actions bot pushed a commit to rust-lang/compiler-builtins that referenced this pull request Nov 27, 2025
@matthiaskrgr
Rollup merge of #147736 - folkertdev:stabilize-asm-cfg, r=jdonszelmann
90b47ec 
Stabilize `asm_cfg`

tracking issue: rust-lang/rust#140364
closes rust-lang/rust#140364

Reference PR:

- rust-lang/reference#2063

# Request for Stabilization

## Summary

The `cfg_asm` feature allows `#[cfg(...)]` and `#[cfg_attr(...)]` on  the arguments of the assembly macros, for instance:

```rust
asm!( // or global_asm! or naked_asm!
    "nop",
    #[cfg(target_feature = "sse2")]
    "nop",
    // ...
    #[cfg(target_feature = "sse2")]
    a = const 123, // only used on sse2
);
```

## Semantics

Templates, operands, `options` and `clobber_abi` in the assembly macros (`asm!`, `naked_asm!` and `global_asm!`) can be annotated with `#[cfg(...)]` and `#[cfg_attr(...)]`. When the condition evaluates to true, the annotated argument has no effect, and is completely ignored when expanding the assembly macro.
## Documentation

reference PR: rust-lang/reference#2063

## Tests

- [tests/ui/asm/cfg.rs](https://github.com/rust-lang/rust/blob/master/tests/ui/asm/cfg.rs) checks that `cfg`'d arguments where the condition evaluates to false have no effect
- [tests/ui/asm/cfg-parse-error.rs](https://github.com/rust-lang/rust/blob/master/tests/ui/asm/cfg.rs) checks the parsing rules (parsing effectively assumes that the cfg conditions are all true)

## History

- rust-lang/rust#140279
- rust-lang/rust#140367

# Resolved questions

**how are other attributes handled**

Other attributes are parsed,  but explicitly rejected.

# unresolved questions

**operand before template**

The current implementation expects at least one template string before any operands. In the example below, if the `cfg` condition evaluates to true, the assembly block is ill-formed. But even when it evaluates to `false` this block is rejected, because the parser still expects just a template (a template is parsed as an expression and then validated to ensure that it is or expands to a string literal).

Changing how this works is difficult.
```rust
// This is rejected because `a = out(reg) x` does not parse as an expresion.
asm!(
	#[cfg(false)]
	a = out(reg) x, //~ ERROR expected token: `,`
	"",
);
```

**lint on positional arguments?**

Adding a lint to warn on the definition or use of positional arguments being `cfg`'d out was discussed in rust-lang/rust#140279 (comment) and subsequent comments. Such a lint is not currently implemented, but that may not be a blocker based on the comments there.

r? `@traviscross` (I'm assuming you'll reassign as needed)
@rustbot rustbot mentioned this pull request Nov 28, 2025
Merged
jhpratt added a commit to jhpratt/rust that referenced this pull request Nov 29, 2025
@jhpratt
Rollup merge of rust-lang#149424 - rustbot:docs-update, r=ehuss
e838b66 
Update books

## rust-lang/book

2 commits in f78ab89d7545ac17780e6a367055cc089f4cd2ec..8c0eacd5c4acbb650497454f3a58c9e8083202a4
2025-11-18 15:36:41 UTC to 2025-11-18 15:33:41 UTC

- Update ch07-02-defining-modules-to-control-scope-and-privacy.md (rust-lang/book#4570)
- use AND for search terms (rust-lang/book#4573)

## rust-lang/reference

4 commits in f9f1d2a4149f02582aec2f8fcdfa5b596193b4e2..f2ac173df9906de5c03b0ee50653321ef1c4ebe8
2025-11-26 02:52:23 UTC to 2025-11-18 21:54:51 UTC

- document `cfg` conditions on inline assembly templates and operands (rust-lang/reference#2063)
- remove unused "link reference definitions" (rust-lang/reference#2092)
- Add review process overview to review-policy.md (rust-lang/reference#2088)
- Remove restriction on dereferencing pointers in const (rust-lang/reference#2090)

## rust-lang/rust-by-example

5 commits in f944161716230641605b5e3733e1c81f10047fd4..111cfae2f9c3a43f7b0ff8fa68c51cc8f930637c
2025-11-27 20:16:42 UTC to 2025-11-20 21:40:02 UTC

- Use `From::from` fn pointer to convert to boxed errors (rust-lang/rust-by-example#1906)
- link the _tuple_ page instead "TupleStruct" (rust-lang/rust-by-example#1909)
- enum_use.md: avoid an uncommon term (rust-lang/rust-by-example#1976)
- make search less surprising (rust-lang/rust-by-example#1975)
- Update documentation for `any` function in iter_any.md (rust-lang/rust-by-example#1973)
rust-timer added a commit to rust-lang/rust that referenced this pull request Nov 29, 2025
@rust-timer
Unrolled build for #149424
d34a235 
Rollup merge of #149424 - rustbot:docs-update, r=ehuss

Update books

## rust-lang/book

2 commits in f78ab89d7545ac17780e6a367055cc089f4cd2ec..8c0eacd5c4acbb650497454f3a58c9e8083202a4
2025-11-18 15:36:41 UTC to 2025-11-18 15:33:41 UTC

- Update ch07-02-defining-modules-to-control-scope-and-privacy.md (rust-lang/book#4570)
- use AND for search terms (rust-lang/book#4573)

## rust-lang/reference

4 commits in f9f1d2a4149f02582aec2f8fcdfa5b596193b4e2..f2ac173df9906de5c03b0ee50653321ef1c4ebe8
2025-11-26 02:52:23 UTC to 2025-11-18 21:54:51 UTC

- document `cfg` conditions on inline assembly templates and operands (rust-lang/reference#2063)
- remove unused "link reference definitions" (rust-lang/reference#2092)
- Add review process overview to review-policy.md (rust-lang/reference#2088)
- Remove restriction on dereferencing pointers in const (rust-lang/reference#2090)

## rust-lang/rust-by-example

5 commits in f944161716230641605b5e3733e1c81f10047fd4..111cfae2f9c3a43f7b0ff8fa68c51cc8f930637c
2025-11-27 20:16:42 UTC to 2025-11-20 21:40:02 UTC

- Use `From::from` fn pointer to convert to boxed errors (rust-lang/rust-by-example#1906)
- link the _tuple_ page instead "TupleStruct" (rust-lang/rust-by-example#1909)
- enum_use.md: avoid an uncommon term (rust-lang/rust-by-example#1976)
- make search less surprising (rust-lang/rust-by-example#1975)
- Update documentation for `any` function in iter_any.md (rust-lang/rust-by-example#1973)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ehuss ehuss ehuss left review comments

@traviscross traviscross traviscross approved these changes

+1 more reviewer

@petrochenkov petrochenkov petrochenkov left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@folkertdev @rustbot @traviscross @ehuss @petrochenkov