README.md

   1 # rust-clippy
   2
   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)
   7
   8 A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.
   9
  10 [There are 208 lints included in this crate!](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
  11
  12 More to come, please [file an issue](https://github.com/rust-lang-nursery/rust-clippy/issues) if you have ideas!
  13
  14 Table of contents:
  15
  16 *   [Usage instructions](#usage)
  17 *   [Configuration](#configuration)
  18 *   [License](#license)
  19
  20 ## Usage
  21
  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.
  26
  27 As a general rule clippy will only work with the *latest* Rust nightly for now.
  28
  29 ### As a cargo subcommand (`cargo clippy`)
  30
  31 One way to use clippy is by installing clippy through cargo as a cargo
  32 subcommand.
  33
  34 ```terminal
  35 cargo +nightly install clippy
  36 ```
  37
  38 (The `+nightly` is not necessary if your default `rustup` install is nightly)
  39
  40 Now you can run clippy by invoking `cargo +nightly clippy`.
  41
  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
  44 similar crates.
  45
  46 ```terminal
  47 SYSROOT=/path/to/rustc/sysroot cargo install clippy
  48 ```
  49
  50 ### Optional dependency
  51
  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`:
  54
  55 ```toml
  56 [dependencies]
  57 clippy = { version = "*", optional = true }
  58 ```
  59
  60 And, in your `main.rs` or `lib.rs`, add these lines:
  61
  62 ```rust
  63 #![cfg_attr(feature="clippy", feature(plugin))]
  64 #![cfg_attr(feature="clippy", plugin(clippy))]
  65 ```
  66
  67 Then build by enabling the feature: `cargo +nightly build --features "clippy"`.
  68
  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).
  73
  74 Alternatively, to only run clippy when testing:
  75
  76 ```toml
  77 [dev-dependencies]
  78 clippy = { version = "*" }
  79 ```
  80
  81 and add to `main.rs` or  `lib.rs`:
  82
  83 ```
  84 #![cfg_attr(test, feature(plugin))]
  85 #![cfg_attr(test, plugin(clippy))]
  86 ```
  87
  88 ### Running clippy from the command line without installing it
  89
  90 To have cargo compile your crate with clippy without clippy installation and without needing `#![plugin(clippy)]`
  91 in your code, you can use:
  92
  93 ```terminal
  94 cargo run --bin cargo-clippy --manifest-path=path_to_clippys_Cargo.toml
  95 ```
  96
  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!
  99
 100 ### As a Compiler Plugin
 101
 102 *Note:* This is not a recommended installation method.
 103
 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
 106 circumvent this.
 107
 108 Add in your `Cargo.toml`:
 109
 110 ```toml
 111 [dependencies]
 112 clippy = "*"
 113 ```
 114
 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`).
 117
 118 Sample `main.rs`:
 119
 120 ```rust
 121 #![feature(plugin)]
 122
 123 #![plugin(clippy)]
 124
 125
 126 fn main(){
 127     let x = Some(1u8);
 128     match x {
 129         Some(y) => println!("{:?}", y),
 130         _ => ()
 131     }
 132 }
 133 ```
 134
 135 Produces this warning:
 136
 137 ```terminal
 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         _ => ()
 142 src/main.rs:11     }
 143 src/main.rs:8:5: 11:6 help: Try
 144 if let Some(y) = x { println!("{:?}", y) }
 145 ```
 146
 147 ## Configuration
 148
 149 Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg.
 150
 151 ```toml
 152 blacklisted-names = ["toto", "tata", "titi"]
 153 cyclomatic-complexity-threshold = 30
 154 ```
 155
 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.
 158
 159 You can also specify the path to the configuration file with:
 160
 161 ```rust
 162 #![plugin(clippy(conf_file="path/to/clippy's/configuration"))]
 163 ```
 164
 165 To deactivate the “for further information visit *lint-link*” message you can
 166 define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
 167
 168 ### Allowing/denying lints
 169
 170 You can add options  to `allow`/`warn`/`deny`:
 171
 172 *   the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy)]`)
 173
 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.
 177
 178 *   only some lints (`#![deny(single_match, box_vec)]`, etc)
 179
 180 *   `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc
 181
 182 Note: `deny` produces errors instead of warnings.
 183
 184 For convenience, `cargo clippy` automatically defines a `cargo-clippy`
 185 features. This lets you set lints level and compile with or without clippy
 186 transparently:
 187
 188 ```rust
 189 #[cfg_attr(feature = "cargo-clippy", allow(needless_lifetimes))]
 190 ```
 191
 192 ## Updating rustc
 193
 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
 196 breakage.
 197
 198 You can use the [rust-update](rust-update) script to update rustc only if
 199 clippy would also update correctly.
 200
 201 ## License
 202
 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.