3 [![Build Status](https://travis-ci.org/rust-lang-nursery/rust-clippy.svg?branch=master)](https://travis-ci.org/rust-lang-nursery/rust-clippy)
4 [![Windows build status](https://ci.appveyor.com/api/projects/status/github/rust-lang-nursery/rust-clippy?svg=true)](https://ci.appveyor.com/project/rust-lang-nursery/rust-clippy)
5 [![Current Version](http://meritbadge.herokuapp.com/clippy)](https://crates.io/crates/clippy)
6 [![License: MPL-2.0](https://img.shields.io/crates/l/clippy.svg)](#license)
8 A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.
10 [There are 208 lints included in this crate!](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
12 More to come, please [file an issue](https://github.com/rust-lang-nursery/rust-clippy/issues) if you have ideas!
16 * [Usage instructions](#usage)
17 * [Configuration](#configuration)
22 Since this is a tool for helping the developer of a library or application
23 write better code, it is recommended not to include clippy as a hard dependency.
24 Options include using it as an optional dependency, as a cargo subcommand, or
25 as an included feature during build. All of these options are detailed below.
27 As a general rule clippy will only work with the *latest* Rust nightly for now.
29 ### As a cargo subcommand (`cargo clippy`)
31 One way to use clippy is by installing clippy through cargo as a cargo
35 cargo +nightly install clippy
38 (The `+nightly` is not necessary if your default `rustup` install is nightly)
40 Now you can run clippy by invoking `cargo +nightly clippy`.
42 In case you are not using rustup, you need to set the environment flag
43 `SYSROOT` during installation so clippy knows where to find `librustc` and
47 SYSROOT=/path/to/rustc/sysroot cargo install clippy
50 ### Optional dependency
52 In some cases you might want to include clippy in your project directly, as an
53 optional dependency. To do this, just modify `Cargo.toml`:
57 clippy = { version = "*", optional = true }
60 And, in your `main.rs` or `lib.rs`, add these lines:
63 #![cfg_attr(feature="clippy", feature(plugin))]
64 #![cfg_attr(feature="clippy", plugin(clippy))]
67 Then build by enabling the feature: `cargo +nightly build --features "clippy"`.
69 Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
70 `cargo rustc --features clippy -- -Z no-trans -Z extra-plugins=clippy`
71 (the `-Z no trans`, while not necessary, will stop the compilation process after
72 typechecking (and lints) have completed, which can significantly reduce the runtime).
74 Alternatively, to only run clippy when testing:
78 clippy = { version = "*" }
81 and add to `main.rs` or `lib.rs`:
84 #![cfg_attr(test, feature(plugin))]
85 #![cfg_attr(test, plugin(clippy))]
88 ### Running clippy from the command line without installing it
90 To have cargo compile your crate with clippy without clippy installation and without needing `#![plugin(clippy)]`
91 in your code, you can use:
94 cargo run --bin cargo-clippy --manifest-path=path_to_clippys_Cargo.toml
97 *[Note](https://github.com/rust-lang-nursery/rust-clippy/wiki#a-word-of-warning):*
98 Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
100 ### As a Compiler Plugin
102 *Note:* This is not a recommended installation method.
104 Since stable Rust is backwards compatible, you should be able to
105 compile your stable programs with nightly Rust with clippy plugged in to
108 Add in your `Cargo.toml`:
115 You then need to add `#![feature(plugin)]` and `#![plugin(clippy)]` to the top
116 of your crate entry point (`main.rs` or `lib.rs`).
129 Some(y) => println!("{:?}", y),
135 Produces this warning:
138 src/main.rs:8:5: 11:6 warning: you seem to be trying to use match for destructuring a single type. Consider using `if let`, #[warn(single_match)] on by default
139 src/main.rs:8 match x {
140 src/main.rs:9 Some(y) => println!("{:?}", y),
141 src/main.rs:10 _ => ()
143 src/main.rs:8:5: 11:6 help: Try
144 if let Some(y) = x { println!("{:?}", y) }
149 Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg.
152 blacklisted-names = ["toto", "tata", "titi"]
153 cyclomatic-complexity-threshold = 30
156 See the [list of lints](https://rust-lang-nursery.github.io/rust-clippy/master/index.html) for more information about which lints can be configured and the
157 meaning of the variables.
159 You can also specify the path to the configuration file with:
162 #![plugin(clippy(conf_file="path/to/clippy's/configuration"))]
165 To deactivate the “for further information visit *lint-link*” message you can
166 define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
168 ### Allowing/denying lints
170 You can add options to `allow`/`warn`/`deny`:
172 * the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy)]`)
174 * all lints using both the `clippy` and `clippy_pedantic` lint groups (`#![deny(clippy)]`,
175 `#![deny(clippy_pedantic)]`). Note that `clippy_pedantic` contains some very aggressive
176 lints prone to false positives.
178 * only some lints (`#![deny(single_match, box_vec)]`, etc)
180 * `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc
182 Note: `deny` produces errors instead of warnings.
184 For convenience, `cargo clippy` automatically defines a `cargo-clippy`
185 features. This lets you set lints level and compile with or without clippy
189 #[cfg_attr(feature = "cargo-clippy", allow(needless_lifetimes))]
194 Sometimes, rustc moves forward without clippy catching up. Therefore updating
195 rustc may leave clippy a non-functional state until we fix the resulting
198 You can use the [rust-update](rust-update) script to update rustc only if
199 clippy would also update correctly.
203 Licensed under [MPL](https://www.mozilla.org/MPL/2.0/).
204 If you're having issues with the license, let me know and I'll try to change it to something more permissive.