|
1 | 1 | # Lint levels |
| 2 | + |
| 3 | +In `rustc`, lints are divided into four *levels*: |
| 4 | + |
| 5 | +1. allow |
| 6 | +2. warn |
| 7 | +3. deny |
| 8 | +4. forbid |
| 9 | + |
| 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. |
| 13 | + |
| 14 | +## allow |
| 15 | + |
| 16 | +These lints exist, but by default, do nothing. For example, consider this |
| 17 | +source: |
| 18 | + |
| 19 | +```rust |
| 20 | +pub fn foo() {} |
| 21 | +``` |
| 22 | + |
| 23 | +Compiling this file produces no warnings: |
| 24 | + |
| 25 | +```rust |
| 26 | +$ rustc lib.rs --crate-type=lib |
| 27 | +$ |
| 28 | +``` |
| 29 | + |
| 30 | +But this code violates the `missing_docs` lint. |
| 31 | + |
| 32 | +These lints exist mostly to be manually turned on via configuration, as we'll |
| 33 | +talk about later in this section. |
| 34 | + |
| 35 | +## warn |
| 36 | + |
| 37 | +The 'warn' lint level will produce a warning if you violate the lint. For example, |
| 38 | +this code runs afoul of the `unused_variable` lint: |
| 39 | + |
| 40 | +```rust |
| 41 | +pub fn foo() { |
| 42 | + let x = 5; |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +This will produce this warning: |
| 47 | + |
| 48 | +```bash |
| 49 | +> rustc lib.rs --crate-type=lib |
| 50 | +warning: unused variable: `x` |
| 51 | + --> lib.rs:2:9 |
| 52 | + | |
| 53 | +2 | let x = 5; |
| 54 | + | ^ |
| 55 | + | |
| 56 | + = note: #[warn(unused_variables)] on by default |
| 57 | + = note: to avoid this warning, consider using `_x` instead |
| 58 | +``` |
| 59 | + |
| 60 | +## deny |
| 61 | + |
| 62 | +A 'deny' lint produces an error if you violate it. For example, this code |
| 63 | +runs into the `exceeding_bitshifts` lint. |
| 64 | + |
| 65 | +```rust |
| 66 | +fn main() { |
| 67 | + 100u8 << 10; |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +```bash |
| 72 | +> rustc main.rs |
| 73 | +error: bitshift exceeds the type's number of bits |
| 74 | + --> main.rs:2:13 |
| 75 | + | |
| 76 | +2 | 100u8 << 10; |
| 77 | + | ^^^^^^^^^^^ |
| 78 | + | |
| 79 | + = note: #[deny(exceeding_bitshifts)] on by default |
| 80 | +``` |
| 81 | +
|
| 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. |
| 87 | + |
| 88 | +## forbid |
| 89 | + |
| 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. |
| 94 | + |
| 95 | +## Configuring warning levels |
| 96 | + |
| 97 | +Remember our `missing_docs` example from the 'allow' lint level? |
| 98 | + |
| 99 | +```bash |
| 100 | +$ cat lib.rs |
| 101 | +pub fn foo() {} |
| 102 | +$ rustc lib.rs --crate-type=lib |
| 103 | +$ |
| 104 | +``` |
| 105 | + |
| 106 | +We can configure this lint to operate at a higher level, both with |
| 107 | +compiler flags, as well as with an attribute in the source code. |
| 108 | + |
| 109 | +You can also "cap" lints so that the compiler can choose to ignore |
| 110 | +certain lint levels. We'll talk about that last. |
| 111 | +
|
| 112 | +### Via compiler flag |
| 113 | +
|
| 114 | +The `-A`, `-W`, `-D`, and `-F` flags let you turn one or more lints |
| 115 | +into allowed, warning, deny, or forbid levels, like this: |
| 116 | +
|
| 117 | +```bash |
| 118 | +$ rustc lib.rs --crate-type=lib -W missing-docs |
| 119 | +warning: missing documentation for crate |
| 120 | + --> lib.rs:1:1 |
| 121 | + | |
| 122 | +1 | pub fn foo() {} |
| 123 | + | ^^^^^^^^^^^^ |
| 124 | + | |
| 125 | + = note: requested on the command line with `-W missing-docs` |
| 126 | +
|
| 127 | +warning: missing documentation for a function |
| 128 | + --> lib.rs:1:1 |
| 129 | + | |
| 130 | +1 | pub fn foo() {} |
| 131 | + | ^^^^^^^^^^^^ |
| 132 | +> rustc lib.rs --crate-type=lib -D missing-docs |
| 133 | +error: missing documentation for crate |
| 134 | + --> lib.rs:1:1 |
| 135 | + | |
| 136 | +1 | pub fn foo() {} |
| 137 | + | ^^^^^^^^^^^^ |
| 138 | + | |
| 139 | + = note: requested on the command line with `-D missing-docs` |
| 140 | +
|
| 141 | +error: missing documentation for a function |
| 142 | + --> lib.rs:1:1 |
| 143 | + | |
| 144 | +1 | pub fn foo() {} |
| 145 | + | ^^^^^^^^^^^^ |
| 146 | +
|
| 147 | +error: aborting due to 2 previous errors |
| 148 | +``` |
| 149 | +
|
| 150 | +You can also pass each flag more than once for changing multiple lints: |
| 151 | +
|
| 152 | +```bash |
| 153 | +rustc lib.rs --crate-type=lib -D missing-docs -D unused-variables |
| 154 | +``` |
| 155 | +
|
| 156 | +And of course, you can mix these four flags together: |
| 157 | +
|
| 158 | +```bash |
| 159 | +rustc lib.rs --crate-type=lib -D missing-docs -A unused-variables |
| 160 | +``` |
| 161 | +
|
| 162 | +### Via an attribute |
| 163 | +
|
| 164 | +You can also modify the lint level with a crate-wide attribute: |
| 165 | +
|
| 166 | +```bash |
| 167 | +> cat lib.rs |
| 168 | +#![warn(missing_docs)] |
| 169 | +
|
| 170 | +pub fn foo() {} |
| 171 | +$ rustc lib.rs --crate-type=lib |
| 172 | +warning: missing documentation for crate |
| 173 | + --> lib.rs:1:1 |
| 174 | + | |
| 175 | +1 | / #![warn(missing_docs)] |
| 176 | +2 | | |
| 177 | +3 | | pub fn foo() {} |
| 178 | + | |_______________^ |
| 179 | + | |
| 180 | +note: lint level defined here |
| 181 | + --> lib.rs:1:9 |
| 182 | + | |
| 183 | +1 | #![warn(missing_docs)] |
| 184 | + | ^^^^^^^^^^^^ |
| 185 | +
|
| 186 | +warning: missing documentation for a function |
| 187 | + --> lib.rs:3:1 |
| 188 | + | |
| 189 | +3 | pub fn foo() {} |
| 190 | + | ^^^^^^^^^^^^ |
| 191 | +``` |
| 192 | +
|
| 193 | +All four, `warn`, `allow`, `deny`, and `forbid` all work this way. |
| 194 | +
|
| 195 | +You can also pass in multiple lints per attribute: |
| 196 | +
|
| 197 | +```rust |
| 198 | +#![warn(missing_docs, unused_variables)] |
| 199 | +
|
| 200 | +pub fn foo() {} |
| 201 | +``` |
| 202 | +
|
| 203 | +And use multiple attributes together: |
| 204 | +
|
| 205 | +```rust |
| 206 | +#![warn(missing_docs)] |
| 207 | +#![deny(unused_variables)] |
| 208 | +
|
| 209 | +pub fn foo() {} |
| 210 | +``` |
| 211 | +
|
| 212 | +### Capping lints |
| 213 | +
|
| 214 | +`rustc` supports a flag, `--cap-lints LEVEL` that sets the "lint cap level." |
| 215 | +This is the maximum level for all lints. So for example, if we take our |
| 216 | +code sample from the "deny" lint level above: |
| 217 | +
|
| 218 | +```rust |
| 219 | +fn main() { |
| 220 | + 100u8 << 10; |
| 221 | +} |
| 222 | +``` |
| 223 | +
|
| 224 | +And we compile it, capping lints to warn: |
| 225 | +
|
| 226 | +```bash |
| 227 | +$ rustc lib.rs --cap-lints warn |
| 228 | +warning: bitshift exceeds the type's number of bits |
| 229 | + --> lib.rs:2:5 |
| 230 | + | |
| 231 | +2 | 100u8 << 10; |
| 232 | + | ^^^^^^^^^^^ |
| 233 | + | |
| 234 | + = note: #[warn(exceeding_bitshifts)] on by default |
| 235 | +
|
| 236 | +warning: this expression will panic at run-time |
| 237 | + --> lib.rs:2:5 |
| 238 | + | |
| 239 | +2 | 100u8 << 10; |
| 240 | + | ^^^^^^^^^^^ attempt to shift left with overflow |
| 241 | +``` |
| 242 | +
|
| 243 | +It now only warns, rather than errors. We can go further and allow all lints: |
| 244 | +
|
| 245 | +```bash |
| 246 | +$ rustc lib.rs --cap-lints allow |
| 247 | +$ |
| 248 | +``` |
| 249 | +
|
| 250 | +This feature is used heavily by Cargo; it will pass `--cap-lints allow` when |
| 251 | +compiling your dependencies, so that if they have any warnings, they do not |
| 252 | +pollute the output of your build. |
0 commit comments