document `cfg` conditions on inline assembly templates and operands by folkertdev · Pull Request #2063 · rust-lang/reference

folkertdev · 2025-10-24T22:33:55Z

Reference PR for:

Stabilize asm_cfg rust#147736

src/inline-assembly.md

src/attributes.md

src/inline-assembly.md

rustbot · 2025-11-16T09:15:03Z

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.

There was a stray comma on this info string. Let's remove it.

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.

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.

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.

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 · 2025-11-16T12:58:48Z

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.

…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)

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)

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)

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)

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)

This updates to mdbook 0.5.2 from mdbook 0.4.52. A primary aspect of this change is that it splits the `mdbook` crate into multiple crates, and various API changes and cleanup. There's full release notes and a migration guide at https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-050. This also includes submodule updates: ## book 8 commits in f660f341887c8bbcd6c24fbfdf5d2a262f523965..9c9104e8a82430f97f42e738051bda718919211c 2025-10-27 21:41:51 -0400 to 2025-12-10 11:33:49 -0500 - Update to mdbook 0.5 - Update ch07-02-defining-modules-to-control-scope-and-privacy.md - use AND for search terms - Consistently use let...else - Merge branch 'main' into fix-typo-17-02 - Fix typo in section 17.2 - Revert "Fix typo in section 17.2" - Fix typo in section 17.2 ## edition-guide 2 commits in 5c621253d8f2a5a4adb64a6365905db67dffe3a2..c3c0f0b3da26610138b7ba7663f60cd2c68cf184 2025-10-23 14:13:01 +0000 to 2025-11-28 18:54:18 +0000 - Update to mdbook 0.5 (rust-lang/edition-guide#381) - Link to 1.56.0 and 1.85.0 blog posts (rust-lang/edition-guide#380) ## nomicon 6 commits in 60f0b30d8ec1c9eb5c2582f2ec55f1094b0f8c42..9fe8fa599ad228dda74f240cc32b54bc5c1aa3e6 2025-10-20 13:05:39 +0000 to 2025-12-03 11:54:04 +0000 - Remove references to outdated unsafe code guidelines (rust-lang/nomicon#512) - Update to mdbook 0.5 (rust-lang/nomicon#511) - Fix grammar in ffi.md (rust-lang/nomicon#510) - Add CITATION.cff (rust-lang/nomicon#507) - Use the newest Layout::array size checks for vec-alloc (rust-lang/nomicon#508) - review comment: dropck analysis is *not* trivial (rust-lang/nomicon#498) ## reference 17 commits in e122eefff3fef362eb7e0c08fb7ffbf5f9461905..50c5de90487b68d429a30cc9466dc8f5b410128f 2025-10-28 20:52:27 +0000 to 2025-12-09 22:19:05 +0000 - UB: update the extra clause for provenance UB during const evaluation (rust-lang/reference#2091) - Remove `[no-mentions]` handler in our triagebot config (rust-lang/reference#2102) - Clarify that omitting `nostack` is a promise from the compiler to the programmer (rust-lang/reference#1999) - Specify that range patterns must be nonempty. (rust-lang/reference#2093) - Update to mdbook 0.5 (rust-lang/reference#2096) - get rid of const.no-mut-refs (rust-lang/reference#2080) - use oxford comma (rust-lang/reference#2099) - 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) - add 'system' to variadic ABIs (rust-lang/reference#2069) - Guarantee the binary representation of `isize` explicitly (rust-lang/reference#2064) - Update `no_implicit_prelude` to use the attribute template (rust-lang/reference#1914) - Update `no_std` to use the attribute template (rust-lang/reference#1913) - const_eval.md: be more clear where link leads to (rust-lang/reference#2083) - specify s390x target features (rust-lang/reference#1972) ## rust-by-example 7 commits in 160e6bbca70b0c01aa4de88d19db7fc5ff8447c3..7d21279e40e8f0e91c2a22c5148dd2d745aef8b6 2025-11-03 09:26:45 -0300 to 2025-12-01 15:02:09 -0300 - Update to mdbook 0.5 (rust-lang/rust-by-example#1977) - 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) - Revise `Path` type documentation for clarity (rust-lang/rust-by-example#1972)

…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)

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 added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Oct 24, 2025

folkertdev mentioned this pull request Oct 24, 2025

Stabilize asm_cfg rust-lang/rust#147736

Merged

traviscross reviewed Oct 24, 2025

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

petrochenkov reviewed Oct 25, 2025

View reviewed changes

src/attributes.md Outdated Show resolved Hide resolved

folkertdev force-pushed the asm-cfg branch 4 times, most recently from 8fc2f56 to 58e0705 Compare October 25, 2025 14:29

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 reviewed Oct 30, 2025

View reviewed changes

src/inline-assembly.md Show resolved Hide resolved

folkertdev force-pushed the asm-cfg branch 2 times, most recently from 841e6ba to 99014a3 Compare October 30, 2025 19:00

document cfg conditions on inline assembly templates and operands

845ec96

traviscross force-pushed the asm-cfg branch from 99014a3 to 845ec96 Compare November 16, 2025 09:15

traviscross added 5 commits November 16, 2025 09:17

Remove stray comma from info string

0de8337

There was a stray comma on this info string. Let's remove it.

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 approved these changes Nov 16, 2025

View reviewed changes

traviscross removed the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Nov 16, 2025

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

rustbot mentioned this pull request Nov 28, 2025

Update books rust-lang/rust#149424

Merged

ehuss mentioned this pull request Dec 11, 2025

Update to mdbook 0.5 rust-lang/rust#149894

Merged

PLeVasseur mentioned this pull request Jan 31, 2026

Document asm_cfg inline assembly attributes PLeVasseur/fls#1

Closed

PLeVasseur mentioned this pull request Jan 31, 2026

Document asm_cfg inline assembly attributes rust-lang/fls#653

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

document `cfg` conditions on inline assembly templates and operands#2063

document `cfg` conditions on inline assembly templates and operands#2063
ehuss merged 6 commits intorust-lang:masterfrom
folkertdev:asm-cfg

folkertdev commented Oct 24, 2025 •

edited by traviscross

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustbot commented Nov 16, 2025

Uh oh!

traviscross commented Nov 16, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

folkertdev commented Oct 24, 2025 • edited by traviscross Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustbot commented Nov 16, 2025

Uh oh!

traviscross commented Nov 16, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

folkertdev commented Oct 24, 2025 •

edited by traviscross

Loading