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