From b778269f543462e5a486e00b3f7be19b6185af9f Mon Sep 17 00:00:00 2001 From: Oliver Schneider Date: Thu, 15 Sep 2016 17:19:30 +0200 Subject: [PATCH] List lints at the end of the readme --- README.md | 314 +++++++++++++++++++++++++++--------------------------- 1 file changed, 157 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index ba0973b0e67..7aec86c2f39 100644 --- a/README.md +++ b/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/).