src/doc/rustc/src/lints/levels.md

   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 ```bash
  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,ignore
  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,ignore
 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.