]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
1 | # Clippy |
2 | ||
3 | [![Clippy Test](https://github.com/rust-lang/rust-clippy/workflows/Clippy%20Test/badge.svg?branch=auto&event=push)](https://github.com/rust-lang/rust-clippy/actions?query=workflow%3A%22Clippy+Test%22+event%3Apush+branch%3Aauto) | |
4 | [![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/clippy.svg)](#license) | |
5 | ||
6 | A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code. | |
7 | ||
cdc7bbd5 | 8 | [There are over 450 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html) |
f20569fa XL |
9 | |
10 | Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html). | |
11 | You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category. | |
12 | ||
136023e0 XL |
13 | | Category | Description | Default level | |
14 | | --------------------- | ----------------------------------------------------------------------------------- | ------------- | | |
15 | | `clippy::all` | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** | | |
16 | | `clippy::correctness` | code that is outright wrong or useless | **deny** | | |
17 | | `clippy::suspicious` | code that is most likely wrong or useless | **warn** | | |
18 | | `clippy::style` | code that should be written in a more idiomatic way | **warn** | | |
19 | | `clippy::complexity` | code that does something simple but in a complex way | **warn** | | |
20 | | `clippy::perf` | code that can be written to run faster | **warn** | | |
21 | | `clippy::pedantic` | lints which are rather strict or might have false positives | allow | | |
22 | | `clippy::nursery` | new lints that are still under development | allow | | |
23 | | `clippy::cargo` | lints for the cargo manifest | allow | | |
f20569fa XL |
24 | |
25 | More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas! | |
26 | ||
27 | The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also contains "restriction lints", which are | |
28 | for things which are usually not considered "bad", but may be useful to turn on in specific cases. These should be used | |
29 | very selectively, if at all. | |
30 | ||
31 | Table of contents: | |
32 | ||
33 | * [Usage instructions](#usage) | |
34 | * [Configuration](#configuration) | |
35 | * [Contributing](#contributing) | |
36 | * [License](#license) | |
37 | ||
38 | ## Usage | |
39 | ||
40 | Below are instructions on how to use Clippy as a subcommand, compiled from source | |
41 | or in Travis CI. | |
42 | ||
43 | ### As a cargo subcommand (`cargo clippy`) | |
44 | ||
45 | One way to use Clippy is by installing Clippy through rustup as a cargo | |
46 | subcommand. | |
47 | ||
48 | #### Step 1: Install rustup | |
49 | ||
50 | You can install [rustup](https://rustup.rs/) on supported platforms. This will help | |
51 | us install Clippy and its dependencies. | |
52 | ||
53 | If you already have rustup installed, update to ensure you have the latest | |
54 | rustup and compiler: | |
55 | ||
56 | ```terminal | |
57 | rustup update | |
58 | ``` | |
59 | ||
60 | #### Step 2: Install Clippy | |
61 | ||
62 | Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command: | |
63 | ||
64 | ```terminal | |
65 | rustup component add clippy | |
66 | ``` | |
67 | If it says that it can't find the `clippy` component, please run `rustup self update`. | |
68 | ||
69 | #### Step 3: Run Clippy | |
70 | ||
71 | Now you can run Clippy by invoking the following command: | |
72 | ||
73 | ```terminal | |
74 | cargo clippy | |
75 | ``` | |
76 | ||
77 | #### Automatically applying Clippy suggestions | |
78 | ||
136023e0 | 79 | Clippy can automatically apply some lint suggestions, just like the compiler. |
f20569fa XL |
80 | |
81 | ```terminal | |
136023e0 | 82 | cargo clippy --fix |
f20569fa XL |
83 | ``` |
84 | ||
85 | #### Workspaces | |
86 | ||
87 | All the usual workspace options should work with Clippy. For example the following command | |
88 | will run Clippy on the `example` crate: | |
89 | ||
90 | ```terminal | |
91 | cargo clippy -p example | |
92 | ``` | |
93 | ||
94 | As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies. | |
95 | If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this: | |
96 | ||
97 | ```terminal | |
136023e0 | 98 | cargo clippy -p example -- --no-deps |
f20569fa XL |
99 | ``` |
100 | ||
101 | ### As a rustc replacement (`clippy-driver`) | |
102 | ||
103 | Clippy can also be used in projects that do not use cargo. To do so, you will need to replace | |
104 | your `rustc` compilation commands with `clippy-driver`. For example, if your project runs: | |
105 | ||
106 | ```terminal | |
107 | rustc --edition 2018 -Cpanic=abort foo.rs | |
108 | ``` | |
109 | ||
110 | Then, to enable Clippy, you will need to call: | |
111 | ||
112 | ```terminal | |
113 | clippy-driver --edition 2018 -Cpanic=abort foo.rs | |
114 | ``` | |
115 | ||
116 | Note that `rustc` will still run, i.e. it will still emit the output files it normally does. | |
117 | ||
118 | ### Travis CI | |
119 | ||
120 | You can add Clippy to Travis CI in the same way you use it locally: | |
121 | ||
122 | ```yml | |
123 | language: rust | |
124 | rust: | |
125 | - stable | |
126 | - beta | |
127 | before_script: | |
128 | - rustup component add clippy | |
129 | script: | |
130 | - cargo clippy | |
131 | # if you want the build job to fail when encountering warnings, use | |
132 | - cargo clippy -- -D warnings | |
133 | # in order to also check tests and non-default crate features, use | |
134 | - cargo clippy --all-targets --all-features -- -D warnings | |
135 | - cargo test | |
136 | # etc. | |
137 | ``` | |
138 | ||
139 | Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code. | |
140 | That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause | |
141 | an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command | |
142 | line. (You can swap `clippy::all` with the specific lint category you are targeting.) | |
143 | ||
144 | ## Configuration | |
145 | ||
146 | Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable = | |
147 | value` mapping eg. | |
148 | ||
149 | ```toml | |
17df50a5 | 150 | avoid-breaking-exported-api = false |
f20569fa XL |
151 | blacklisted-names = ["toto", "tata", "titi"] |
152 | cognitive-complexity-threshold = 30 | |
153 | ``` | |
154 | ||
155 | See the [list of lints](https://rust-lang.github.io/rust-clippy/master/index.html) for more information about which | |
156 | lints can be configured and the meaning of the variables. | |
157 | ||
158 | To deactivate the “for further information visit *lint-link*” message you can | |
159 | define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable. | |
160 | ||
161 | ### Allowing/denying lints | |
162 | ||
163 | You can add options to your code to `allow`/`warn`/`deny` Clippy lints: | |
164 | ||
165 | * the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`) | |
166 | ||
167 | * all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`, | |
168 | `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive | |
169 | lints prone to false positives. | |
170 | ||
171 | * only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.) | |
172 | ||
173 | * `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc. | |
174 | ||
175 | Note: `allow` means to suppress the lint for your code. With `warn` the lint | |
176 | will only emit a warning, while with `deny` the lint will emit an error, when | |
177 | triggering for your code. An error causes clippy to exit with an error code, so | |
178 | is useful in scripts like CI/CD. | |
179 | ||
180 | If you do not want to include your lint levels in your code, you can globally | |
181 | enable/disable lints by passing extra flags to Clippy during the run: | |
182 | ||
183 | To allow `lint_name`, run | |
184 | ||
185 | ```terminal | |
186 | cargo clippy -- -A clippy::lint_name | |
187 | ``` | |
188 | ||
189 | And to warn on `lint_name`, run | |
190 | ||
191 | ```terminal | |
192 | cargo clippy -- -W clippy::lint_name | |
193 | ``` | |
194 | ||
195 | This also works with lint groups. For example you | |
196 | can run Clippy with warnings for all lints enabled: | |
197 | ```terminal | |
198 | cargo clippy -- -W clippy::pedantic | |
199 | ``` | |
200 | ||
201 | If you care only about a single lint, you can allow all others and then explicitly warn on | |
202 | the lint(s) you are interested in: | |
203 | ```terminal | |
204 | cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::... | |
205 | ``` | |
206 | ||
207 | ### Specifying the minimum supported Rust version | |
208 | ||
209 | Projects that intend to support old versions of Rust can disable lints pertaining to newer features by | |
210 | specifying the minimum supported Rust version (MSRV) in the clippy configuration file. | |
211 | ||
212 | ```toml | |
213 | msrv = "1.30.0" | |
214 | ``` | |
215 | ||
216 | The MSRV can also be specified as an inner attribute, like below. | |
217 | ||
218 | ```rust | |
219 | #![feature(custom_inner_attributes)] | |
220 | #![clippy::msrv = "1.30.0"] | |
221 | ||
222 | fn main() { | |
223 | ... | |
224 | } | |
225 | ``` | |
226 | ||
227 | You can also omit the patch version when specifying the MSRV, so `msrv = 1.30` | |
228 | is equivalent to `msrv = 1.30.0`. | |
229 | ||
230 | Note: `custom_inner_attributes` is an unstable feature so it has to be enabled explicitly. | |
231 | ||
232 | Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv) | |
233 | ||
234 | ## Contributing | |
235 | ||
236 | If you want to contribute to Clippy, you can find more information in [CONTRIBUTING.md](https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md). | |
237 | ||
238 | ## License | |
239 | ||
17df50a5 | 240 | Copyright 2014-2021 The Rust Project Developers |
f20569fa XL |
241 | |
242 | Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
243 | [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license | |
244 | <LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your | |
245 | option. Files in the project may not be | |
246 | copied, modified, or distributed except according to those terms. |