src/doc/rustc/src/lints/index.md

   1 # Lints
   2
   3 In software, a "lint" is a tool used to help improve your source code. The
   4 Rust compiler contains a number of lints, and when it compiles your code, it will
   5 also run the lints. These lints may produce a warning, an error, or nothing at all,
   6 depending on how you've configured things.
   7
   8 Here's a small example:
   9
  10 ```bash
  11 $ cat main.rs
  12 fn main() {
  13     let x = 5;
  14 }
  15 $ rustc main.rs
  16 warning: unused variable: `x`
  17  --> main.rs:2:9
  18   |
  19 2 |     let x = 5;
  20   |         ^
  21   |
  22   = note: `#[warn(unused_variables)]` on by default
  23   = note: to avoid this warning, consider using `_x` instead
  24 ```
  25
  26 This is the `unused_variables` lint, and it tells you that you've introduced
  27 a variable that you don't use in your code. That's not *wrong*, so it's not
  28 an error, but it might be a bug, so you get a warning.
  29
  30 ## Future-incompatible lints
  31
  32 Sometimes the compiler needs to be changed to fix an issue that can cause
  33 existing code to stop compiling. "Future-incompatible" lints are issued in
  34 these cases to give users of Rust a smooth transition to the new behavior.
  35 Initially, the compiler will continue to accept the problematic code and issue
  36 a warning. The warning has a description of the problem, a notice that this
  37 will become an error in the future, and a link to a tracking issue that
  38 provides detailed information and an opportunity for feedback. This gives
  39 users some time to fix the code to accommodate the change. After some time,
  40 the warning may become an error.
  41
  42 The following is an example of what a future-incompatible looks like:
  43
  44 ```text
  45 warning: borrow of packed field is unsafe and requires unsafe function or block (error E0133)
  46   --> lint_example.rs:11:13
  47    |
  48 11 |     let y = &x.data.0;
  49    |             ^^^^^^^^^
  50    |
  51    = note: `#[warn(safe_packed_borrows)]` on by default
  52    = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  53    = note: for more information, see issue #46043 <https://github.com/rust-lang/rust/issues/46043>
  54    = note: fields of packed structs might be misaligned: dereferencing a misaligned pointer or even just creating a misaligned reference is undefined behavior
  55 ```
  56
  57 For more information about the process and policy of future-incompatible
  58 changes, see [RFC 1589].
  59
  60 [RFC 1589]: https://github.com/rust-lang/rfcs/blob/master/text/1589-rustc-bug-fix-procedure.md