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.
7 To get started, we will create a lint that detects functions called `foo`,
8 because that's clearly a non-descriptive name.
10 - [Adding a new lint](#adding-a-new-lint)
12 - [Getting Started](#getting-started)
14 - [Cargo lints](#cargo-lints)
15 - [Rustfix tests](#rustfix-tests)
16 - [Edition 2018 tests](#edition-2018-tests)
17 - [Testing manually](#testing-manually)
18 - [Lint declaration](#lint-declaration)
19 - [Lint registration](#lint-registration)
20 - [Lint passes](#lint-passes)
21 - [Emitting a lint](#emitting-a-lint)
22 - [Adding the lint logic](#adding-the-lint-logic)
23 - [Specifying the lint's minimum supported Rust version (MSRV)](#specifying-the-lints-minimum-supported-rust-version-msrv)
24 - [Author lint](#author-lint)
25 - [Print HIR lint](#print-hir-lint)
26 - [Documentation](#documentation)
27 - [Running rustfmt](#running-rustfmt)
28 - [Debugging](#debugging)
29 - [PR Checklist](#pr-checklist)
30 - [Adding configuration to a lint](#adding-configuration-to-a-lint)
31 - [Cheat Sheet](#cheat-sheet)
35 See the [Basics](basics.md#get-the-code) documentation.
39 There is a bit of boilerplate code that needs to be set up when creating a new
40 lint. Fortunately, you can use the clippy dev tools to handle this for you. We
41 are naming our new lint `foo_functions` (lints are generally written in snake
42 case), and we don't need type information so it will have an early pass type
43 (more on this later on). If you're not sure if the name you chose fits the lint,
44 take a look at our [lint naming guidelines][lint_naming]. To get started on this
45 lint you can run `cargo dev new_lint --name=foo_functions --pass=early
46 --category=pedantic` (category will default to nursery if not provided). This
47 command will create two files: `tests/ui/foo_functions.rs` and
48 `clippy_lints/src/foo_functions.rs`, as well as
49 [registering the lint](#lint-registration). For cargo lints, two project
50 hierarchies (fail/pass) will be created by default under `tests/ui-cargo`.
52 Next, we'll open up these files and add our lint!
56 Let's write some tests first that we can execute while we iterate on our lint.
58 Clippy uses UI tests for testing. UI tests check that the output of Clippy is
59 exactly as expected. Each test is just a plain Rust file that contains the code
60 we want to check. The output of Clippy is compared against a `.stderr` file.
61 Note that you don't have to create this file yourself, we'll get to
62 generating the `.stderr` files further down.
64 We start by opening the test file created at `tests/ui/foo_functions.rs`.
66 Update the file with some examples to get started:
69 #![warn(clippy::foo_functions)]
79 // Default trait methods
92 // We also don't want to lint method calls
99 Now we can run the test with `TESTNAME=foo_functions cargo uitest`,
100 currently this test is meaningless though.
102 While we are working on implementing our lint, we can keep running the UI
103 test. That allows us to check if the output is turning into what we want.
105 Once we are satisfied with the output, we need to run
106 `cargo dev bless` to update the `.stderr` file for our lint.
107 Please note that, we should run `TESTNAME=foo_functions cargo uitest`
108 every time before running `cargo dev bless`.
109 Running `TESTNAME=foo_functions cargo uitest` should pass then. When we commit
110 our lint, we need to commit the generated `.stderr` files, too. In general, you
111 should only commit files changed by `cargo dev bless` for the
112 specific lint you are creating/editing. Note that if the generated files are
113 empty, they should be removed.
115 Note that you can run multiple test files by specifying a comma separated list:
116 `TESTNAME=foo_functions,test2,test3`.
120 For cargo lints, the process of testing differs in that we are interested in
121 the `Cargo.toml` manifest file. We also need a minimal crate associated
124 If our new lint is named e.g. `foo_categories`, after running `cargo dev new_lint`
125 we will find by default two new crates, each with its manifest file:
127 * `tests/ui-cargo/foo_categories/fail/Cargo.toml`: this file should cause the new lint to raise an error.
128 * `tests/ui-cargo/foo_categories/pass/Cargo.toml`: this file should not trigger the lint.
130 If you need more cases, you can copy one of those crates (under `foo_categories`) and rename it.
132 The process of generating the `.stderr` file is the same, and prepending the `TESTNAME`
133 variable to `cargo uitest` works too.
137 If the lint you are working on is making use of structured suggestions, the
138 test file should include a `// run-rustfix` comment at the top. This will
139 additionally run [rustfix] for that test. Rustfix will apply the suggestions
140 from the lint to the code of the test file and compare that to the contents of
143 Use `cargo dev bless` to automatically generate the
144 `.fixed` file after running the tests.
146 [rustfix]: https://github.com/rust-lang/rustfix
148 ## Edition 2018 tests
150 Some features require the 2018 edition to work (e.g. `async_await`), but
151 compile-test tests run on the 2015 edition by default. To change this behavior
152 add `// edition:2018` at the top of the test file (note that it's space-sensitive).
156 Manually testing against an example file can be useful if you have added some
157 `println!`s and the test suite output becomes unreadable. To try Clippy with
158 your local modifications, run
161 cargo dev lint input.rs
164 from the working copy root. With tests in place, let's have a look at
165 implementing our lint now.
169 Let's start by opening the new file created in the `clippy_lints` crate
170 at `clippy_lints/src/foo_functions.rs`. That's the crate where all the
171 lint code is. This file has already imported some initial things we will need:
174 use rustc_lint::{EarlyLintPass, EarlyContext};
175 use rustc_session::{declare_lint_pass, declare_tool_lint};
176 use rustc_ast::ast::*;
179 The next step is to update the lint declaration. Lints are declared using the
180 [`declare_clippy_lint!`][declare_clippy_lint] macro, and we just need to update
181 the auto-generated lint declaration to have a real description, something like this:
184 declare_clippy_lint! {
187 /// ### Why is this bad?
193 #[clippy::version = "1.29.0"]
196 "function named `foo`, which is not a descriptive name"
200 * The section of lines prefixed with `///` constitutes the lint documentation
201 section. This is the default documentation style and will be displayed
202 [like this][example_lint_page]. To render and open this documentation locally
203 in a browser, run `cargo dev serve`.
204 * The `#[clippy::version]` attribute will be rendered as part of the lint documentation.
205 The value should be set to the current Rust version that the lint is developed in,
206 it can be retrieved by running `rustc -vV` in the rust-clippy directory. The version
207 is listed under *release*. (Use the version without the `-nightly`) suffix.
208 * `FOO_FUNCTIONS` is the name of our lint. Be sure to follow the
209 [lint naming guidelines][lint_naming] here when naming your lint.
210 In short, the name should state the thing that is being checked for and
211 read well when used with `allow`/`warn`/`deny`.
212 * `pedantic` sets the lint level to `Allow`.
213 The exact mapping can be found [here][category_level_mapping]
214 * The last part should be a text that explains what exactly is wrong with the
217 The rest of this file contains an empty implementation for our lint pass,
218 which in this case is `EarlyLintPass` and should look like this:
221 // clippy_lints/src/foo_functions.rs
223 // .. imports and lint declaration ..
225 declare_lint_pass!(FooFunctions => [FOO_FUNCTIONS]);
227 impl EarlyLintPass for FooFunctions {}
230 [declare_clippy_lint]: https://github.com/rust-lang/rust-clippy/blob/557f6848bd5b7183f55c1e1522a326e9e1df6030/clippy_lints/src/lib.rs#L60
231 [example_lint_page]: https://rust-lang.github.io/rust-clippy/master/index.html#redundant_closure
232 [lint_naming]: https://rust-lang.github.io/rfcs/0344-conventions-galore.html#lints
233 [category_level_mapping]: https://github.com/rust-lang/rust-clippy/blob/557f6848bd5b7183f55c1e1522a326e9e1df6030/clippy_lints/src/lib.rs#L110
237 When using `cargo dev new_lint`, the lint is automatically registered and
238 nothing more has to be done.
240 When declaring a new lint by hand and `cargo dev update_lints` is used, the lint
241 pass may have to be registered manually in the `register_plugins` function in
242 `clippy_lints/src/lib.rs`:
245 store.register_early_pass(|| Box::new(foo_functions::FooFunctions));
248 As one may expect, there is a corresponding `register_late_pass` method
249 available as well. Without a call to one of `register_early_pass` or
250 `register_late_pass`, the lint pass in question will not be run.
252 One reason that `cargo dev update_lints` does not automate this step is that
253 multiple lints can use the same lint pass, so registering the lint pass may
254 already be done when adding a new lint. Another reason that this step is not
255 automated is that the order that the passes are registered determines the order
256 the passes actually run, which in turn affects the order that any emitted lints
261 Writing a lint that only checks for the name of a function means that we only
262 have to deal with the AST and don't have to deal with the type system at all.
263 This is good, because it makes writing this particular lint less complicated.
265 We have to make this decision with every new Clippy lint. It boils down to using
266 either [`EarlyLintPass`][early_lint_pass] or [`LateLintPass`][late_lint_pass].
268 In short, the `LateLintPass` has access to type information while the
269 `EarlyLintPass` doesn't. If you don't need access to type information, use the
270 `EarlyLintPass`. The `EarlyLintPass` is also faster. However linting speed
271 hasn't really been a concern with Clippy so far.
273 Since we don't need type information for checking the function name, we used
274 `--pass=early` when running the new lint automation and all the imports were
277 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html
278 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html
282 With UI tests and the lint declaration in place, we can start working on the
283 implementation of the lint logic.
285 Let's start by implementing the `EarlyLintPass` for our `FooFunctions`:
288 impl EarlyLintPass for FooFunctions {
289 fn check_fn(&mut self, cx: &EarlyContext<'_>, fn_kind: FnKind<'_>, span: Span, _: NodeId) {
290 // TODO: Emit lint here
295 We implement the [`check_fn`][check_fn] method from the
296 [`EarlyLintPass`][early_lint_pass] trait. This gives us access to various
297 information about the function that is currently being checked. More on that in
298 the next section. Let's worry about the details later and emit our lint for
299 *every* function definition first.
301 Depending on how complex we want our lint message to be, we can choose from a
302 variety of lint emission functions. They can all be found in
303 [`clippy_utils/src/diagnostics.rs`][diagnostics].
305 `span_lint_and_help` seems most appropriate in this case. It allows us to
306 provide an extra help message and we can't really suggest a better name
307 automatically. This is how it looks:
310 impl EarlyLintPass for FooFunctions {
311 fn check_fn(&mut self, cx: &EarlyContext<'_>, fn_kind: FnKind<'_>, span: Span, _: NodeId) {
316 "function named `foo`",
318 "consider using a more meaningful name"
324 Running our UI test should now produce output that contains the lint message.
326 According to [the rustc-dev-guide], the text should be matter of fact and avoid
327 capitalization and periods, unless multiple sentences are needed.
328 When code or an identifier must appear in a message or label, it should be
329 surrounded with single grave accents \`.
331 [check_fn]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html#method.check_fn
332 [diagnostics]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_utils/src/diagnostics.rs
333 [the rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/diagnostics.html
335 ## Adding the lint logic
337 Writing the logic for your lint will most likely be different from our example,
338 so this section is kept rather short.
340 Using the [`check_fn`][check_fn] method gives us access to [`FnKind`][fn_kind]
341 that has the [`FnKind::Fn`] variant. It provides access to the name of the
342 function/method via an [`Ident`][ident].
344 With that we can expand our `check_fn` method to:
347 impl EarlyLintPass for FooFunctions {
348 fn check_fn(&mut self, cx: &EarlyContext<'_>, fn_kind: FnKind<'_>, span: Span, _: NodeId) {
349 if is_foo_fn(fn_kind) {
354 "function named `foo`",
356 "consider using a more meaningful name"
363 We separate the lint conditional from the lint emissions because it makes the
364 code a bit easier to read. In some cases this separation would also allow to
365 write some unit tests (as opposed to only UI tests) for the separate function.
367 In our example, `is_foo_fn` looks like:
370 // use statements, impl EarlyLintPass, check_fn, ..
372 fn is_foo_fn(fn_kind: FnKind<'_>) -> bool {
374 FnKind::Fn(_, ident, ..) => {
375 // check if `fn` name is `foo`
376 ident.name.as_str() == "foo"
379 FnKind::Closure(..) => false
384 Now we should also run the full test suite with `cargo test`. At this point
385 running `cargo test` should produce the expected output. Remember to run
386 `cargo dev bless` to update the `.stderr` file.
388 `cargo test` (as opposed to `cargo uitest`) will also ensure that our lint
389 implementation is not violating any Clippy lints itself.
391 That should be it for the lint implementation. Running `cargo test` should now
394 [fn_kind]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/visit/enum.FnKind.html
395 [`FnKind::Fn`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/visit/enum.FnKind.html#variant.Fn
396 [ident]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/symbol/struct.Ident.html
398 ## Specifying the lint's minimum supported Rust version (MSRV)
400 Sometimes a lint makes suggestions that require a certain version of Rust. For example, the `manual_strip` lint suggests
401 using `str::strip_prefix` and `str::strip_suffix` which is only available after Rust 1.45. In such cases, you need to
402 ensure that the MSRV configured for the project is >= the MSRV of the required Rust feature. If multiple features are
403 required, just use the one with a lower MSRV.
405 First, add an MSRV alias for the required feature in [`clippy_utils::msrvs`](/clippy_utils/src/msrvs.rs). This can be
406 accessed later as `msrvs::STR_STRIP_PREFIX`, for example.
411 1,45,0 { STR_STRIP_PREFIX }
415 In order to access the project-configured MSRV, you need to have an `msrv` field in the LintPass struct, and a
416 constructor to initialize the field. The `msrv` value is passed to the constructor in `clippy_lints/lib.rs`.
419 pub struct ManualStrip {
420 msrv: Option<RustcVersion>,
425 pub fn new(msrv: Option<RustcVersion>) -> Self {
431 The project's MSRV can then be matched against the feature MSRV in the LintPass
432 using the `meets_msrv` utility function.
435 if !meets_msrv(self.msrv, msrvs::STR_STRIP_PREFIX) {
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`.
446 impl<'tcx> LateLintPass<'tcx> for ManualStrip {
447 fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx Expr<'_>) {
450 extract_msrv_attr!(LateContext);
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.
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`:
463 /// Lint: LIST, OF, LINTS, <THE_NEWLY_ADDED_LINT>. The minimum rust version that the project supports
464 (msrv: Option<String> = None),
471 If you have trouble implementing your lint, there is also the internal `author`
472 lint to generate Clippy code that detects the offending pattern. It does not
473 work for all of the Rust syntax, but can give a good starting point.
475 The quickest way to use it, is the
476 [Rust playground: play.rust-lang.org][author_example].
477 Put the code you want to lint into the editor and add the `#[clippy::author]`
478 attribute above the item. Then run Clippy via `Tools -> Clippy` and you should
479 see the generated code in the output below.
481 [Here][author_example] is an example on the playground.
483 If the command was executed successfully, you can copy the code over to where
484 you are implementing your lint.
486 [author_example]: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2018&gist=9a12cb60e5c6ad4e3003ac6d5e63cf55
490 To implement a lint, it's helpful to first understand the internal representation
491 that rustc uses. Clippy has the `#[clippy::dump]` attribute that prints the
492 [_High-Level Intermediate Representation (HIR)_] of the item, statement, or
493 expression that the attribute is attached to. To attach the attribute to expressions
494 you often need to enable `#![feature(stmt_expr_attributes)]`.
496 [Here][print_hir_example] you can find an example, just select _Tools_ and run _Clippy_.
498 [_High-Level Intermediate Representation (HIR)_]: https://rustc-dev-guide.rust-lang.org/hir.html
499 [print_hir_example]: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=daf14db3a7f39ca467cd1b86c34b9afb
503 The final thing before submitting our PR is to add some documentation to our
506 Please document your lint with a doc comment akin to the following:
509 declare_clippy_lint! {
511 /// Checks for ... (describe what the lint matches).
513 /// ### Why is this bad?
514 /// Supply the reason for linting the code.
519 /// // A short example of code that triggers the lint
524 /// // A short example of improved code that doesn't trigger the lint
526 #[clippy::version = "1.29.0"]
529 "function named `foo`, which is not a descriptive name"
533 Once your lint is merged, this documentation will show up in the [lint
536 [lint_list]: https://rust-lang.github.io/rust-clippy/master/index.html
540 [Rustfmt] is a tool for formatting Rust code according to style guidelines.
541 Your code has to be formatted by `rustfmt` before a PR can be merged.
542 Clippy uses nightly `rustfmt` in the CI.
544 It can be installed via `rustup`:
547 rustup component add rustfmt --toolchain=nightly
550 Use `cargo dev fmt` to format the whole codebase. Make sure that `rustfmt` is
551 installed for the nightly toolchain.
553 [Rustfmt]: https://github.com/rust-lang/rustfmt
557 If you want to debug parts of your lint implementation, you can use the [`dbg!`]
558 macro anywhere in your code. Running the tests should then include the debug
559 output in the `stdout` part.
561 [`dbg!`]: https://doc.rust-lang.org/std/macro.dbg.html
565 Before submitting your PR make sure you followed all of the basic requirements:
567 <!-- Sync this with `.github/PULL_REQUEST_TEMPLATE` -->
569 - \[ ] Followed [lint naming conventions][lint_naming]
570 - \[ ] Added passing UI tests (including committed `.stderr` file)
571 - \[ ] `cargo test` passes locally
572 - \[ ] Executed `cargo dev update_lints`
573 - \[ ] Added lint documentation
574 - \[ ] Run `cargo dev fmt`
576 ## Adding configuration to a lint
578 Clippy supports the configuration of lints values using a `clippy.toml` file in the workspace
579 directory. Adding a configuration to a lint can be useful for thresholds or to constrain some
580 behavior that can be seen as a false positive for some users. Adding a configuration is done
581 in the following steps:
583 1. Adding a new configuration entry to [clippy_lints::utils::conf](/clippy_lints/src/utils/conf.rs)
588 /// <The configuration field doc comment>
589 (configuration_ident: Type = DefaultValue),
591 The doc comment is automatically added to the documentation of the listed lints. The default
592 value will be formatted using the `Debug` implementation of the type.
593 2. Adding the configuration value to the lint impl struct:
594 1. This first requires the definition of a lint impl struct. Lint impl structs are usually
595 generated with the `declare_lint_pass!` macro. This struct needs to be defined manually
596 to add some kind of metadata to it:
598 // Generated struct definition
599 declare_lint_pass!(StructName => [
603 // New manual definition struct
604 #[derive(Copy, Clone)]
605 pub struct StructName {}
607 impl_lint_pass!(StructName => [
612 2. Next add the configuration value and a corresponding creation method like this:
614 #[derive(Copy, Clone)]
615 pub struct StructName {
616 configuration_ident: Type,
622 pub fn new(configuration_ident: Type) -> Self {
629 3. Passing the configuration value to the lint impl struct:
631 First find the struct construction in the [clippy_lints lib file](/clippy_lints/src/lib.rs).
632 The configuration value is now cloned or copied into a local value that is then passed to the
633 impl struct like this:
635 // Default generated registration:
636 store.register_*_pass(|| box module::StructName);
638 // New registration with configuration value
639 let configuration_ident = conf.configuration_ident.clone();
640 store.register_*_pass(move || box module::StructName::new(configuration_ident));
643 Congratulations the work is almost done. The configuration value can now be accessed
644 in the linting code via `self.configuration_ident`.
647 1. The default configured value can be tested like any normal lint in [`tests/ui`](/tests/ui).
648 2. The configuration itself will be tested separately in [`tests/ui-toml`](/tests/ui-toml).
649 Simply add a new subfolder with a fitting name. This folder contains a `clippy.toml` file
650 with the configuration value and a rust file that should be linted by Clippy. The test can
651 otherwise be written as usual.
655 Here are some pointers to things you are likely going to need for every lint:
657 * [Clippy utils][utils] - Various helper functions. Maybe the function you need
658 is already in here ([`is_type_diagnostic_item`], [`implements_trait`], [`snippet`], etc)
659 * [Clippy diagnostics][diagnostics]
660 * [Let chains][let-chains]
661 * [`from_expansion`][from_expansion] and [`in_external_macro`][in_external_macro]
663 * [`Applicability`][applicability]
664 * [Common tools for writing lints](common_tools_writing_lints.md) helps with common operations
665 * [The rustc-dev-guide][rustc-dev-guide] explains a lot of internal compiler concepts
666 * [The nightly rustc docs][nightly_docs] which has been linked to throughout
669 For `EarlyLintPass` lints:
671 * [`EarlyLintPass`][early_lint_pass]
672 * [`rustc_ast::ast`][ast]
674 For `LateLintPass` lints:
676 * [`LateLintPass`][late_lint_pass]
679 While most of Clippy's lint utils are documented, most of rustc's internals lack
680 documentation currently. This is unfortunate, but in most cases you can probably
681 get away with copying things from existing similar lints. If you are stuck,
682 don't hesitate to ask on [Zulip] or in the issue/PR.
684 [utils]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/index.html
685 [`is_type_diagnostic_item`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/ty/fn.is_type_diagnostic_item.html
686 [`implements_trait`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/ty/fn.implements_trait.html
687 [`snippet`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/source/fn.snippet.html
688 [let-chains]: https://github.com/rust-lang/rust/pull/94927
689 [from_expansion]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html#method.from_expansion
690 [in_external_macro]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/lint/fn.in_external_macro.html
691 [span]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html
692 [applicability]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/enum.Applicability.html
693 [rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/
694 [nightly_docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
695 [ast]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html
696 [ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/sty/index.html
697 [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/clippy