Mirrors/rust-clippy
2
0
Fork 0
mirror of https://github.com/rust-lang/rust-clippy synced 2024-11-22 20:53:21 +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
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.
### 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
*Note:* This is not a recommended installation method.
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.
@ -63,68 +132,6 @@ 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.