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

Book: Split up and rewrite installation and usage

Browse source
This commit is contained in:
flip1995 2022-01-21 18:24:43 +01:00 committed by Philipp Krones
parent 404432b791
commit d12a5c3a52
No known key found for this signature in database
GPG key ID: 1CA0DF2AF59D68A5
6 changed files with 177 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
book/src/SUMMARY.md
View file

@ -2,7 +2,8 @@
[Introduction](README.md)
- [Installation and Usage](installation_and_usage.md)
- [Installation](installation.md)
- [Usage](usage.md)
- [Configuration](configuration.md)
- [Clippy's Lints](lints/README.md)
- [Correctness]()

4
book/src/continuous_integration/README.md
View file

@ -1,5 +1 @@
# Continuous Integration
- [Travis CI](travis.md)
- [Github Actions](github_actions.md)
- [Gitlab](gitlab.md)

5
book/src/continuous_integration/travis.md
View file

@ -18,8 +18,3 @@ script:
- cargo test
# etc.
```
Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.
That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause
an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command
line. (You can swap `clippy::all` with the specific lint category you are targeting.)

24
book/src/installation.md Normal file
View file

@ -0,0 +1,24 @@
# Installation
If you're using `rustup` to install and manage you're Rust toolchains, Clippy is
usually **already installed**. In that case you can skip this chapter and go to
the [Usage] chapter.
> Note: If you used the `minimal` profile when installing a Rust toolchain,
> Clippy is not automatically installed.
## Using Rustup
If Clippy was not installed for a toolchain, it can be installed with
```
$ rustup component add clippy [--toolchain=<name>]
```
## From Source
Take a look at the [Basics] chapter in the Clippy developer guide to find step
by step instructions on how to build and install Clippy from source.
[Basics]: development/basics.md#install-from-source
[Usage]: usage.md

88
book/src/installation_and_usage.md
View file

@ -1,88 +0,0 @@
# Installation and Usage
Below are instructions on how to use Clippy as a subcommand, compiled from source
or in Travis CI. Note that Clippy is installed as a
[component](https://rust-lang.github.io/rustup/concepts/components.html?highlight=clippy#components) as part of the
[rustup](https://rust-lang.github.io/rustup/installation/index.html) installation.
### As a cargo subcommand (`cargo clippy`)
One way to use Clippy is by installing Clippy through rustup as a cargo
subcommand.
#### Step 1: Install rustup
You can install [rustup](https://rustup.rs/) on supported platforms. This will help
us install Clippy and its dependencies.
If you already have rustup installed, update to ensure you have the latest
rustup and compiler:
```terminal
rustup update
```
#### Step 2: Install Clippy
Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:
```terminal
rustup component add clippy
```
If it says that it can't find the `clippy` component, please run `rustup self update`.
#### Step 3: Run Clippy
Now you can run Clippy by invoking the following command:
```terminal
cargo clippy
```
#### Automatically applying Clippy suggestions
Clippy can automatically apply some lint suggestions.
Note that this is still experimental and only supported on the nightly channel:
```terminal
cargo clippy --fix
```
#### Workspaces
All the usual workspace options should work with Clippy. For example the following command
will run Clippy on the `example` crate:
```terminal
cargo clippy -p example
```
As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies.
If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this:
```terminal
cargo clippy -p example --no-deps
```
### As a rustc replacement (`clippy-driver`)
Clippy can also be used in projects that do not use cargo. To do so, you will need to replace
your `rustc` compilation commands with `clippy-driver`. For example, if your project runs:
```terminal
rustc --edition 2018 -Cpanic=abort foo.rs
```
Then, to enable Clippy, you will need to call:
```terminal
clippy-driver --edition 2018 -Cpanic=abort foo.rs
```
Note that `rustc` will still run, i.e. it will still emit the output files it normally does.
### Continuous Integration
Adding Clippy to your continuous integration pipeline is a great way to automate the linting process. See the
[Continuous Integration](continuous_integration) chapter for more information.

151
book/src/usage.md Normal file
View file

@ -0,0 +1,151 @@
# Usage
This chapter describes how to use Clippy to get the most out of it. Clippy can
be used as a `cargo` subcommand or, like `rustc`, directly with the
`clippy-driver` binary.
> _Note:_ This chapter assumes that you have Clippy installed already. If you're
> not sure, take a look at the [Installation] chapter.
## Cargo subcommand
The easiest and most common way to run Clippy is through `cargo`. To do that,
just run
```bash
cargo clippy
```
### Lint configuration
The above command will run the default set of lints, which are included in the
lint group `clippy::all`. You might want to use even more lints or you might not
agree with every Clippy lint, and for that there are ways to configure lint
levels.
> _Note:_ Clippy is meant to be used with a generous sprinkling of
> `#[allow(..)]`s through your code. So if you disagree with a lint, don't feel
> bad disabling them for parts of your code or the whole project.
#### Command line
You can configure lint levels on the command line by adding
`-A/W/D clippy::lint_name` like this:
```bash
cargo clippy -- -Aclippy::style -Wclippy::double_neg -Dclippy::perf
```
For [CI] all warnings can be elevated to errors which will inturn fail
the build and cause Clippy to exit with a code other than `0`.
```
cargo clippy -- -Dwarnings
```
> _Note:_ Adding `-D warnings` will cause your build to fail if **any** warnings
> are found in your code. That includes warnings found by rustc (e.g.
> `dead_code`, etc.).
For more information on configuring lint levels, see the [rustc documentation].
[rustc documentation]: https://doc.rust-lang.org/rustc/lints/levels.html#configuring-warning-levels
#### Even more lints
Clippy has lint groups which are allow-by-default. This means, that you will
have to enable the lints in those groups manually.
For a full list of all lints with their description and examples, please refere
to [Clippy's lint list]. The two most important allow-by-default groups are
described below:
[Clippy's lint list]: https://rust-lang.github.io/rust-clippy/master/index.html
##### `clippy::pedantic`
The first group is the `pedantic` group. This group contains really opinionated
lints, that may have some intentional false positives in order to prevent false
negatives. So while this group is ready to be used in production, you can expect
to sprinkle multiple `#[allow(..)]`s in your code. If you find any false
positives, you're still welcome to report them to us for future improvements.
> FYI: Clippy uses the whole group to lint itself.
##### `clippy::restriction`
The second group is the `restriction` group. This group contains lints that
"restrict" the language in some way. For example the `clippy::unwrap` lint from
this group won't allow you to use `.unwrap()` in your code. You may want to look
through the lints in this group and enable the ones that fit your need.
> _Note:_ You shouldn't enable the whole lint group, but cherry-pick lints from
> this group. Some lints in this group will even contradict other Clippy lints!
#### Too many lints
The most opinionated warn-by-default group of Clippy is the `clippy::style`
group. Some people prefer to disable this group completely and then cherry-pick
some lints they like from this group. The same is of course possible with every
other of Clippy's lint groups.
> _Note:_ We try to keep the warn-by-default groups free from false positives
> (FP). If you find that a lint wrongly triggers, please report it in an issue
> (if there isn't an issue for that FP already)
#### Source Code
You can configure lint levels in source code the same way you can configure
`rustc` lints:
```rust
#![allow(clippy::style)]
#[warn(clippy::double_neg)]
fn main() {
let x = 1;
let y = --x;
// ^^ warning: double negation
}
```
### Automatically applying Clippy suggestions
Clippy can automatically apply some lint suggestions, just like the compiler.
```terminal
cargo clippy --fix
```
### Workspaces
All the usual workspace options should work with Clippy. For example the
following command will run Clippy on the `example` crate in your workspace:
```terminal
cargo clippy -p example
```
As with `cargo check`, this includes dependencies that are members of the
workspace, like path dependencies. If you want to run Clippy **only** on the
given crate, use the `--no-deps` option like this:
```terminal
cargo clippy -p example -- --no-deps
```
## Using Clippy without `cargo`: `clippy-driver`
Clippy can also be used in projects that do not use cargo. To do so, run
`clippy-driver` with the same arguments you use for `rustc`. For example:
```terminal
clippy-driver --edition 2018 -Cpanic=abort foo.rs
```
> _Note:_ `clippy-driver` is designed for running Clippy and should not be used
> as a general replacement for `rustc`. `clippy-driver` may produce artifacts
> that are not optimized as expected, for example.
[Installation]: installation.md
[CI]: continuous_integration