Skip to content

Commit e40cb6a

Browse files
author
Daniel S Poulin
authored
Further clarify recommended usage
Pushed the section on hard dependency installation to the bottom of the usage methods to further discourage its use. Also included a note in that section warning that it is not the recommended method. Lastly, changed what was said in the opening paragraph of the Usage section to reflect the multitude of options.
1 parent 5a415f6 commit e40cb6a

File tree

1 file changed

+38
-36
lines changed

1 file changed

+38
-36
lines changed

README.md

Lines changed: 38 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@ Table of contents:
1818
## Usage
1919

2020
Since this is a tool for helping the developer of a library or application
21-
write better code, it is recommended to include clippy as an optional
22-
dependency.
21+
write better code, it is recommended not to include clippy as a hard dependency.
22+
Options include using it as an optional dependency, as a cargo subcommand, or
23+
as an included feature during build. All of these options are detailed below.
2324

2425
As a general rule clippy will only work with the *latest* Rust nightly for now.
2526

@@ -52,8 +53,43 @@ Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
5253
(the `-Z no trans`, while not neccessary, will stop the compilation process after
5354
typechecking (and lints) have completed, which can significantly reduce the runtime).
5455

56+
### As a cargo subcommand (`cargo clippy`)
57+
58+
An alternate way to use clippy is by installing clippy through cargo as a cargo
59+
subcommand.
60+
61+
```terminal
62+
cargo install clippy
63+
```
64+
65+
Now you can run clippy by invoking `cargo clippy`, or
66+
`rustup run nightly cargo clippy` directly from a directory that is usually
67+
compiled with stable.
68+
69+
In case you are not using rustup, you need to set the environment flag
70+
`SYSROOT` during installation so clippy knows where to find `librustc` and
71+
similar crates.
72+
73+
```terminal
74+
SYSROOT=/path/to/rustc/sysroot cargo install clippy
75+
```
76+
77+
### Running clippy from the command line without installing
78+
79+
To have cargo compile your crate with clippy without needing `#![plugin(clippy)]`
80+
in your code, you can use:
81+
82+
```terminal
83+
cargo rustc -- -L /path/to/clippy_so -Z extra-plugins=clippy
84+
```
85+
86+
*[Note](https://github.com/Manishearth/rust-clippy/wiki#a-word-of-warning):*
87+
Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
88+
5589
### As a Compiler Plugin
5690

91+
*Note:* This is not a recommended installation method.
92+
5793
Since stable Rust is backwards compatible, you should be able to
5894
compile your stable programs with nightly Rust with clippy plugged in to
5995
circumvent this.
@@ -97,40 +133,6 @@ src/main.rs:8:5: 11:6 help: Try
97133
if let Some(y) = x { println!("{:?}", y) }
98134
```
99135

100-
### As a cargo subcommand (`cargo clippy`)
101-
102-
An alternate way to use clippy is by installing clippy through cargo as a cargo
103-
subcommand.
104-
105-
```terminal
106-
cargo install clippy
107-
```
108-
109-
Now you can run clippy by invoking `cargo clippy`, or
110-
`rustup run nightly cargo clippy` directly from a directory that is usually
111-
compiled with stable.
112-
113-
In case you are not using rustup, you need to set the environment flag
114-
`SYSROOT` during installation so clippy knows where to find `librustc` and
115-
similar crates.
116-
117-
```terminal
118-
SYSROOT=/path/to/rustc/sysroot cargo install clippy
119-
```
120-
121-
### Running clippy from the command line without installing
122-
123-
To have cargo compile your crate with clippy without needing `#![plugin(clippy)]`
124-
in your code, you can use:
125-
126-
```terminal
127-
cargo rustc -- -L /path/to/clippy_so -Z extra-plugins=clippy
128-
```
129-
130-
*[Note](https://github.com/Manishearth/rust-clippy/wiki#a-word-of-warning):*
131-
Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
132-
133-
134136
## Configuration
135137

136138
Some lints can be configured in a `clippy.toml` file. It contains basic `variable = value` mapping eg.

0 commit comments

Comments
 (0)