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 code.
   9
  10 Table of contents:
  11
  12 *   [Lint list](#lints)
  13 *   [Usage instructions](#usage)
  14 *   [Configuration](#configuration)
  15 *   [License](#license)
  16
  17 ## Usage
  18
  19 Since this is a tool for helping the developer of a library or application
  20 write better code, it is recommended not to include clippy as a hard dependency.
  21 Options include using it as an optional dependency, as a cargo subcommand, or
  22 as an included feature during build. All of these options are detailed below.
  23
  24 As a general rule clippy will only work with the *latest* Rust nightly for now.
  25
  26 ### Optional dependency
  27
  28 If you want to make clippy an optional dependency, you can do the following:
  29
  30 In your `Cargo.toml`:
  31
  32 ```toml
  33 [dependencies]
  34 clippy = {version = "*", optional = true}
  35
  36 [features]
  37 default = []
  38 ```
  39
  40 And, in your `main.rs` or `lib.rs`:
  41
  42 ```rust
  43 #![cfg_attr(feature="clippy", feature(plugin))]
  44
  45 #![cfg_attr(feature="clippy", plugin(clippy))]
  46 ```
  47
  48 Then build by enabling the feature: `cargo build --features "clippy"`
  49
  50 Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
  51 `cargo rustc --features clippy -- -Z no-trans -Z extra-plugins=clippy`
  52 (the `-Z no trans`, while not necessary, will stop the compilation process after
  53 typechecking (and lints) have completed, which can significantly reduce the runtime).
  54
  55 ### As a cargo subcommand (`cargo clippy`)
  56
  57 An alternate way to use clippy is by installing clippy through cargo as a cargo
  58 subcommand.
  59
  60 ```terminal
  61 cargo install clippy
  62 ```
  63
  64 Now you can run clippy by invoking `cargo clippy`, or
  65 `rustup run nightly cargo clippy` directly from a directory that is usually
  66 compiled with stable.
  67
  68 In case you are not using rustup, you need to set the environment flag
  69 `SYSROOT` during installation so clippy knows where to find `librustc` and
  70 similar crates.
  71
  72 ```terminal
  73 SYSROOT=/path/to/rustc/sysroot cargo install clippy
  74 ```
  75
  76 ### Running clippy from the command line without installing
  77
  78 To have cargo compile your crate with clippy without needing `#![plugin(clippy)]`
  79 in your code, you can use:
  80
  81 ```terminal
  82 cargo rustc -- -L /path/to/clippy_so/dir/ -Z extra-plugins=clippy
  83 ```
  84
  85 *[Note](https://github.com/rust-lang-nursery/rust-clippy/wiki#a-word-of-warning):*
  86 Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
  87
  88 ### As a Compiler Plugin
  89
  90 *Note:* This is not a recommended installation method.
  91
  92 Since stable Rust is backwards compatible, you should be able to
  93 compile your stable programs with nightly Rust with clippy plugged in to
  94 circumvent this.
  95
  96 Add in your `Cargo.toml`:
  97
  98 ```toml
  99 [dependencies]
 100 clippy = "*"
 101 ```
 102
 103 You then need to add `#![feature(plugin)]` and `#![plugin(clippy)]` to the top
 104 of your crate entry point (`main.rs` or `lib.rs`).
 105
 106 Sample `main.rs`:
 107
 108 ```rust
 109 #![feature(plugin)]
 110
 111 #![plugin(clippy)]
 112
 113
 114 fn main(){
 115     let x = Some(1u8);
 116     match x {
 117         Some(y) => println!("{:?}", y),
 118         _ => ()
 119     }
 120 }
 121 ```
 122
 123 Produces this warning:
 124
 125 ```terminal
 126 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
 127 src/main.rs:8     match x {
 128 src/main.rs:9         Some(y) => println!("{:?}", y),
 129 src/main.rs:10         _ => ()
 130 src/main.rs:11     }
 131 src/main.rs:8:5: 11:6 help: Try
 132 if let Some(y) = x { println!("{:?}", y) }
 133 ```
 134
 135 ## Configuration
 136
 137 Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg.
 138
 139 ```toml
 140 blacklisted-names = ["toto", "tata", "titi"]
 141 cyclomatic-complexity-threshold = 30
 142 ```
 143
 144 See the wiki for more information about which lints can be configured and the
 145 meaning of the variables.
 146
 147 You can also specify the path to the configuration file with:
 148
 149 ```rust
 150 #![plugin(clippy(conf_file="path/to/clippy's/configuration"))]
 151 ```
 152
 153 To deactivate the “for further information visit *wiki-link*” message you can
 154 define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
 155
 156 ### Allowing/denying lints
 157
 158 You can add options  to `allow`/`warn`/`deny`:
 159
 160 *   the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy)]`)
 161
 162 *   all lints using both the `clippy` and `clippy_pedantic` lint groups (`#![deny(clippy)]`,
 163     `#![deny(clippy_pedantic)]`). Note that `clippy_pedantic` contains some very aggressive
 164     lints prone to false positives.
 165
 166 *   only some lints (`#![deny(single_match, box_vec)]`, etc)
 167
 168 *   `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc
 169
 170 Note: `deny` produces errors instead of warnings.
 171
 172 For convenience, `cargo clippy` automatically defines a `cargo-clippy`
 173 features. This lets you set lints level and compile with or without clippy
 174 transparently:
 175
 176 ```rust
 177 #[cfg_attr(feature = "cargo-clippy", allow(needless_lifetimes))]
 178 ```
 179
 180 ## Lints
 181
 182 [There are 209 lints included in this crate](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
 183
 184 More to come, please [file an issue](https://github.com/rust-lang-nursery/rust-clippy/issues) if you have ideas!
 185
 186 ## License
 187
 188 Licensed under [MPL](https://www.mozilla.org/MPL/2.0/).
 189 If you're having issues with the license, let me know and I'll try to change it to something more permissive.