List lints at the end of the readme
This commit is contained in:
Oliver Schneider
GitHub
parent
dc84759ac5
commit
b778269f54
314
README.md
314
README.md
|
|
@ -15,6 +15,163 @@ Table of contents:
|
|||
* [*clippy-service*](#link-with-clippy-service)
|
||||
* [License](#license)
|
||||
|
||||
## Usage
|
||||
|
||||
As a general rule clippy will only work with the *latest* Rust nightly for now.
|
||||
|
||||
### As a Compiler Plugin
|
||||
|
||||
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) }
|
||||
```
|
||||
|
||||
### 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
|
||||
cargo rustc -- -L /path/to/clippy_so -Z extra-plugins=clippy
|
||||
```
|
||||
|
||||
*[Note](https://github.com/Manishearth/rust-clippy/wiki#a-word-of-warning):*
|
||||
Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
|
||||
|
||||
### Optional dependency
|
||||
|
||||
If you want to make clippy an optional dependency, you can do the following:
|
||||
|
||||
In your `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
clippy = {version = "*", optional = true}
|
||||
|
||||
[features]
|
||||
default = []
|
||||
```
|
||||
|
||||
And, in your `main.rs` or `lib.rs`:
|
||||
|
||||
```rust
|
||||
#![cfg_attr(feature="clippy", feature(plugin))]
|
||||
|
||||
#![cfg_attr(feature="clippy", plugin(clippy))]
|
||||
```
|
||||
|
||||
Then build by enabling the feature: `cargo build --features "clippy"`
|
||||
|
||||
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`
|
||||
(the `-Z no trans`, while not neccessary, will stop the compilation process after
|
||||
typechecking (and lints) have completed, which can significantly reduce the runtime).
|
||||
|
||||
## 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
|
||||
define the `CLIPPY_DISABLE_WIKI_LINKS` environment variable.
|
||||
|
||||
### 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.
|
||||
|
||||
## Link with clippy service
|
||||
|
||||
`clippy-service` is a rust web initiative providing `rust-clippy` as a web service.
|
||||
|
||||
Both projects are independent and maintained by different people
|
||||
(even if some `clippy-service`'s contributions are authored by some `rust-clippy` members).
|
||||
|
||||
You can check out this great service at [clippy.bashy.io](https://clippy.bashy.io/).
|
||||
|
||||
## Lints
|
||||
|
||||
There are 171 lints included in this crate:
|
||||
|
|
@ -195,163 +352,6 @@ name
|
|||
|
||||
More to come, please [file an issue](https://github.com/Manishearth/rust-clippy/issues) if you have ideas!
|
||||
|
||||
## Usage
|
||||
|
||||
As a general rule clippy will only work with the *latest* Rust nightly for now.
|
||||
|
||||
### As a Compiler Plugin
|
||||
|
||||
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) }
|
||||
```
|
||||
|
||||
### 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
|
||||
cargo rustc -- -L /path/to/clippy_so -Z extra-plugins=clippy
|
||||
```
|
||||
|
||||
*[Note](https://github.com/Manishearth/rust-clippy/wiki#a-word-of-warning):*
|
||||
Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
|
||||
|
||||
### Optional dependency
|
||||
|
||||
If you want to make clippy an optional dependency, you can do the following:
|
||||
|
||||
In your `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
clippy = {version = "*", optional = true}
|
||||
|
||||
[features]
|
||||
default = []
|
||||
```
|
||||
|
||||
And, in your `main.rs` or `lib.rs`:
|
||||
|
||||
```rust
|
||||
#![cfg_attr(feature="clippy", feature(plugin))]
|
||||
|
||||
#![cfg_attr(feature="clippy", plugin(clippy))]
|
||||
```
|
||||
|
||||
Then build by enabling the feature: `cargo build --features "clippy"`
|
||||
|
||||
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`
|
||||
(the `-Z no trans`, while not neccessary, will stop the compilation process after
|
||||
typechecking (and lints) have completed, which can significantly reduce the runtime).
|
||||
|
||||
## 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
|
||||
define the `CLIPPY_DISABLE_WIKI_LINKS` environment variable.
|
||||
|
||||
### 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.
|
||||
|
||||
## Link with clippy service
|
||||
|
||||
`clippy-service` is a rust web initiative providing `rust-clippy` as a web service.
|
||||
|
||||
Both projects are independent and maintained by different people
|
||||
(even if some `clippy-service`'s contributions are authored by some `rust-clippy` members).
|
||||
|
||||
You can check out this great service at [clippy.bashy.io](https://clippy.bashy.io/).
|
||||
|
||||
## License
|
||||
|
||||
Licensed under [MPL](https://www.mozilla.org/MPL/2.0/).
|
||||
|
|
|
|||
Loading…
Reference in a new issue