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](https://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 259 lints included in this crate!](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
  11
  12 We have a bunch of lint categories to allow you to choose how much clippy is supposed to ~~annoy~~ help you:
  13
  14 * `clippy` (everything that has no false positives)
  15 * `clippy_pedantic` (everything)
  16 * `clippy_nursery` (new lints that aren't quite ready yet)
  17 * `clippy_style` (code that should be written in a more idiomatic way)
  18 * `clippy_complexity` (code that does something simple but in a complex way)
  19 * `clippy_perf` (code that can be written in a faster way)
  20 * `clippy_cargo` (checks against the cargo manifest)
  21 * **`clippy_correctness`** (code that is just outright wrong or very very useless)
  22
  23 More to come, please [file an issue](https://github.com/rust-lang-nursery/rust-clippy/issues) if you have ideas!
  24
  25 Table of contents:
  26
  27 *   [Usage instructions](#usage)
  28 *   [Configuration](#configuration)
  29 *   [License](#license)
  30
  31 ## Usage
  32
  33 Since this is a tool for helping the developer of a library or application
  34 write better code, it is recommended not to include clippy as a hard dependency.
  35 Options include using it as an optional dependency, as a cargo subcommand, or
  36 as an included feature during build. All of these options are detailed below.
  37
  38 As a general rule clippy will only work with the *latest* Rust nightly for now.
  39
  40 To install Rust nightly, the recommended way is to use [rustup](https://rustup.rs/):
  41
  42 ```terminal
  43 rustup install nightly
  44 ```
  45
  46 ### As a cargo subcommand (`cargo clippy`)
  47
  48 One way to use clippy is by installing clippy through cargo as a cargo
  49 subcommand.
  50
  51 ```terminal
  52 cargo +nightly install clippy
  53 ```
  54
  55 (The `+nightly` is not necessary if your default `rustup` install is nightly)
  56
  57 Now you can run clippy by invoking `cargo +nightly clippy`.
  58
  59 To update the subcommand together with the latest nightly use the [rust-update](rust-update) script or run:
  60
  61 ```terminal
  62 rustup update nightly
  63 cargo +nightly install --force clippy
  64 ```
  65
  66 In case you are not using rustup, you need to set the environment flag
  67 `SYSROOT` during installation so clippy knows where to find `librustc` and
  68 similar crates.
  69
  70 ```terminal
  71 SYSROOT=/path/to/rustc/sysroot cargo install clippy
  72 ```
  73
  74 ### Running clippy from the command line without installing it
  75
  76 To have cargo compile your crate with clippy without clippy installation
  77 in your code, you can use:
  78
  79 ```terminal
  80 cargo run --bin cargo-clippy --manifest-path=path_to_clippys_Cargo.toml
  81 ```
  82
  83 *[Note](https://github.com/rust-lang-nursery/rust-clippy/wiki#a-word-of-warning):*
  84 Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
  85
  86 ## Configuration
  87
  88 Some lints can be configured in a TOML file named with `clippy.toml` or `.clippy.toml`. It contains basic `variable = value` mapping eg.
  89
  90 ```toml
  91 blacklisted-names = ["toto", "tata", "titi"]
  92 cyclomatic-complexity-threshold = 30
  93 ```
  94
  95 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
  96 meaning of the variables.
  97
  98 To deactivate the “for further information visit *lint-link*” message you can
  99 define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
 100
 101 ### Allowing/denying lints
 102
 103 You can add options  to `allow`/`warn`/`deny`:
 104
 105 *   the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy)]`)
 106
 107 *   all lints using both the `clippy` and `clippy_pedantic` lint groups (`#![deny(clippy)]`,
 108     `#![deny(clippy_pedantic)]`). Note that `clippy_pedantic` contains some very aggressive
 109     lints prone to false positives.
 110
 111 *   only some lints (`#![deny(single_match, box_vec)]`, etc)
 112
 113 *   `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc
 114
 115 Note: `deny` produces errors instead of warnings.
 116
 117 For convenience, `cargo clippy` automatically defines a `cargo-clippy`
 118 feature. This lets you set lint levels and compile with or without clippy
 119 transparently:
 120
 121 ```rust
 122 #[cfg_attr(feature = "cargo-clippy", allow(needless_lifetimes))]
 123 ```
 124
 125 ## Updating rustc
 126
 127 Sometimes, rustc moves forward without clippy catching up. Therefore updating
 128 rustc may leave clippy a non-functional state until we fix the resulting
 129 breakage.
 130
 131 You can use the [rust-update](rust-update) script to update rustc only if
 132 clippy would also update correctly.
 133
 134 ## License
 135
 136 Licensed under [MPL](https://www.mozilla.org/MPL/2.0/).
 137 If you're having issues with the license, let me know and I'll try to change it to something more permissive.