diff options
| -rw-r--r-- | book/src/SUMMARY.md | 3 | ||||
| -rw-r--r-- | book/src/continuous_integration/README.md | 4 | ||||
| -rw-r--r-- | book/src/continuous_integration/travis.md | 5 | ||||
| -rw-r--r-- | book/src/installation.md | 24 | ||||
| -rw-r--r-- | book/src/installation_and_usage.md | 88 | ||||
| -rw-r--r-- | book/src/usage.md | 151 |
6 files changed, 177 insertions, 98 deletions
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 595b6138867..db937f95d22 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -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]() diff --git a/book/src/continuous_integration/README.md b/book/src/continuous_integration/README.md index a28959de5c5..257fa0f8df4 100644 --- a/book/src/continuous_integration/README.md +++ b/book/src/continuous_integration/README.md @@ -1,5 +1 @@ # Continuous Integration - -- [Travis CI](travis.md) -- [Github Actions](github_actions.md) -- [Gitlab](gitlab.md) diff --git a/book/src/continuous_integration/travis.md b/book/src/continuous_integration/travis.md index 36e467f9858..85b9ed53dae 100644 --- a/book/src/continuous_integration/travis.md +++ b/book/src/continuous_integration/travis.md @@ -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.) diff --git a/book/src/installation.md b/book/src/installation.md new file mode 100644 index 00000000000..b2a28d0be62 --- /dev/null +++ b/book/src/installation.md @@ -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 diff --git a/book/src/installation_and_usage.md b/book/src/installation_and_usage.md deleted file mode 100644 index 8982e0f1037..00000000000 --- a/book/src/installation_and_usage.md +++ /dev/null @@ -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. - diff --git a/book/src/usage.md b/book/src/usage.md new file mode 100644 index 00000000000..337680aa313 --- /dev/null +++ b/book/src/usage.md @@ -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 |