]>
Commit | Line | Data |
---|---|---|
923072b8 FG |
1 | # Usage |
2 | ||
3 | This chapter describes how to use Clippy to get the most out of it. Clippy can | |
4 | be used as a `cargo` subcommand or, like `rustc`, directly with the | |
5 | `clippy-driver` binary. | |
6 | ||
7 | > _Note:_ This chapter assumes that you have Clippy installed already. If you're | |
8 | > not sure, take a look at the [Installation] chapter. | |
9 | ||
10 | ## Cargo subcommand | |
11 | ||
12 | The easiest and most common way to run Clippy is through `cargo`. To do that, | |
13 | just run | |
14 | ||
15 | ```bash | |
16 | cargo clippy | |
17 | ``` | |
18 | ||
19 | ### Lint configuration | |
20 | ||
21 | The above command will run the default set of lints, which are included in the | |
353b0b11 | 22 | lint group `clippy::all`. You might want to use even more lints, or you may not |
923072b8 FG |
23 | agree with every Clippy lint, and for that there are ways to configure lint |
24 | levels. | |
25 | ||
26 | > _Note:_ Clippy is meant to be used with a generous sprinkling of | |
27 | > `#[allow(..)]`s through your code. So if you disagree with a lint, don't feel | |
28 | > bad disabling them for parts of your code or the whole project. | |
29 | ||
30 | #### Command line | |
31 | ||
32 | You can configure lint levels on the command line by adding | |
33 | `-A/W/D clippy::lint_name` like this: | |
34 | ||
35 | ```bash | |
36 | cargo clippy -- -Aclippy::style -Wclippy::double_neg -Dclippy::perf | |
37 | ``` | |
38 | ||
39 | For [CI] all warnings can be elevated to errors which will inturn fail | |
40 | the build and cause Clippy to exit with a code other than `0`. | |
41 | ||
42 | ``` | |
43 | cargo clippy -- -Dwarnings | |
44 | ``` | |
45 | ||
46 | > _Note:_ Adding `-D warnings` will cause your build to fail if **any** warnings | |
47 | > are found in your code. That includes warnings found by rustc (e.g. | |
48 | > `dead_code`, etc.). | |
49 | ||
50 | For more information on configuring lint levels, see the [rustc documentation]. | |
51 | ||
52 | [rustc documentation]: https://doc.rust-lang.org/rustc/lints/levels.html#configuring-warning-levels | |
53 | ||
54 | #### Even more lints | |
55 | ||
56 | Clippy has lint groups which are allow-by-default. This means, that you will | |
57 | have to enable the lints in those groups manually. | |
58 | ||
064997fb | 59 | For a full list of all lints with their description and examples, please refer |
923072b8 FG |
60 | to [Clippy's lint list]. The two most important allow-by-default groups are |
61 | described below: | |
62 | ||
63 | [Clippy's lint list]: https://rust-lang.github.io/rust-clippy/master/index.html | |
64 | ||
65 | ##### `clippy::pedantic` | |
66 | ||
67 | The first group is the `pedantic` group. This group contains really opinionated | |
68 | lints, that may have some intentional false positives in order to prevent false | |
69 | negatives. So while this group is ready to be used in production, you can expect | |
70 | to sprinkle multiple `#[allow(..)]`s in your code. If you find any false | |
71 | positives, you're still welcome to report them to us for future improvements. | |
72 | ||
73 | > FYI: Clippy uses the whole group to lint itself. | |
74 | ||
75 | ##### `clippy::restriction` | |
76 | ||
77 | The second group is the `restriction` group. This group contains lints that | |
78 | "restrict" the language in some way. For example the `clippy::unwrap` lint from | |
79 | this group won't allow you to use `.unwrap()` in your code. You may want to look | |
80 | through the lints in this group and enable the ones that fit your need. | |
81 | ||
82 | > _Note:_ You shouldn't enable the whole lint group, but cherry-pick lints from | |
83 | > this group. Some lints in this group will even contradict other Clippy lints! | |
84 | ||
85 | #### Too many lints | |
86 | ||
87 | The most opinionated warn-by-default group of Clippy is the `clippy::style` | |
88 | group. Some people prefer to disable this group completely and then cherry-pick | |
89 | some lints they like from this group. The same is of course possible with every | |
90 | other of Clippy's lint groups. | |
91 | ||
92 | > _Note:_ We try to keep the warn-by-default groups free from false positives | |
93 | > (FP). If you find that a lint wrongly triggers, please report it in an issue | |
94 | > (if there isn't an issue for that FP already) | |
95 | ||
96 | #### Source Code | |
97 | ||
98 | You can configure lint levels in source code the same way you can configure | |
99 | `rustc` lints: | |
100 | ||
353b0b11 | 101 | ```rust,ignore |
923072b8 FG |
102 | #![allow(clippy::style)] |
103 | ||
104 | #[warn(clippy::double_neg)] | |
105 | fn main() { | |
106 | let x = 1; | |
107 | let y = --x; | |
108 | // ^^ warning: double negation | |
109 | } | |
110 | ``` | |
111 | ||
112 | ### Automatically applying Clippy suggestions | |
113 | ||
114 | Clippy can automatically apply some lint suggestions, just like the compiler. | |
115 | ||
116 | ```terminal | |
117 | cargo clippy --fix | |
118 | ``` | |
119 | ||
120 | ### Workspaces | |
121 | ||
122 | All the usual workspace options should work with Clippy. For example the | |
123 | following command will run Clippy on the `example` crate in your workspace: | |
124 | ||
125 | ```terminal | |
126 | cargo clippy -p example | |
127 | ``` | |
128 | ||
129 | As with `cargo check`, this includes dependencies that are members of the | |
130 | workspace, like path dependencies. If you want to run Clippy **only** on the | |
131 | given crate, use the `--no-deps` option like this: | |
132 | ||
133 | ```terminal | |
134 | cargo clippy -p example -- --no-deps | |
135 | ``` | |
136 | ||
137 | ## Using Clippy without `cargo`: `clippy-driver` | |
138 | ||
139 | Clippy can also be used in projects that do not use cargo. To do so, run | |
140 | `clippy-driver` with the same arguments you use for `rustc`. For example: | |
141 | ||
142 | ```terminal | |
143 | clippy-driver --edition 2018 -Cpanic=abort foo.rs | |
144 | ``` | |
145 | ||
146 | > _Note:_ `clippy-driver` is designed for running Clippy and should not be used | |
147 | > as a general replacement for `rustc`. `clippy-driver` may produce artifacts | |
148 | > that are not optimized as expected, for example. | |
149 | ||
150 | [Installation]: installation.md | |
064997fb | 151 | [CI]: continuous_integration/index.md |