Mirrors/rust-clippy
2
0
Fork 0
mirror of https://github.com/rust-lang/rust-clippy synced 2024-11-26 22:50:56 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #1345 from EpocSquadron/epocsquadron-documentation

Browse source 
Clarify recco to install as a soft dependency
This commit is contained in:
Manish Goregaokar 2016-12-19 03:36:42 -08:00 committed by GitHub
commit cc8c1c0814
1 changed files with 69 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
README.md
View file

@ -16,10 +16,79 @@ Table of contents:
## Usage ## Usage
Since this is a tool for helping the developer of a library or application
write better code, it is recommended not to include clippy as a hard dependency.
Options include using it as an optional dependency, as a cargo subcommand, or
as an included feature during build. All of these options are detailed below.
As a general rule clippy will only work with the *latest* Rust nightly for now. As a general rule clippy will only work with the *latest* Rust nightly for now.
### 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).
### 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!
### As a Compiler Plugin ### As a Compiler Plugin
*Note:* This is not a recommended installation method.
Since stable Rust is backwards compatible, you should be able to Since stable Rust is backwards compatible, you should be able to
compile your stable programs with nightly Rust with clippy plugged in to compile your stable programs with nightly Rust with clippy plugged in to
circumvent this. circumvent this.
@ -63,68 +132,6 @@ src/main.rs:8:5: 11:6 help: Try
if let Some(y) = x { println!("{:?}", y) } 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 ## Configuration
Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg. Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg.