Mirrors/rust-clippy
2
0
Fork 0
mirror of https://github.com/rust-lang/rust-clippy synced 2024-11-16 17:58:14 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #1227 from Manishearth/readme_improvements

Browse source 
List lints at the end of the readme
This commit is contained in:
Manish Goregaokar 2016-09-15 22:18:52 +05:30 committed by GitHub
commit 766217f9ac
1 changed files with 157 additions and 157 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

314
README.md
View file

@ -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/).