2016-05-06 16:07:47 +02:00
# rust-clippy
2017-08-06 13:10:21 +02:00
[![Build Status ](https://travis-ci.org/rust-lang-nursery/rust-clippy.svg?branch=master )](https://travis-ci.org/rust-lang-nursery/rust-clippy)
[![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)
2016-02-13 13:13:28 +01:00
[![Current Version ](http://meritbadge.herokuapp.com/clippy )](https://crates.io/crates/clippy)
2017-11-22 21:26:11 +01:00
[![License: MPL-2.0 ](https://img.shields.io/crates/l/clippy.svg )](#license)
2014-11-19 08:50:46 +01:00
2017-10-14 21:47:38 +02:00
A collection of lints to catch common mistakes and improve your [Rust ](https://github.com/rust-lang/rust ) code.
2014-11-19 20:19:03 +01:00
2017-10-20 06:42:04 +02:00
[There are 208 lints included in this crate! ](https://rust-lang-nursery.github.io/rust-clippy/master/index.html )
2017-09-01 20:29:36 +02:00
More to come, please [file an issue ](https://github.com/rust-lang-nursery/rust-clippy/issues ) if you have ideas!
2016-02-22 15:50:40 +01:00
Table of contents:
2016-03-10 21:42:24 +01:00
2016-05-06 16:07:47 +02:00
* [Usage instructions ](#usage )
* [Configuration ](#configuration )
* [License ](#license )
2016-09-15 17:19:30 +02:00
## Usage
2016-11-19 04:46:12 +01:00
Since this is a tool for helping the developer of a library or application
2016-11-20 04:16:36 +01:00
write better code, it is recommended not to include clippy as a hard dependency.
Options include using it as an optional dependency, as a cargo subcommand, or
as an included feature during build. All of these options are detailed below.
2016-11-19 04:46:12 +01:00
2016-09-15 17:19:30 +02:00
As a general rule clippy will only work with the *latest* Rust nightly for now.
2016-11-19 04:46:12 +01:00
### Optional dependency
2016-09-15 17:19:30 +02:00
2016-11-19 04:46:12 +01:00
If you want to make clippy an optional dependency, you can do the following:
2016-09-15 17:19:30 +02:00
2016-11-19 04:46:12 +01:00
In your `Cargo.toml` :
2016-09-15 17:19:30 +02:00
```toml
[dependencies]
2016-11-19 04:46:12 +01:00
clippy = {version = "*", optional = true}
2016-09-15 17:19:30 +02:00
2016-11-19 04:46:12 +01:00
[features]
default = []
```
2016-09-15 17:19:30 +02:00
2016-11-19 04:46:12 +01:00
And, in your `main.rs` or `lib.rs` :
2016-09-15 17:19:30 +02:00
```rust
2016-11-19 04:46:12 +01:00
#![cfg_attr(feature="clippy", feature(plugin))]
2016-09-15 17:19:30 +02:00
2016-11-19 04:46:12 +01:00
#![cfg_attr(feature="clippy", plugin(clippy))]
2016-09-15 17:19:30 +02:00
```
2016-11-19 04:46:12 +01:00
Then build by enabling the feature: `cargo build --features "clippy"`
2016-09-15 17:19:30 +02:00
2016-11-19 04:46:12 +01:00
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`
2017-03-17 08:30:29 +01:00
(the `-Z no trans` , while not necessary, will stop the compilation process after
2016-11-19 04:46:12 +01:00
typechecking (and lints) have completed, which can significantly reduce the runtime).
2016-09-15 17:19:30 +02:00
### As a cargo subcommand (`cargo clippy`)
An alternate way to use clippy is by installing clippy through cargo as a cargo
subcommand.
```terminal
cargo install clippy
```
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.
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
```
### Running clippy from the command line without installing
To have cargo compile your crate with clippy without needing `#![plugin(clippy)]`
in your code, you can use:
```terminal
2017-04-26 12:12:56 +02:00
cargo rustc -- -L /path/to/clippy_so/dir/ -Z extra-plugins=clippy
2016-09-15 17:19:30 +02:00
```
2017-08-06 13:10:21 +02:00
*[Note](https://github.com/rust-lang-nursery/rust-clippy/wiki#a-word-of-warning):*
2016-09-15 17:19:30 +02:00
Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
### As a Compiler Plugin
2016-11-20 04:16:36 +01:00
*Note:* This is not a recommended installation method.
2016-09-15 17:19:30 +02:00
Since stable Rust is backwards compatible, you should be able to
compile your stable programs with nightly Rust with clippy plugged in to
circumvent this.
Add in your `Cargo.toml` :
```toml
[dependencies]
clippy = "*"
```
You then need to add `#![feature(plugin)]` and `#![plugin(clippy)]` to the top
of your crate entry point (`main.rs` or `lib.rs` ).
Sample `main.rs` :
```rust
#![feature(plugin)]
#![plugin(clippy)]
fn main(){
let x = Some(1u8);
match x {
Some(y) => println!("{:?}", y),
_ => ()
}
}
```
Produces this warning:
```terminal
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
src/main.rs:8 match x {
src/main.rs:9 Some(y) => println!("{:?}", y),
src/main.rs:10 _ => ()
src/main.rs:11 }
src/main.rs:8:5: 11:6 help: Try
if let Some(y) = x { println!("{:?}", y) }
```
## Configuration
Some lints can be configured in a `clippy.toml` file. 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
meaning of the variables.
You can also specify the path to the configuration file with:
```rust
#![plugin(clippy(conf_file="path/to/clippy's/configuration"))]
```
To deactivate the “for further information visit *wiki-link* ” message you can
2017-09-01 10:29:49 +02:00
define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
2016-09-15 17:19:30 +02:00
### Allowing/denying lints
You can add options to `allow` /`warn`/`deny`:
* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy)]`)
* all lints using both the `clippy` and `clippy_pedantic` lint groups (`#![deny(clippy)]`,
`#![deny(clippy_pedantic)]` ). Note that `clippy_pedantic` contains some very aggressive
lints prone to false positives.
* only some lints (`#![deny(single_match, box_vec)]`, etc)
* `allow` /`warn`/`deny` can be limited to a single function or module using `#[allow(...)]` , etc
Note: `deny` produces errors instead of warnings.
2016-10-24 16:04:00 +02:00
For convenience, `cargo clippy` automatically defines a `cargo-clippy`
features. This lets you set lints level and compile with or without clippy
transparently:
```rust
#[cfg_attr(feature = "cargo-clippy", allow(needless_lifetimes))]
```
2017-10-11 20:50:58 +02:00
## Updating rustc
Sometimes, rustc moves forward without clippy catching up. Therefore updating
rustc may leave clippy a non-functional state until we fix the resulting
breakage.
You can use the [rust-update ](rust-update ) script to update rustc only if
clippy would also update correctly.
2016-05-06 16:07:47 +02:00
## License
Licensed under [MPL ](https://www.mozilla.org/MPL/2.0/ ).
If you're having issues with the license, let me know and I'll try to change it to something more permissive.