Doc: clarify priority of lint level sources #142021
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This updates the rustc book to clearly document how conflicting lint configurations are resolved across different sources, including command-line flags, crate-level attributes, in-line attributes, and `--cap-lints`. It also explains the special behavior of `forbid` and `force_warn`.
rustbot
added
the
S-waiting-on-review
|
The job Click to see the possible cause of the failure (guessed by this bot) |
jieyouxu
reviewed
Jun 4, 2025
|
|
||
| ## Priority of Lint Level Sources | ||
|
|
||
| Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect. |
There was a problem hiding this comment.
Some general remarks (I don't have bandwidth to take over review for this ATM):
- I wonder if we should explicitly delineate between lint level control mechanisms which are compiler-only, versus those part of the language (such as in-source lint level attributes).
- I'm not so sure the priority order is well-defined. See Support overriding
warningslevel for a specific lint via command line #113307 (comment). - Note that the ordering of compiler flags can matter! Some flags are "commutative" (in terms of observable final behavior) with respect to each other IIRC, while some flags aren't.
- (Unstable, not suitable for stable rustc book) there's also the
--crate-attrflag, which can somewhat blur the line between compiler vs language.
There was a problem hiding this comment.
Thanks for the feedback! I took a closer look and I think you're right. If that's the case, it might be best to just document the ordering for in-source lint level attributes, where the behavior is straightforward: the closer attribute takes precedence.
jieyouxu
added
A-lints
ehuss
reviewed
Jun 5, 2025
|
|
||
| ## Priority of Lint Level Sources | ||
|
|
||
| Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect. |
There was a problem hiding this comment.
What is a "global compiler configuration"?
|
|
||
| Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect. | ||
|
|
||
| This section explains how Rust resolves conflicts between **different sources of lint configuration**, rather than between the lint levels themselves. |
There was a problem hiding this comment.
Wording nit:
Suggested change
| This section explains how Rust resolves conflicts between **different sources of lint configuration**, rather than between the lint levels themselves. | |
| This section explains how conflicts are resolved between **different sources of lint configuration**, rather than between the lint levels themselves. |
|
|
||
| This section explains how Rust resolves conflicts between **different sources of lint configuration**, rather than between the lint levels themselves. | ||
|
|
||
| ### Priority of Sources (Highest to Lowest) |
There was a problem hiding this comment.
Usually use sentence case for section titles.
Suggested change
| ### Priority of Sources (Highest to Lowest) | |
| ### Priority of sources (highest to lowest) |
Comment on lines
+345
to
+346
| in-line attributes (#[...]) > | ||
| crate-level attributes (#![...]) > |
There was a problem hiding this comment.
I think the way this is presented is possibly confusing. The language doesn't differentiate between inner and outer attributes for lint levels. It just so happens that crate-level can only be specified by an inner attribute. But inner attributes can show up in many places. I would probably just say "attributes" here, since attributes just create an AST-hierarchy with the most-specific taking precedence.
| command-line flags (-A, -W, -D) | ||
| ``` | ||
|
|
||
| ### Special Cases |
There was a problem hiding this comment.
Suggested change
| ### Special Cases | |
| ### Special case priorities |
|
|
||
| ### Special Cases | ||
|
|
||
| The special levels `forbid(lint)` and `force_warn(lint)` take precedence over normal configurations **regardless of where they are set**. |
There was a problem hiding this comment.
The use of parentheses looks a little strange here to me, since force_warn(lint) isn't a valid syntax anywhere. How about just something like this?
Suggested change
| The special levels `forbid(lint)` and `force_warn(lint)` take precedence over normal configurations **regardless of where they are set**. | |
| The special levels forbid and force-warn take precedence over normal configurations **regardless of where they are set**. |
I don't know what "normal configurations" are.
Also, this doesn't seem quite accurate to me. cap-lints takes precedence over forbid.
And in a sense it does matter where forbid is set, since it applies only to the AST-hierarchy below where it is set.
force-warn can only be set in one place (the CLI), though I'm not sure if this is trying to convey something about the order of CLI arguments?
This doesn't say how forbid and force-warn interact with one another.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This updates the rustc book to clearly document how conflicting lint configurations are resolved across different sources, including command-line flags, crate-level attributes, in-line attributes, and
--cap-lints.It also explains the special behavior of
forbidandforce_warn.Fixes #124088