RFC: `--crate-attr` by jyn514 · Pull Request #3791 · rust-lang/rfcs

jyn514 · 2025-03-17T05:38:21Z

Differences from the current nightly implementation (note that this section is non-normative):

-A -W -D -F become aliases for crate-attr
Attributes are prepended, not appended.
Everything about how this interacts with doctests (see RFC: --crate-attr #3791 (comment))
The attribute shares the same Span as the crate root. In particular file! behaves properly now and the edition is no longer always 2015.

- Mention how this applies to doctests - Mention build-std - Remove outdated mention of custom test frameworks

jieyouxu · 2025-03-17T14:54:47Z

+The `--crate-attr` flag allows you to inject attributes into the crate root.
+For example, `--crate-attr=crate_name="test"` acts as if `#![crate_name="test"]` were present before the first source line of the crate root.


Question (not necessarily for you but the Cursed Code Specialists): do we have any wonky (stable) crate-level attributes like #![crate_name = EXPR] (whose validation was only recently fixed as a breaking change in rust-lang/rust#127581) that an injection like --crate-attr=crate_name=include_str!("crate_name.txt") can lead to... interesting behaviors?

Or perhaps, can crate-root attributes take a "value" that's a macro, possibly line!()?

these should be questions for the individual attributes, imo. crate-attr does not try to special-case these in any way, it just forwards the macro invocation which gets rejected later in compilation. i do not think we should try to limit the syntax to things that "look normal".

$ rustc +r2-stage1 src/main.rs -Zcrate-attr=crate_name='line!()' error: malformed `crate_name` attribute input --> <crate attribute>:1:1 | 1 | #![crate_name=line!()] | ^^^^^^^^^^^^^^^^^^^^^^ help: must be of the form: `#![crate_name = "name"]`

(here r2-stage1 is a checkout of rust-lang/rust#138336)

Yeah that seems completely fair (if anything, may be QoI issue on specific crate-level attrs)

(I'll temporarily leave this thread open in case people do know of any Funny Things, but please resolve this comment chain before FCP as it is not intended to be blocking).

oh, i misunderstood. you were asking what include! and line! should expand to in this context. my understanding is that we do not currently have any crate-level attributes which accept values, right? i'm tempted to say we just delay defining this until we need to.

I agree with Jyn that we shouldn't restrict the grammar of those attributes.

To answer the original question however, there are several. E.g., #![doc = …], #![deprecated = …], #![type_length_limit = …]. In these three cases you can use concat!("", line!()) as the RHS which expands to (lineno) "1" when passed via -Zcrate-attr (I'm using concat to essentially get rid of the numeric suffix).

(crate_name, crate_type and recursion_limit are fully locked-down nowadays in the sense that they no longer accept macro calls)

(since a lot of malformed and misplaced attrs are still accepted by rustc and only trigger the warn-by-default lint unused_attributes, you can currently also do things like #![must_use = compile_error!("…")] which isn't that interesting arguably)

rustdoc -Zcrate-attr='doc=concat!("test", line!())' foo.rs gave a doc/foo/index.html containing "test1".

ok. of these, line!() really does not seem to have a meaning to me, maybe the implementation comes up with "1" but i don't think that's useful. so i'm tempted to ban that particular macro in this context.

include! and friends all seem fine to me, they should be relative to whatever #![doc = include_str!()] in the source is relative to.

FWIW I was mostly thinking adversarially on what weird combinations this can end up with (e.g. what's prone to break, between a stable + stable feature/functionality interaction). I suppose this may also include the other "meta" ones like column!(). Not sure how to phrase this, but "observable implementation details" -- e.g. that line number 1 being observable through line!() is potentially interesting if it can become depended upon by the user.

Alternatively... explicitly carve out a stability caution/exception where it's explicitly remarked that depending on line!()/column!() etc. is not part of the stability guarantees? Idk how to word this though. It's not a big concern but it can be annoying if it ever comes up.

i still think that all these concerns apply just as much to existing crate-level attributes in source code. if there is a concern here it should be specific to attributes passed via a CLI flag.

jieyouxu · 2025-03-17T15:10:09Z

+
+- We could require `--crate-attr=#![foo]` instead. This is more verbose and requires extensive shell quoting, for not much benefit.
+- We could disallow comments in the attribute. This perhaps makes the design less surprising, but complicates the implementation for little benefit.
+- We could add a syntax for passing multiple attributes in a single CLI flag. We would have to find a syntax that avoids ambiguity *and* that does not mis-parse the data inside string literals (i.e. picking a fixed string, such as `|`, would not work because it has to take quote nesting into account). This greatly complicates the implementation for little benefit.


Remark: +1, I think it's perfectly fine (and arguably good) to not support multi-attr in same flag. If anything, multiple --crate-attr flags is way easier to read too, IMO.

…nce.

Mark-Simulacrum · 2025-03-30T15:08:55Z

@rfcbot fcp merge

I've wanted this functionality before myself, and it's a requested feature from Rust for Linux, so demand exists. I think the RFC does a good job motivating the feature and noting edge cases that need resolution, though personally nothing that necessarily seems like it blocks stabilization. So, proposing we merge it.

rfcbot · 2025-03-30T15:08:57Z

wesleywiser · 2025-04-01T00:42:51Z

+
+Additionally, some existing CLI options could have been useful as attributes. This leads to the second group: Maintainers of the Rust language. Often we need to decide between attributes and flags; either we duplicate features between the two (lints, `crate-name`, `crate-type`), or we make it harder to configure the options for stakeholder group 1.
+
+The third group is the authors of external tools. The [original motivation][impl] for this feature was for Crater, which wanted to enable a rustfix feature in *all* crates it built without having to modify the source code. Other motivations include the currently-unstable [`register-tool`], which with this RFC could be an attribute passed by the external tool (or configured in the workspace), and [build-std], which wants to inject `no_std` into all crates being compiled.


and [build-std], which wants to inject no_std into all crates being compiled

Just as a note, RfL already does this exact thing and they would like to see -Zcrate-attr stabilized as well:

https://github.com/Rust-for-Linux/linux/blob/e6ea10d5dbe082c54add289b44f08c9fcfe658af/scripts/Makefile.build#L238-L239

apiraino · 2025-04-10T09:30:56Z

visited in meeting on Zulip

@rustbot label -I-compiler-nominated

Noratrieb · 2025-05-29T15:08:08Z

+fn foo() {}
+```
+
+Additionally, all existing `-A -W -D -F` flags become aliases for `--crate-attr` (`allow`, `warn`, `deny`, and `forbid`, respectively). In particular, this implies that the following CLI flag combinations are exactly equivalent:


This doesn't actually affect anything, right? The flags behave exactly the same no matter whether they are aliases or not.

no, this is user-facing. see #3791 (comment) for an example of how it can affect behavior otherwise.

Ok, please mention this in the RFC more explicitly in that case.

rfcbot · 2025-06-17T16:39:45Z

🔔 This is now entering its final comment period, as per the review above. 🔔

Co-authored-by: Josh Triplett <josh@joshtriplett.org>

rfcbot · 2025-06-27T16:39:53Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

jyn514 force-pushed the crate-attr branch from 2acde96 to fb68d4d Compare March 17, 2025 05:39

jyn514 commented Mar 17, 2025

View reviewed changes

Comment thread text/0000-crate-attr.md Outdated

RFC: --crate-attr

9d7b2f6

jyn514 force-pushed the crate-attr branch from fb68d4d to 9d7b2f6 Compare March 17, 2025 05:46

jyn514 mentioned this pull request Mar 17, 2025

rustdoc --test does not respect -Zcrate-attr rust-lang/rust#138491

Closed

epage reviewed Mar 17, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md

epage reviewed Mar 17, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md Outdated

ehuss added the T-compiler Relevant to the compiler team, which will review and decide on the RFC. label Mar 17, 2025

jyn514 added 2 commits March 17, 2025 10:46

initial feedback

ed9d231

- Mention how this applies to doctests - Mention build-std - Remove outdated mention of custom test frameworks

forgot to mark doctests as resolved

cec9178

jieyouxu reviewed Mar 17, 2025

View reviewed changes

Document that all tools support this flag. Document order and precede…

c29d394

…nce.

kennytm reviewed Mar 17, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md Outdated

jyn514 added 2 commits March 18, 2025 07:22

Define -A/W/D to be exactly equivalent to --crate-attr

7b03a05

Clarify that //! isn't allowed

aca698c

notriddle reviewed Mar 25, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md

jyn514 added 12 commits March 26, 2025 04:19

extend prior art section

046463b

Document why crate-attr is prepended instead of appended

4b9fa4b

Mention that line! and column! cause problems

69df2b8

Mention that the more verbose syntax fixes column!

f1cb06b

oops forgot miri

640136e

mention that #![crate_name] is a mess

8ef1b64

document that this shares a Span with the crate root

9a9b8da

Mention that the edition may be observable

b213d1f

oops typo

4c1b2ba

document that this may interact with custom inner attributes

a3abbbe

oops typo (redux)

cb4205d

ok maybe edition should not actually be an attribute

327a5ec

nikomatsakis mentioned this pull request Mar 26, 2025

Getting Rust for Linux into stable Rust: language features rust-lang/rust-project-goals#116

Closed

53 tasks

ojeda mentioned this pull request Mar 26, 2025

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

52 tasks

oli-obk added the I-compiler-nominated Indicates that an issue has been nominated for prioritizing at the next compiler team meeting. label Mar 30, 2025

Mark-Simulacrum reviewed Mar 30, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md

Comment thread text/3791-crate-attr.md Outdated

Comment thread text/3791-crate-attr.md Outdated

rfcbot added proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. disposition-merge This RFC is in PFCP or FCP with a disposition to merge it. labels Mar 30, 2025

wesleywiser approved these changes Apr 1, 2025

View reviewed changes

rustbot removed the I-compiler-nominated Indicates that an issue has been nominated for prioritizing at the next compiler team meeting. label Apr 10, 2025

nagisa reviewed Apr 10, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md Outdated

Comment thread text/3791-crate-attr.md Outdated

Comment thread text/3791-crate-attr.md Outdated

Clarify line!/column! treatment within expansion.

32bc019

Noratrieb reviewed May 29, 2025

View reviewed changes

jieyouxu mentioned this pull request Jun 4, 2025

Doc: clarify priority of lint level sources rust-lang/rust#142021

Merged

rfcbot added final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. and removed proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. labels Jun 17, 2025

joshtriplett reviewed Jun 18, 2025

View reviewed changes

Comment thread text/3791-crate-attr.md

Document dependency on build system

37315a8

Co-authored-by: Josh Triplett <josh@joshtriplett.org>

rfcbot added finished-final-comment-period The final comment period is finished for this RFC. to-announce and removed final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. labels Jun 27, 2025

zjp-CN mentioned this pull request Jul 14, 2025

rustdoc --test doesn't recognize register_tool rust-lang/rust#143930

Closed

joshtriplett merged commit b145b2e into rust-lang:master Jul 30, 2025

fmease mentioned this pull request Jul 30, 2025

Tracking Issue for -Z crate-attr rust-lang/rust#138287

Open

8 tasks

jyn514 deleted the crate-attr branch August 1, 2026 16:17

		The `--crate-attr` flag allows you to inject attributes into the crate root.
		For example, `--crate-attr=crate_name="test"` acts as if `#![crate_name="test"]` were present before the first source line of the crate root.


		Additionally, some existing CLI options could have been useful as attributes. This leads to the second group: Maintainers of the Rust language. Often we need to decide between attributes and flags; either we duplicate features between the two (lints, `crate-name`, `crate-type`), or we make it harder to configure the options for stakeholder group 1.

		The third group is the authors of external tools. The [original motivation][impl] for this feature was for Crater, which wanted to enable a rustfix feature in all crates it built without having to modify the source code. Other motivations include the currently-unstable [`register-tool`], which with this RFC could be an attribute passed by the external tool (or configured in the workspace), and [build-std], which wants to inject `no_std` into all crates being compiled.

Uh oh!

Conversation

jyn514 commented Mar 17, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyn514 Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jieyouxu Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Mark-Simulacrum commented Mar 30, 2025

Uh oh!

rfcbot commented Mar 30, 2025 • edited by compiler-errors Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apiraino commented Apr 10, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Noratrieb May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rfcbot commented Jun 17, 2025

Uh oh!

Uh oh!

rfcbot commented Jun 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

jyn514 commented Mar 17, 2025 •

edited by rustbot

Loading

jyn514 Mar 17, 2025 •

edited

Loading

fmease Mar 17, 2025 •

edited

Loading

jieyouxu Mar 17, 2025 •

edited

Loading

rfcbot commented Mar 30, 2025 •

edited by compiler-errors

Loading

Noratrieb May 29, 2025 •

edited

Loading