src/tools/clippy/book/src/development/adding_lints.md

   1 # Adding a new lint
   2
   3 You are probably here because you want to add a new lint to Clippy. If this is
   4 the first time you're contributing to Clippy, this document guides you through
   5 creating an example lint from scratch.
   6
   7 To get started, we will create a lint that detects functions called `foo`,
   8 because that's clearly a non-descriptive name.
   9
  10 - [Adding a new lint](#adding-a-new-lint)
  11   - [Setup](#setup)
  12   - [Getting Started](#getting-started)
  13   - [Testing](#testing)
  14     - [Cargo lints](#cargo-lints)
  15   - [Rustfix tests](#rustfix-tests)
  16   - [Testing manually](#testing-manually)
  17   - [Lint declaration](#lint-declaration)
  18   - [Lint registration](#lint-registration)
  19   - [Lint passes](#lint-passes)
  20   - [Emitting a lint](#emitting-a-lint)
  21   - [Adding the lint logic](#adding-the-lint-logic)
  22   - [Specifying the lint's minimum supported Rust version (MSRV)](#specifying-the-lints-minimum-supported-rust-version-msrv)
  23   - [Author lint](#author-lint)
  24   - [Print HIR lint](#print-hir-lint)
  25   - [Documentation](#documentation)
  26   - [Running rustfmt](#running-rustfmt)
  27   - [Debugging](#debugging)
  28   - [PR Checklist](#pr-checklist)
  29   - [Adding configuration to a lint](#adding-configuration-to-a-lint)
  30   - [Cheat Sheet](#cheat-sheet)
  31
  32 ## Setup
  33
  34 See the [Basics](basics.md#get-the-code) documentation.
  35
  36 ## Getting Started
  37
  38 There is a bit of boilerplate code that needs to be set up when creating a new
  39 lint. Fortunately, you can use the clippy dev tools to handle this for you. We
  40 are naming our new lint `foo_functions` (lints are generally written in snake
  41 case), and we don't need type information so it will have an early pass type
  42 (more on this later on). If you're not sure if the name you chose fits the lint,
  43 take a look at our [lint naming guidelines][lint_naming]. To get started on this
  44 lint you can run `cargo dev new_lint --name=foo_functions --pass=early
  45 --category=pedantic` (category will default to nursery if not provided). This
  46 command will create two files: `tests/ui/foo_functions.rs` and
  47 `clippy_lints/src/foo_functions.rs`, as well as [registering the
  48 lint](#lint-registration). For cargo lints, two project hierarchies (fail/pass)
  49 will be created by default under `tests/ui-cargo`.
  50
  51 Next, we'll open up these files and add our lint!
  52
  53 ## Testing
  54
  55 Let's write some tests first that we can execute while we iterate on our lint.
  56
  57 Clippy uses UI tests for testing. UI tests check that the output of Clippy is
  58 exactly as expected. Each test is just a plain Rust file that contains the code
  59 we want to check. The output of Clippy is compared against a `.stderr` file.
  60 Note that you don't have to create this file yourself, we'll get to generating
  61 the `.stderr` files further down.
  62
  63 We start by opening the test file created at `tests/ui/foo_functions.rs`.
  64
  65 Update the file with some examples to get started:
  66
  67 ```rust
  68 #![warn(clippy::foo_functions)]
  69
  70 // Impl methods
  71 struct A;
  72 impl A {
  73     pub fn fo(&self) {}
  74     pub fn foo(&self) {}
  75     pub fn food(&self) {}
  76 }
  77
  78 // Default trait methods
  79 trait B {
  80     fn fo(&self) {}
  81     fn foo(&self) {}
  82     fn food(&self) {}
  83 }
  84
  85 // Plain functions
  86 fn fo() {}
  87 fn foo() {}
  88 fn food() {}
  89
  90 fn main() {
  91     // We also don't want to lint method calls
  92     foo();
  93     let a = A;
  94     a.foo();
  95 }
  96 ```
  97
  98 Now we can run the test with `TESTNAME=foo_functions cargo uitest`, currently
  99 this test is meaningless though.
 100
 101 While we are working on implementing our lint, we can keep running the UI test.
 102 That allows us to check if the output is turning into what we want.
 103
 104 Once we are satisfied with the output, we need to run `cargo dev bless` to
 105 update the `.stderr` file for our lint. Please note that, we should run
 106 `TESTNAME=foo_functions cargo uitest` every time before running `cargo dev
 107 bless`. Running `TESTNAME=foo_functions cargo uitest` should pass then. When we
 108 commit our lint, we need to commit the generated `.stderr` files, too. In
 109 general, you should only commit files changed by `cargo dev bless` for the
 110 specific lint you are creating/editing. Note that if the generated files are
 111 empty, they should be removed.
 112
 113 > _Note:_ you can run multiple test files by specifying a comma separated list:
 114 > `TESTNAME=foo_functions,test2,test3`.
 115
 116 ### Cargo lints
 117
 118 For cargo lints, the process of testing differs in that we are interested in the
 119 `Cargo.toml` manifest file. We also need a minimal crate associated with that
 120 manifest.
 121
 122 If our new lint is named e.g. `foo_categories`, after running `cargo dev
 123 new_lint` we will find by default two new crates, each with its manifest file:
 124
 125 * `tests/ui-cargo/foo_categories/fail/Cargo.toml`: this file should cause the
 126   new lint to raise an error.
 127 * `tests/ui-cargo/foo_categories/pass/Cargo.toml`: this file should not trigger
 128   the lint.
 129
 130 If you need more cases, you can copy one of those crates (under
 131 `foo_categories`) and rename it.
 132
 133 The process of generating the `.stderr` file is the same, and prepending the
 134 `TESTNAME` variable to `cargo uitest` works too.
 135
 136 ## Rustfix tests
 137
 138 If the lint you are working on is making use of structured suggestions, the test
 139 file should include a `// run-rustfix` comment at the top. This will
 140 additionally run [rustfix] for that test. Rustfix will apply the suggestions
 141 from the lint to the code of the test file and compare that to the contents of a
 142 `.fixed` file.
 143
 144 Use `cargo dev bless` to automatically generate the `.fixed` file after running
 145 the tests.
 146
 147 [rustfix]: https://github.com/rust-lang/rustfix
 148
 149 ## Testing manually
 150
 151 Manually testing against an example file can be useful if you have added some
 152 `println!`s and the test suite output becomes unreadable. To try Clippy with
 153 your local modifications, run
 154
 155 ```
 156 cargo dev lint input.rs
 157 ```
 158
 159 from the working copy root. With tests in place, let's have a look at
 160 implementing our lint now.
 161
 162 ## Lint declaration
 163
 164 Let's start by opening the new file created in the `clippy_lints` crate at
 165 `clippy_lints/src/foo_functions.rs`. That's the crate where all the lint code
 166 is. This file has already imported some initial things we will need:
 167
 168 ```rust
 169 use rustc_lint::{EarlyLintPass, EarlyContext};
 170 use rustc_session::{declare_lint_pass, declare_tool_lint};
 171 use rustc_ast::ast::*;
 172 ```
 173
 174 The next step is to update the lint declaration. Lints are declared using the
 175 [`declare_clippy_lint!`][declare_clippy_lint] macro, and we just need to update
 176 the auto-generated lint declaration to have a real description, something like
 177 this:
 178
 179 ```rust
 180 declare_clippy_lint! {
 181     /// ### What it does
 182     ///
 183     /// ### Why is this bad?
 184     ///
 185     /// ### Example
 186     /// ```rust
 187     /// // example code
 188     /// ```
 189     #[clippy::version = "1.29.0"]
 190     pub FOO_FUNCTIONS,
 191     pedantic,
 192     "function named `foo`, which is not a descriptive name"
 193 }
 194 ```
 195
 196 * The section of lines prefixed with `///` constitutes the lint documentation
 197   section. This is the default documentation style and will be displayed [like
 198   this][example_lint_page]. To render and open this documentation locally in a
 199   browser, run `cargo dev serve`.
 200 * The `#[clippy::version]` attribute will be rendered as part of the lint
 201   documentation. The value should be set to the current Rust version that the
 202   lint is developed in, it can be retrieved by running `rustc -vV` in the
 203   rust-clippy directory. The version is listed under *release*. (Use the version
 204   without the `-nightly`) suffix.
 205 * `FOO_FUNCTIONS` is the name of our lint. Be sure to follow the [lint naming
 206   guidelines][lint_naming] here when naming your lint. In short, the name should
 207   state the thing that is being checked for and read well when used with
 208   `allow`/`warn`/`deny`.
 209 * `pedantic` sets the lint level to `Allow`. The exact mapping can be found
 210   [here][category_level_mapping]
 211 * The last part should be a text that explains what exactly is wrong with the
 212   code
 213
 214 The rest of this file contains an empty implementation for our lint pass, which
 215 in this case is `EarlyLintPass` and should look like this:
 216
 217 ```rust
 218 // clippy_lints/src/foo_functions.rs
 219
 220 // .. imports and lint declaration ..
 221
 222 declare_lint_pass!(FooFunctions => [FOO_FUNCTIONS]);
 223
 224 impl EarlyLintPass for FooFunctions {}
 225 ```
 226
 227 [declare_clippy_lint]: https://github.com/rust-lang/rust-clippy/blob/557f6848bd5b7183f55c1e1522a326e9e1df6030/clippy_lints/src/lib.rs#L60
 228 [example_lint_page]: https://rust-lang.github.io/rust-clippy/master/index.html#redundant_closure
 229 [lint_naming]: https://rust-lang.github.io/rfcs/0344-conventions-galore.html#lints
 230 [category_level_mapping]: https://github.com/rust-lang/rust-clippy/blob/557f6848bd5b7183f55c1e1522a326e9e1df6030/clippy_lints/src/lib.rs#L110
 231
 232 ## Lint registration
 233
 234 When using `cargo dev new_lint`, the lint is automatically registered and
 235 nothing more has to be done.
 236
 237 When declaring a new lint by hand and `cargo dev update_lints` is used, the lint
 238 pass may have to be registered manually in the `register_plugins` function in
 239 `clippy_lints/src/lib.rs`:
 240
 241 ```rust
 242 store.register_early_pass(|| Box::new(foo_functions::FooFunctions));
 243 ```
 244
 245 As one may expect, there is a corresponding `register_late_pass` method
 246 available as well. Without a call to one of `register_early_pass` or
 247 `register_late_pass`, the lint pass in question will not be run.
 248
 249 One reason that `cargo dev update_lints` does not automate this step is that
 250 multiple lints can use the same lint pass, so registering the lint pass may
 251 already be done when adding a new lint. Another reason that this step is not
 252 automated is that the order that the passes are registered determines the order
 253 the passes actually run, which in turn affects the order that any emitted lints
 254 are output in.
 255
 256 ## Lint passes
 257
 258 Writing a lint that only checks for the name of a function means that we only
 259 have to deal with the AST and don't have to deal with the type system at all.
 260 This is good, because it makes writing this particular lint less complicated.
 261
 262 We have to make this decision with every new Clippy lint. It boils down to using
 263 either [`EarlyLintPass`][early_lint_pass] or [`LateLintPass`][late_lint_pass].
 264
 265 In short, the `LateLintPass` has access to type information while the
 266 `EarlyLintPass` doesn't. If you don't need access to type information, use the
 267 `EarlyLintPass`. The `EarlyLintPass` is also faster. However linting speed
 268 hasn't really been a concern with Clippy so far.
 269
 270 Since we don't need type information for checking the function name, we used
 271 `--pass=early` when running the new lint automation and all the imports were
 272 added accordingly.
 273
 274 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html
 275 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html
 276
 277 ## Emitting a lint
 278
 279 With UI tests and the lint declaration in place, we can start working on the
 280 implementation of the lint logic.
 281
 282 Let's start by implementing the `EarlyLintPass` for our `FooFunctions`:
 283
 284 ```rust
 285 impl EarlyLintPass for FooFunctions {
 286     fn check_fn(&mut self, cx: &EarlyContext<'_>, fn_kind: FnKind<'_>, span: Span, _: NodeId) {
 287         // TODO: Emit lint here
 288     }
 289 }
 290 ```
 291
 292 We implement the [`check_fn`][check_fn] method from the
 293 [`EarlyLintPass`][early_lint_pass] trait. This gives us access to various
 294 information about the function that is currently being checked. More on that in
 295 the next section. Let's worry about the details later and emit our lint for
 296 *every* function definition first.
 297
 298 Depending on how complex we want our lint message to be, we can choose from a
 299 variety of lint emission functions. They can all be found in
 300 [`clippy_utils/src/diagnostics.rs`][diagnostics].
 301
 302 `span_lint_and_help` seems most appropriate in this case. It allows us to
 303 provide an extra help message and we can't really suggest a better name
 304 automatically. This is how it looks:
 305
 306 ```rust
 307 impl EarlyLintPass for FooFunctions {
 308     fn check_fn(&mut self, cx: &EarlyContext<'_>, fn_kind: FnKind<'_>, span: Span, _: NodeId) {
 309         span_lint_and_help(
 310             cx,
 311             FOO_FUNCTIONS,
 312             span,
 313             "function named `foo`",
 314             None,
 315             "consider using a more meaningful name"
 316         );
 317     }
 318 }
 319 ```
 320
 321 Running our UI test should now produce output that contains the lint message.
 322
 323 According to [the rustc-dev-guide], the text should be matter of fact and avoid
 324 capitalization and periods, unless multiple sentences are needed. When code or
 325 an identifier must appear in a message or label, it should be surrounded with
 326 single grave accents \`.
 327
 328 [check_fn]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html#method.check_fn
 329 [diagnostics]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/diagnostics.rs
 330 [the rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/diagnostics.html
 331
 332 ## Adding the lint logic
 333
 334 Writing the logic for your lint will most likely be different from our example,
 335 so this section is kept rather short.
 336
 337 Using the [`check_fn`][check_fn] method gives us access to [`FnKind`][fn_kind]
 338 that has the [`FnKind::Fn`] variant. It provides access to the name of the
 339 function/method via an [`Ident`][ident].
 340
 341 With that we can expand our `check_fn` method to:
 342
 343 ```rust
 344 impl EarlyLintPass for FooFunctions {
 345     fn check_fn(&mut self, cx: &EarlyContext<'_>, fn_kind: FnKind<'_>, span: Span, _: NodeId) {
 346         if is_foo_fn(fn_kind) {
 347             span_lint_and_help(
 348                 cx,
 349                 FOO_FUNCTIONS,
 350                 span,
 351                 "function named `foo`",
 352                 None,
 353                 "consider using a more meaningful name"
 354             );
 355         }
 356     }
 357 }
 358 ```
 359
 360 We separate the lint conditional from the lint emissions because it makes the
 361 code a bit easier to read. In some cases this separation would also allow to
 362 write some unit tests (as opposed to only UI tests) for the separate function.
 363
 364 In our example, `is_foo_fn` looks like:
 365
 366 ```rust
 367 // use statements, impl EarlyLintPass, check_fn, ..
 368
 369 fn is_foo_fn(fn_kind: FnKind<'_>) -> bool {
 370     match fn_kind {
 371         FnKind::Fn(_, ident, ..) => {
 372             // check if `fn` name is `foo`
 373             ident.name.as_str() == "foo"
 374         }
 375         // ignore closures
 376         FnKind::Closure(..) => false
 377     }
 378 }
 379 ```
 380
 381 Now we should also run the full test suite with `cargo test`. At this point
 382 running `cargo test` should produce the expected output. Remember to run `cargo
 383 dev bless` to update the `.stderr` file.
 384
 385 `cargo test` (as opposed to `cargo uitest`) will also ensure that our lint
 386 implementation is not violating any Clippy lints itself.
 387
 388 That should be it for the lint implementation. Running `cargo test` should now
 389 pass.
 390
 391 [fn_kind]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/visit/enum.FnKind.html
 392 [`FnKind::Fn`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/visit/enum.FnKind.html#variant.Fn
 393 [ident]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/symbol/struct.Ident.html
 394
 395 ## Specifying the lint's minimum supported Rust version (MSRV)
 396
 397 Sometimes a lint makes suggestions that require a certain version of Rust. For
 398 example, the `manual_strip` lint suggests using `str::strip_prefix` and
 399 `str::strip_suffix` which is only available after Rust 1.45. In such cases, you
 400 need to ensure that the MSRV configured for the project is >= the MSRV of the
 401 required Rust feature. If multiple features are required, just use the one with
 402 a lower MSRV.
 403
 404 First, add an MSRV alias for the required feature in [`clippy_utils::msrvs`].
 405 This can be accessed later as `msrvs::STR_STRIP_PREFIX`, for example.
 406
 407 ```rust
 408 msrv_aliases! {
 409     ..
 410     1,45,0 { STR_STRIP_PREFIX }
 411 }
 412 ```
 413
 414 In order to access the project-configured MSRV, you need to have an `msrv` field
 415 in the LintPass struct, and a constructor to initialize the field. The `msrv`
 416 value is passed to the constructor in `clippy_lints/lib.rs`.
 417
 418 ```rust
 419 pub struct ManualStrip {
 420     msrv: Option<RustcVersion>,
 421 }
 422
 423 impl ManualStrip {
 424     #[must_use]
 425     pub fn new(msrv: Option<RustcVersion>) -> Self {
 426         Self { msrv }
 427     }
 428 }
 429 ```
 430
 431 The project's MSRV can then be matched against the feature MSRV in the LintPass
 432 using the `meets_msrv` utility function.
 433
 434 ``` rust
 435 if !meets_msrv(self.msrv, msrvs::STR_STRIP_PREFIX) {
 436     return;
 437 }
 438 ```
 439
 440 The project's MSRV can also be specified as an inner attribute, which overrides
 441 the value from `clippy.toml`. This can be accounted for using the
 442 `extract_msrv_attr!(LintContext)` macro and passing
 443 `LateContext`/`EarlyContext`.
 444
 445 ```rust
 446 impl<'tcx> LateLintPass<'tcx> for ManualStrip {
 447     fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx Expr<'_>) {
 448         ...
 449     }
 450     extract_msrv_attr!(LateContext);
 451 }
 452 ```
 453
 454 Once the `msrv` is added to the lint, a relevant test case should be added to
 455 `tests/ui/min_rust_version_attr.rs` which verifies that the lint isn't emitted
 456 if the project's MSRV is lower.
 457
 458 As a last step, the lint should be added to the lint documentation. This is done
 459 in `clippy_lints/src/utils/conf.rs`:
 460
 461 ```rust
 462 define_Conf! {
 463     /// Lint: LIST, OF, LINTS, <THE_NEWLY_ADDED_LINT>. The minimum rust version that the project supports
 464     (msrv: Option<String> = None),
 465     ...
 466 }
 467 ```
 468
 469 [`clippy_utils::msrvs`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/msrvs/index.html
 470
 471 ## Author lint
 472
 473 If you have trouble implementing your lint, there is also the internal `author`
 474 lint to generate Clippy code that detects the offending pattern. It does not
 475 work for all of the Rust syntax, but can give a good starting point.
 476
 477 The quickest way to use it, is the [Rust playground:
 478 play.rust-lang.org][author_example]. Put the code you want to lint into the
 479 editor and add the `#[clippy::author]` attribute above the item. Then run Clippy
 480 via `Tools -> Clippy` and you should see the generated code in the output below.
 481
 482 [Here][author_example] is an example on the playground.
 483
 484 If the command was executed successfully, you can copy the code over to where
 485 you are implementing your lint.
 486
 487 [author_example]: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2018&gist=9a12cb60e5c6ad4e3003ac6d5e63cf55
 488
 489 ## Print HIR lint
 490
 491 To implement a lint, it's helpful to first understand the internal
 492 representation that rustc uses. Clippy has the `#[clippy::dump]` attribute that
 493 prints the [_High-Level Intermediate Representation (HIR)_] of the item,
 494 statement, or expression that the attribute is attached to. To attach the
 495 attribute to expressions you often need to enable
 496 `#![feature(stmt_expr_attributes)]`.
 497
 498 [Here][print_hir_example] you can find an example, just select _Tools_ and run
 499 _Clippy_.
 500
 501 [_High-Level Intermediate Representation (HIR)_]: https://rustc-dev-guide.rust-lang.org/hir.html
 502 [print_hir_example]: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=daf14db3a7f39ca467cd1b86c34b9afb
 503
 504 ## Documentation
 505
 506 The final thing before submitting our PR is to add some documentation to our
 507 lint declaration.
 508
 509 Please document your lint with a doc comment akin to the following:
 510
 511 ```rust
 512 declare_clippy_lint! {
 513     /// ### What it does
 514     /// Checks for ... (describe what the lint matches).
 515     ///
 516     /// ### Why is this bad?
 517     /// Supply the reason for linting the code.
 518     ///
 519     /// ### Example
 520     ///
 521     /// ```rust,ignore
 522     /// // A short example of code that triggers the lint
 523     /// ```
 524     ///
 525     /// Use instead:
 526     /// ```rust,ignore
 527     /// // A short example of improved code that doesn't trigger the lint
 528     /// ```
 529     #[clippy::version = "1.29.0"]
 530     pub FOO_FUNCTIONS,
 531     pedantic,
 532     "function named `foo`, which is not a descriptive name"
 533 }
 534 ```
 535
 536 Once your lint is merged, this documentation will show up in the [lint
 537 list][lint_list].
 538
 539 [lint_list]: https://rust-lang.github.io/rust-clippy/master/index.html
 540
 541 ## Running rustfmt
 542
 543 [Rustfmt] is a tool for formatting Rust code according to style guidelines. Your
 544 code has to be formatted by `rustfmt` before a PR can be merged. Clippy uses
 545 nightly `rustfmt` in the CI.
 546
 547 It can be installed via `rustup`:
 548
 549 ```bash
 550 rustup component add rustfmt --toolchain=nightly
 551 ```
 552
 553 Use `cargo dev fmt` to format the whole codebase. Make sure that `rustfmt` is
 554 installed for the nightly toolchain.
 555
 556 [Rustfmt]: https://github.com/rust-lang/rustfmt
 557
 558 ## Debugging
 559
 560 If you want to debug parts of your lint implementation, you can use the [`dbg!`]
 561 macro anywhere in your code. Running the tests should then include the debug
 562 output in the `stdout` part.
 563
 564 [`dbg!`]: https://doc.rust-lang.org/std/macro.dbg.html
 565
 566 ## PR Checklist
 567
 568 Before submitting your PR make sure you followed all of the basic requirements:
 569
 570 <!-- Sync this with `.github/PULL_REQUEST_TEMPLATE` -->
 571
 572 - \[ ] Followed [lint naming conventions][lint_naming]
 573 - \[ ] Added passing UI tests (including committed `.stderr` file)
 574 - \[ ] `cargo test` passes locally
 575 - \[ ] Executed `cargo dev update_lints`
 576 - \[ ] Added lint documentation
 577 - \[ ] Run `cargo dev fmt`
 578
 579 ## Adding configuration to a lint
 580
 581 Clippy supports the configuration of lints values using a `clippy.toml` file in
 582 the workspace directory. Adding a configuration to a lint can be useful for
 583 thresholds or to constrain some behavior that can be seen as a false positive
 584 for some users. Adding a configuration is done in the following steps:
 585
 586 1. Adding a new configuration entry to [`clippy_lints::utils::conf`] like this:
 587
 588    ```rust
 589    /// Lint: LINT_NAME.
 590    ///
 591    /// <The configuration field doc comment>
 592    (configuration_ident: Type = DefaultValue),
 593    ```
 594
 595    The doc comment is automatically added to the documentation of the listed
 596    lints. The default value will be formatted using the `Debug` implementation
 597    of the type.
 598 2. Adding the configuration value to the lint impl struct:
 599     1. This first requires the definition of a lint impl struct. Lint impl
 600        structs are usually generated with the `declare_lint_pass!` macro. This
 601        struct needs to be defined manually to add some kind of metadata to it:
 602        ```rust
 603        // Generated struct definition
 604        declare_lint_pass!(StructName => [
 605            LINT_NAME
 606        ]);
 607
 608        // New manual definition struct
 609        #[derive(Copy, Clone)]
 610        pub struct StructName {}
 611
 612        impl_lint_pass!(StructName => [
 613            LINT_NAME
 614        ]);
 615        ```
 616
 617     2. Next add the configuration value and a corresponding creation method like
 618        this:
 619        ```rust
 620        #[derive(Copy, Clone)]
 621        pub struct StructName {
 622            configuration_ident: Type,
 623        }
 624
 625        // ...
 626
 627        impl StructName {
 628            pub fn new(configuration_ident: Type) -> Self {
 629                Self {
 630                    configuration_ident,
 631                }
 632            }
 633        }
 634        ```
 635 3. Passing the configuration value to the lint impl struct:
 636
 637    First find the struct construction in the [`clippy_lints` lib file]. The
 638    configuration value is now cloned or copied into a local value that is then
 639    passed to the impl struct like this:
 640
 641    ```rust
 642    // Default generated registration:
 643    store.register_*_pass(|| box module::StructName);
 644
 645    // New registration with configuration value
 646    let configuration_ident = conf.configuration_ident.clone();
 647    store.register_*_pass(move || box module::StructName::new(configuration_ident));
 648    ```
 649
 650    Congratulations the work is almost done. The configuration value can now be
 651    accessed in the linting code via `self.configuration_ident`.
 652
 653 4. Adding tests:
 654     1. The default configured value can be tested like any normal lint in
 655        [`tests/ui`].
 656     2. The configuration itself will be tested separately in [`tests/ui-toml`].
 657        Simply add a new subfolder with a fitting name. This folder contains a
 658        `clippy.toml` file with the configuration value and a rust file that
 659        should be linted by Clippy. The test can otherwise be written as usual.
 660
 661 [`clippy_lints::utils::conf`]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/utils/conf.rs
 662 [`clippy_lints` lib file]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/lib.rs
 663 [`tests/ui`]: https://github.com/rust-lang/rust-clippy/blob/master/tests/ui
 664 [`tests/ui-toml`]: https://github.com/rust-lang/rust-clippy/blob/master/tests/ui-toml
 665
 666 ## Cheat Sheet
 667
 668 Here are some pointers to things you are likely going to need for every lint:
 669
 670 * [Clippy utils][utils] - Various helper functions. Maybe the function you need
 671   is already in here ([`is_type_diagnostic_item`], [`implements_trait`],
 672   [`snippet`], etc)
 673 * [Clippy diagnostics][diagnostics]
 674 * [Let chains][let-chains]
 675 * [`from_expansion`][from_expansion] and
 676   [`in_external_macro`][in_external_macro]
 677 * [`Span`][span]
 678 * [`Applicability`][applicability]
 679 * [Common tools for writing lints](common_tools_writing_lints.md) helps with
 680   common operations
 681 * [The rustc-dev-guide][rustc-dev-guide] explains a lot of internal compiler
 682   concepts
 683 * [The nightly rustc docs][nightly_docs] which has been linked to throughout
 684   this guide
 685
 686 For `EarlyLintPass` lints:
 687
 688 * [`EarlyLintPass`][early_lint_pass]
 689 * [`rustc_ast::ast`][ast]
 690
 691 For `LateLintPass` lints:
 692
 693 * [`LateLintPass`][late_lint_pass]
 694 * [`Ty::TyKind`][ty]
 695
 696 While most of Clippy's lint utils are documented, most of rustc's internals lack
 697 documentation currently. This is unfortunate, but in most cases you can probably
 698 get away with copying things from existing similar lints. If you are stuck,
 699 don't hesitate to ask on [Zulip] or in the issue/PR.
 700
 701 [utils]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/index.html
 702 [`is_type_diagnostic_item`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/ty/fn.is_type_diagnostic_item.html
 703 [`implements_trait`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/ty/fn.implements_trait.html
 704 [`snippet`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/source/fn.snippet.html
 705 [let-chains]: https://github.com/rust-lang/rust/pull/94927
 706 [from_expansion]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html#method.from_expansion
 707 [in_external_macro]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/lint/fn.in_external_macro.html
 708 [span]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html
 709 [applicability]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/enum.Applicability.html
 710 [rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/
 711 [nightly_docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
 712 [ast]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html
 713 [ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/sty/index.html
 714 [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/clippy