3 In `rustc`, lints are divided into four *levels*:
10 Each lint has a default level (explained in the lint listing later in this
11 chapter), and the compiler has a default warning level. First, let's explain
12 what these levels mean, and then we'll talk about configuration.
16 These lints exist, but by default, do nothing. For example, consider this
23 Compiling this file produces no warnings:
26 $ rustc lib.rs --crate-type=lib
30 But this code violates the `missing_docs` lint.
32 These lints exist mostly to be manually turned on via configuration, as we'll
33 talk about later in this section.
37 The 'warn' lint level will produce a warning if you violate the lint. For example,
38 this code runs afoul of the `unused_variables` lint:
46 This will produce this warning:
49 $ rustc lib.rs --crate-type=lib
50 warning: unused variable: `x`
56 = note: `#[warn(unused_variables)]` on by default
57 = note: to avoid this warning, consider using `_x` instead
62 A 'deny' lint produces an error if you violate it. For example, this code
63 runs into the `exceeding_bitshifts` lint.
73 error: bitshift exceeds the type's number of bits
79 = note: `#[deny(exceeding_bitshifts)]` on by default
82 What's the difference between an error from a lint and a regular old error?
83 Lints are configurable via levels, so in a similar way to 'allow' lints,
84 warnings that are 'deny' by default let you allow them. Similarly, you may
85 wish to set up a lint that is `warn` by default to produce an error instead.
86 This lint level gives you that.
90 'forbid' is a special lint level that's stronger than 'deny'. It's the same
91 as 'deny' in that a lint at this level will produce an error, but unlike the
92 'deny' level, the 'forbid' level can not be overridden to be anything lower
93 than an error. However, lint levels may still be capped with `--cap-lints`
94 (see below) so `rustc --cap-lints warn` will make lints set to 'forbid' just
97 ## Configuring warning levels
99 Remember our `missing_docs` example from the 'allow' lint level?
104 $ rustc lib.rs --crate-type=lib
108 We can configure this lint to operate at a higher level, both with
109 compiler flags, as well as with an attribute in the source code.
111 You can also "cap" lints so that the compiler can choose to ignore
112 certain lint levels. We'll talk about that last.
114 ### Via compiler flag
116 The `-A`, `-W`, `-D`, and `-F` flags let you turn one or more lints
117 into allowed, warning, deny, or forbid levels, like this:
120 $ rustc lib.rs --crate-type=lib -W missing-docs
121 warning: missing documentation for crate
127 = note: requested on the command line with `-W missing-docs`
129 warning: missing documentation for a function
137 $ rustc lib.rs --crate-type=lib -D missing-docs
138 error: missing documentation for crate
144 = note: requested on the command line with `-D missing-docs`
146 error: missing documentation for a function
152 error: aborting due to 2 previous errors
155 You can also pass each flag more than once for changing multiple lints:
158 $ rustc lib.rs --crate-type=lib -D missing-docs -D unused-variables
161 And of course, you can mix these four flags together:
164 $ rustc lib.rs --crate-type=lib -D missing-docs -A unused-variables
167 The order of these command line arguments is taken into account. The following allows the `unused-variables` lint, because it is the last argument for that lint:
170 $ rustc lib.rs --crate-type=lib -D unused-variables -A unused-variables
173 You can make use of this behavior by overriding the level of one specific lint out of a group of lints. The following example denies all the lints in the `unused` group, but explicitly allows the `unused-variables` lint in that group (forbid still trumps everything regardless of ordering):
176 $ rustc lib.rs --crate-type=lib -D unused -A unused-variables
181 You can also modify the lint level with a crate-wide attribute:
185 #![warn(missing_docs)]
188 $ rustc lib.rs --crate-type=lib
189 warning: missing documentation for crate
192 1 | / #![warn(missing_docs)]
194 3 | | pub fn foo() {}
197 note: lint level defined here
200 1 | #![warn(missing_docs)]
203 warning: missing documentation for a function
210 All four, `warn`, `allow`, `deny`, and `forbid` all work this way.
212 You can also pass in multiple lints per attribute:
215 #![warn(missing_docs, unused_variables)]
220 And use multiple attributes together:
223 #![warn(missing_docs)]
224 #![deny(unused_variables)]
231 `rustc` supports a flag, `--cap-lints LEVEL` that sets the "lint cap level."
232 This is the maximum level for all lints. So for example, if we take our
233 code sample from the "deny" lint level above:
241 And we compile it, capping lints to warn:
244 $ rustc lib.rs --cap-lints warn
245 warning: bitshift exceeds the type's number of bits
251 = note: `#[warn(exceeding_bitshifts)]` on by default
253 warning: this expression will panic at run-time
257 | ^^^^^^^^^^^ attempt to shift left with overflow
260 It now only warns, rather than errors. We can go further and allow all lints:
263 $ rustc lib.rs --cap-lints allow
267 This feature is used heavily by Cargo; it will pass `--cap-lints allow` when
268 compiling your dependencies, so that if they have any warnings, they do not
269 pollute the output of your build.