X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=README.md;h=2c3defeaa83078d2d124d62fbc1bb3cb6458d600;hb=f93d418f1789a5782053e99038db7d6701c8a30c;hp=8c0c16c443dfcd4153f43318e9a2568214fb99e6;hpb=7fcd15571201d55951cf518a564069ff3ed115aa;p=rust.git diff --git a/README.md b/README.md index 8c0c16c443d..2c3defeaa83 100644 --- a/README.md +++ b/README.md @@ -5,21 +5,22 @@ A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code. -[There are over 450 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html) +[There are over 550 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html) Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html). You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category. -| Category | Description | Default level | -| --------------------- | ----------------------------------------------------------------------- | ------------- | -| `clippy::all` | all lints that are on by default (correctness, style, complexity, perf) | **warn/deny** | -| `clippy::correctness` | code that is outright wrong or very useless | **deny** | -| `clippy::style` | code that should be written in a more idiomatic way | **warn** | -| `clippy::complexity` | code that does something simple but in a complex way | **warn** | -| `clippy::perf` | code that can be written to run faster | **warn** | -| `clippy::pedantic` | lints which are rather strict or might have false positives | allow | -| `clippy::nursery` | new lints that are still under development | allow | -| `clippy::cargo` | lints for the cargo manifest | allow | +| Category | Description | Default level | +| --------------------- | ----------------------------------------------------------------------------------- | ------------- | +| `clippy::all` | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** | +| `clippy::correctness` | code that is outright wrong or useless | **deny** | +| `clippy::suspicious` | code that is most likely wrong or useless | **warn** | +| `clippy::style` | code that should be written in a more idiomatic way | **warn** | +| `clippy::complexity` | code that does something simple but in a complex way | **warn** | +| `clippy::perf` | code that can be written to run faster | **warn** | +| `clippy::pedantic` | lints which are rather strict or have occasional false positives | allow | +| `clippy::nursery` | new lints that are still under development | allow | +| `clippy::cargo` | lints for the cargo manifest | allow | More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas! @@ -36,21 +37,21 @@ Table of contents: ## Usage -Below are instructions on how to use Clippy as a subcommand, compiled from source -or in Travis CI. +Below are instructions on how to use Clippy as a cargo subcommand, +in projects that do not use cargo, or in Travis CI. ### 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 +#### Step 1: Install Rustup -You can install [rustup](https://rustup.rs/) on supported platforms. This will help +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: +If you already have Rustup installed, update to ensure you have the latest +Rustup and compiler: ```terminal rustup update @@ -75,11 +76,10 @@ 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: +Clippy can automatically apply some lint suggestions, just like the compiler. ```terminal -cargo clippy --fix -Z unstable-options +cargo clippy --fix ``` #### Workspaces @@ -95,25 +95,21 @@ As with `cargo check`, this includes dependencies that are members of the worksp 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 +cargo clippy -p example -- --no-deps ``` -### As a rustc replacement (`clippy-driver`) +### Using `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: +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 that `rustc` will still run, i.e. it will still emit the output files it normally does. +Note that `clippy-driver` is designed for running Clippy only and should not be used as a general +replacement for `rustc`. `clippy-driver` may produce artifacts that are not optimized as expected, +for example. ### Travis CI @@ -144,9 +140,10 @@ line. (You can swap `clippy::all` with the specific lint category you are target ## Configuration Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable = -value` mapping eg. +value` mapping e.g. ```toml +avoid-breaking-exported-api = false blacklisted-names = ["toto", "tata", "titi"] cognitive-complexity-threshold = 30 ``` @@ -154,6 +151,10 @@ cognitive-complexity-threshold = 30 See the [list of lints](https://rust-lang.github.io/rust-clippy/master/index.html) for more information about which lints can be configured and the meaning of the variables. +Note that configuration changes will not apply for code that has already been compiled and cached under `./target/`; +for example, adding a new string to `doc-valid-idents` may still result in Clippy flagging that string. To be sure that +any configuration changes are applied, you may want to run `cargo clean` and re-compile your crate from scratch. + To deactivate the “for further information visit *lint-link*” message you can define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable. @@ -161,7 +162,8 @@ define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable. You can add options to your code to `allow`/`warn`/`deny` Clippy lints: -* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`) +* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`). + Note that `rustc` has additional [lint groups](https://doc.rust-lang.org/rustc/lints/groups.html). * all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`, `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive @@ -191,7 +193,7 @@ And to warn on `lint_name`, run cargo clippy -- -W clippy::lint_name ``` -This also works with lint groups. For example you +This also works with lint groups. For example, you can run Clippy with warnings for all lints enabled: ```terminal cargo clippy -- -W clippy::pedantic @@ -212,6 +214,14 @@ specifying the minimum supported Rust version (MSRV) in the clippy configuration msrv = "1.30.0" ``` +Alternatively, the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) +in the `Cargo.toml` can be used. + +```toml +# Cargo.toml +rust-version = "1.30" +``` + The MSRV can also be specified as an inner attribute, like below. ```rust @@ -226,7 +236,7 @@ fn main() { You can also omit the patch version when specifying the MSRV, so `msrv = 1.30` is equivalent to `msrv = 1.30.0`. -Note: `custom_inner_attributes` is an unstable feature so it has to be enabled explicitly. +Note: `custom_inner_attributes` is an unstable feature, so it has to be enabled explicitly. Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv) @@ -236,7 +246,7 @@ If you want to contribute to Clippy, you can find more information in [CONTRIBUT ## License -Copyright 2014-2020 The Rust Project Developers +Copyright 2014-2022 The Rust Project Developers Licensed under the Apache License, Version 2.0 or the MIT license