[](https://travis-ci.org/rust-lang-nursery/rust-clippy)
[](https://ci.appveyor.com/project/rust-lang-nursery/rust-clippy)
-[](http://clippy.bashy.io/github/rust-lang-nursery/rust-clippy/master/log)
[](https://crates.io/crates/clippy)
-[](#License)
+[](#license)
-A collection of lints to catch common mistakes and improve your Rust code.
+A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.
+
+[There are 249 lints included in this crate!](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
+
+We have a bunch of lint categories to allow you to choose how much clippy is supposed to ~~annoy~~ help you:
+
+* `clippy` (everything that has no false positives)
+* `clippy_pedantic` (everything)
+* `clippy_style` (code that should be written in a more idiomatic way)
+* `clippy_complexity` (code that does something simple but in a complex way)
+* `clippy_perf` (code that can be written in a faster way)
+* **`clippy_correctness`** (code that is just outright wrong or very very useless)
+
+More to come, please [file an issue](https://github.com/rust-lang-nursery/rust-clippy/issues) if you have ideas!
Table of contents:
-* [Lint list](#lints)
* [Usage instructions](#usage)
* [Configuration](#configuration)
* [License](#license)
As a general rule clippy will only work with the *latest* Rust nightly for now.
-### Optional dependency
+To install Rust nightly, the recommended way is to use [rustup](https://rustup.rs/):
+
+```terminal
+rustup install nightly
+```
+
+### As a cargo subcommand (`cargo clippy`)
+
+One way to use clippy is by installing clippy through cargo as a cargo
+subcommand.
+
+```terminal
+cargo +nightly install clippy
+```
+
+(The `+nightly` is not necessary if your default `rustup` install is nightly)
+
+Now you can run clippy by invoking `cargo +nightly clippy`.
+
+To update the subcommand together with the latest nightly use the [rust-update](rust-update) script or run:
+
+```terminal
+rustup update nightly
+cargo +nightly install --force clippy
+```
+
+In case you are not using rustup, you need to set the environment flag
+`SYSROOT` during installation so clippy knows where to find `librustc` and
+similar crates.
+
+```terminal
+SYSROOT=/path/to/rustc/sysroot cargo install clippy
+```
-If you want to make clippy an optional dependency, you can do the following:
+### Optional dependency
-In your `Cargo.toml`:
+In some cases you might want to include clippy in your project directly, as an
+optional dependency. To do this, just modify `Cargo.toml`:
```toml
[dependencies]
-clippy = {version = "*", optional = true}
-
-[features]
-default = []
+clippy = { version = "*", optional = true }
```
-And, in your `main.rs` or `lib.rs`:
+And, in your `main.rs` or `lib.rs`, add these lines:
```rust
#![cfg_attr(feature="clippy", feature(plugin))]
-
#![cfg_attr(feature="clippy", plugin(clippy))]
```
-Then build by enabling the feature: `cargo build --features "clippy"`
+Then build by enabling the feature: `cargo +nightly build --features "clippy"`.
Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
`cargo rustc --features clippy -- -Z no-trans -Z extra-plugins=clippy`
(the `-Z no trans`, while not necessary, will stop the compilation process after
typechecking (and lints) have completed, which can significantly reduce the runtime).
-### As a cargo subcommand (`cargo clippy`)
+Alternatively, to only run clippy when testing:
-An alternate way to use clippy is by installing clippy through cargo as a cargo
-subcommand.
-
-```terminal
-cargo install clippy
+```toml
+[dev-dependencies]
+clippy = { version = "*" }
```
-Now you can run clippy by invoking `cargo clippy`, or
-`rustup run nightly cargo clippy` directly from a directory that is usually
-compiled with stable.
+and add to `main.rs` or `lib.rs`:
-In case you are not using rustup, you need to set the environment flag
-`SYSROOT` during installation so clippy knows where to find `librustc` and
-similar crates.
-
-```terminal
-SYSROOT=/path/to/rustc/sysroot cargo install clippy
+```
+#![cfg_attr(test, feature(plugin))]
+#![cfg_attr(test, plugin(clippy))]
```
-### Running clippy from the command line without installing
+### Running clippy from the command line without installing it
-To have cargo compile your crate with clippy without needing `#![plugin(clippy)]`
+To have cargo compile your crate with clippy without clippy installation and without needing `#![plugin(clippy)]`
in your code, you can use:
```terminal
-cargo rustc -- -L /path/to/clippy_so/dir/ -Z extra-plugins=clippy
+cargo run --bin cargo-clippy --manifest-path=path_to_clippys_Cargo.toml
```
*[Note](https://github.com/rust-lang-nursery/rust-clippy/wiki#a-word-of-warning):*
## Configuration
-Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg.
+Some lints can be configured in a TOML file named with `clippy.toml` or `.clippy.toml`. It contains basic `variable = value` mapping eg.
```toml
blacklisted-names = ["toto", "tata", "titi"]
cyclomatic-complexity-threshold = 30
```
-See the wiki for more information about which lints can be configured and the
+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
meaning of the variables.
You can also specify the path to the configuration file with:
#![plugin(clippy(conf_file="path/to/clippy's/configuration"))]
```
-To deactivate the “for further information visit *wiki-link*” message you can
+To deactivate the “for further information visit *lint-link*” message you can
define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
### Allowing/denying lints
Note: `deny` produces errors instead of warnings.
For convenience, `cargo clippy` automatically defines a `cargo-clippy`
-features. This lets you set lints level and compile with or without clippy
+feature. This lets you set lint levels and compile with or without clippy
transparently:
```rust
#[cfg_attr(feature = "cargo-clippy", allow(needless_lifetimes))]
```
-## Lints
+## Updating rustc
-There are 209 lints included in this crate:
-https://rust-lang-nursery.github.io/rust-clippy/master/index.html
+Sometimes, rustc moves forward without clippy catching up. Therefore updating
+rustc may leave clippy a non-functional state until we fix the resulting
+breakage.
-More to come, please [file an issue](https://github.com/rust-lang-nursery/rust-clippy/issues) if you have ideas!
+You can use the [rust-update](rust-update) script to update rustc only if
+clippy would also update correctly.
## License
projects / rust.git / blobdiff