docs: document build.warnings as alternative to -Dwarnings (#17072)

Cargo 1.97 stabilized `build.warnings` but Clippy docs only mention
`-Dwarnings`. Documents `build.warnings` as an alternative that does not
invalidate build caches.

changelog: none

Refs #16963

Author: llogiq

README.md

@@ -140,18 +140,27 @@ before_script:
 script:
   - cargo clippy
   # if you want the build job to fail when encountering warnings, use
-  - cargo clippy -- -D warnings
+  - CARGO_BUILD_WARNINGS=deny cargo clippy
   # in order to also check tests and non-default crate features, use
-  - cargo clippy --all-targets --all-features -- -D warnings
+  - CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets --all-features
   - cargo test
   # etc.
 ```
 
-Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.
+Note that setting `CARGO_BUILD_WARNINGS=deny` 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.)
 
+Also note that before Cargo 1.97, the usual way to deny all warnings was by using `-D warnings`:
+
+```shell
+cargo clippy -- -D warnings
+```
+
+However, [`CARGO_BUILD_WARNINGS`] has the benefit of not invalidating build caches,
+and is thus to be preferred going forward.
+
 ## Configuration
 
 ### Allowing/denying lints
@@ -286,3 +295,5 @@ option. Files in the project may not be
 copied, modified, or distributed except according to those terms.
 
 <!-- REUSE-IgnoreEnd -->
+
+[`CARGO_BUILD_WARNINGS`]: https://doc.rust-lang.org/cargo/reference/config.html#buildwarnings

book/src/usage.md

@@ -36,16 +36,40 @@ You can configure lint levels on the command line by adding
 cargo clippy -- -Aclippy::style -Wclippy::box_default -Dclippy::perf
 ```
 
+#### Elevating warning to errors
+
 For [CI] all warnings can be elevated to errors which will in turn fail
 the build and cause Clippy to exit with a code other than `0`.
 
+Since Cargo 1.97, the recommended way to do this is by using the [`build.warnings`] config option.
+
+It can be enabled on the command line using the environment variable:
+
+```bash
+CARGO_BUILD_WARNINGS=deny cargo clippy
 ```
-cargo clippy -- -Dwarnings
+
+.. or permanently, in `.cargo/config.toml`:
+
+```toml
+# .cargo/config.toml
+[build]
+warnings = "deny"
 ```
 
-> _Note:_ Adding `-D warnings` will cause your build to fail if **any** warnings
+> _Note:_ Using `CARGO_BUILD_WARNINGS=deny` (or `-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.).
+> `dead_code`, etc.)
+
+If you use an older version of Cargo, you can use the following instead:
+
+```bash
+cargo clippy -- -Dwarnings
+```
+
+Note, however, that this will invalidate build caches and is therefore not recommended.
+
+[`build.warnings`]: https://doc.rust-lang.org/cargo/reference/config.html#buildwarnings
 
 For more information on configuring lint levels, see the [rustc documentation].