Skip to content

Commit d12a5c3

Browse files
flip1995flip1995
committed
Book: Split up and rewrite installation and usage
1 parent 404432b commit d12a5c3

File tree

6 files changed

+177
-98
lines changed

6 files changed

+177
-98
lines changed

‎book/src/SUMMARY.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
[Introduction](README.md)
44

5-
- [Installation and Usage](installation_and_usage.md)
5+
- [Installation](installation.md)
6+
- [Usage](usage.md)
67
- [Configuration](configuration.md)
78
- [Clippy's Lints](lints/README.md)
89
- [Correctness]()

‎book/src/continuous_integration/README.md

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
11
# Continuous Integration
2-
3-
- [Travis CI](travis.md)
4-
- [Github Actions](github_actions.md)
5-
- [Gitlab](gitlab.md)

‎book/src/continuous_integration/travis.md

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,3 @@ script:
1818
- cargo test
1919
# etc.
2020
```
21-
22-
Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.
23-
That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause
24-
an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command
25-
line. (You can swap `clippy::all` with the specific lint category you are targeting.)

‎book/src/installation.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Installation
2+
3+
If you're using `rustup` to install and manage you're Rust toolchains, Clippy is
4+
usually **already installed**. In that case you can skip this chapter and go to
5+
the [Usage] chapter.
6+
7+
> Note: If you used the `minimal` profile when installing a Rust toolchain,
8+
> Clippy is not automatically installed.
9+
10+
## Using Rustup
11+
12+
If Clippy was not installed for a toolchain, it can be installed with
13+
14+
```
15+
$ rustup component add clippy [--toolchain=<name>]
16+
```
17+
18+
## From Source
19+
20+
Take a look at the [Basics] chapter in the Clippy developer guide to find step
21+
by step instructions on how to build and install Clippy from source.
22+
23+
[Basics]: development/basics.md#install-from-source
24+
[Usage]: usage.md

‎book/src/installation_and_usage.md

Lines changed: 0 additions & 88 deletions
This file was deleted.

‎book/src/usage.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Usage
2+
3+
This chapter describes how to use Clippy to get the most out of it. Clippy can
4+
be used as a `cargo` subcommand or, like `rustc`, directly with the
5+
`clippy-driver` binary.
6+
7+
> _Note:_ This chapter assumes that you have Clippy installed already. If you're
8+
> not sure, take a look at the [Installation] chapter.
9+
10+
## Cargo subcommand
11+
12+
The easiest and most common way to run Clippy is through `cargo`. To do that,
13+
just run
14+
15+
```bash
16+
cargo clippy
17+
```
18+
19+
### Lint configuration
20+
21+
The above command will run the default set of lints, which are included in the
22+
lint group `clippy::all`. You might want to use even more lints or you might not
23+
agree with every Clippy lint, and for that there are ways to configure lint
24+
levels.
25+
26+
> _Note:_ Clippy is meant to be used with a generous sprinkling of
27+
> `#[allow(..)]`s through your code. So if you disagree with a lint, don't feel
28+
> bad disabling them for parts of your code or the whole project.
29+
30+
#### Command line
31+
32+
You can configure lint levels on the command line by adding
33+
`-A/W/D clippy::lint_name` like this:
34+
35+
```bash
36+
cargo clippy -- -Aclippy::style -Wclippy::double_neg -Dclippy::perf
37+
```
38+
39+
For [CI] all warnings can be elevated to errors which will inturn fail
40+
the build and cause Clippy to exit with a code other than `0`.
41+
42+
```
43+
cargo clippy -- -Dwarnings
44+
```
45+
46+
> _Note:_ Adding `-D warnings` will cause your build to fail if **any** warnings
47+
> are found in your code. That includes warnings found by rustc (e.g.
48+
> `dead_code`, etc.).
49+
50+
For more information on configuring lint levels, see the [rustc documentation].
51+
52+
[rustc documentation]: https://doc.rust-lang.org/rustc/lints/levels.html#configuring-warning-levels
53+
54+
#### Even more lints
55+
56+
Clippy has lint groups which are allow-by-default. This means, that you will
57+
have to enable the lints in those groups manually.
58+
59+
For a full list of all lints with their description and examples, please refere
60+
to [Clippy's lint list]. The two most important allow-by-default groups are
61+
described below:
62+
63+
[Clippy's lint list]: https://rust-lang.github.io/rust-clippy/master/index.html
64+
65+
##### `clippy::pedantic`
66+
67+
The first group is the `pedantic` group. This group contains really opinionated
68+
lints, that may have some intentional false positives in order to prevent false
69+
negatives. So while this group is ready to be used in production, you can expect
70+
to sprinkle multiple `#[allow(..)]`s in your code. If you find any false
71+
positives, you're still welcome to report them to us for future improvements.
72+
73+
> FYI: Clippy uses the whole group to lint itself.
74+
75+
##### `clippy::restriction`
76+
77+
The second group is the `restriction` group. This group contains lints that
78+
"restrict" the language in some way. For example the `clippy::unwrap` lint from
79+
this group won't allow you to use `.unwrap()` in your code. You may want to look
80+
through the lints in this group and enable the ones that fit your need.
81+
82+
> _Note:_ You shouldn't enable the whole lint group, but cherry-pick lints from
83+
> this group. Some lints in this group will even contradict other Clippy lints!
84+
85+
#### Too many lints
86+
87+
The most opinionated warn-by-default group of Clippy is the `clippy::style`
88+
group. Some people prefer to disable this group completely and then cherry-pick
89+
some lints they like from this group. The same is of course possible with every
90+
other of Clippy's lint groups.
91+
92+
> _Note:_ We try to keep the warn-by-default groups free from false positives
93+
> (FP). If you find that a lint wrongly triggers, please report it in an issue
94+
> (if there isn't an issue for that FP already)
95+
96+
#### Source Code
97+
98+
You can configure lint levels in source code the same way you can configure
99+
`rustc` lints:
100+
101+
```rust
102+
#![allow(clippy::style)]
103+
104+
#[warn(clippy::double_neg)]
105+
fn main() {
106+
let x = 1;
107+
let y = --x;
108+
// ^^ warning: double negation
109+
}
110+
```
111+
112+
### Automatically applying Clippy suggestions
113+
114+
Clippy can automatically apply some lint suggestions, just like the compiler.
115+
116+
```terminal
117+
cargo clippy --fix
118+
```
119+
120+
### Workspaces
121+
122+
All the usual workspace options should work with Clippy. For example the
123+
following command will run Clippy on the `example` crate in your workspace:
124+
125+
```terminal
126+
cargo clippy -p example
127+
```
128+
129+
As with `cargo check`, this includes dependencies that are members of the
130+
workspace, like path dependencies. If you want to run Clippy **only** on the
131+
given crate, use the `--no-deps` option like this:
132+
133+
```terminal
134+
cargo clippy -p example -- --no-deps
135+
```
136+
137+
## Using Clippy without `cargo`: `clippy-driver`
138+
139+
Clippy can also be used in projects that do not use cargo. To do so, run
140+
`clippy-driver` with the same arguments you use for `rustc`. For example:
141+
142+
```terminal
143+
clippy-driver --edition 2018 -Cpanic=abort foo.rs
144+
```
145+
146+
> _Note:_ `clippy-driver` is designed for running Clippy and should not be used
147+
> as a general replacement for `rustc`. `clippy-driver` may produce artifacts
148+
> that are not optimized as expected, for example.
149+
150+
[Installation]: installation.md
151+
[CI]: continuous_integration

0 commit comments

Comments
 (0)