Adjust documentation for newly stabilized -Zcheck-cfg

Author: Urgau

src/doc/src/reference/build-scripts.md

@@ -130,6 +130,8 @@ one detailed below.
   compiler.
 * [`cargo::rustc-cfg=KEY[="VALUE"]`](#rustc-cfg) --- Enables compile-time `cfg`
   settings.
+* [`cargo::rustc-check-cfg=CHECK_CFG`](#rustc-check-cfg) -- Enables compile-time
+  checking of configs. 
 * [`cargo::rustc-env=VAR=VALUE`](#rustc-env) --- Sets an environment variable.
 * [`cargo::rustc-cdylib-link-arg=FLAG`](#rustc-cdylib-link-arg) --- Passes custom
   flags to a linker for cdylib crates.
@@ -233,7 +235,9 @@ equivalent to using [`rustc-link-lib`](#rustc-link-lib) and
 
 The `rustc-cfg` instruction tells Cargo to pass the given value to the
 [`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time
-detection of features to enable [conditional compilation].
+detection of features to enable [conditional compilation]. Each custom cfgs
+must **always** be declared using the [`cargo::rustc-check-cfg`](#rustc-check-cfg)
+instruction.
 
 Note that this does *not* affect Cargo's dependency resolution. This cannot be
 used to enable an optional dependency, or enable other Cargo features.
@@ -250,6 +254,45 @@ identifier, the value should be a string.
 [conditional compilation]: ../../reference/conditional-compilation.md
 [option-cfg]: ../../rustc/command-line-arguments.md#option-cfg
 
+### `cargo::rustc-check-cfg=CHECK_CFG` {#rustc-check-cfg}
+
+The `rustc-check-cfg` instruction tells Cargo to pass the given expected
+configs to the [`--check-cfg` flag][option-check-cfg] to the compiler. This is
+used for compile-time detection of unexpected [conditional compilation] configs.
+
+You can use the instruction like this:
+
+```rust,no_run
+// build.rs
+println!("cargo::rustc-check-cfg=cfg(foo, values(\"bar\"))");
+```
+
+Note that all possible cfgs should be defined, regardless of which cfgs are
+currently enabled. This includes all possible values of a given cfg name.
+
+It is recommended to group the `cargo::rustc-check-cfg` and
+[`cargo::rustc-cfg`][option-cfg] instructions as closely as possible in order to
+avoid typos, missing check-cfg, stalled cfgs...
+
+<details>
+<summary>
+
+Example of using `cargo::rustc-check-cfg` and `cargo::rustc-cfg` together
+
+</summary>
+
+```rust,no_run
+// build.rs
+println!("cargo::rustc-check-cfg=cfg(foo, values(\"bar\"))");
+if foo_bar_condition {
+    println!("cargo::rustc-cfg=foo=\"bar\"");
+}
+```
+
+</details>
+
+[option-cfg]: ../../rustc/command-line-arguments.md#option-check-cfg
+
 ### `cargo::rustc-env=VAR=VALUE` {#rustc-env}
 
 The `rustc-env` instruction tells Cargo to set the given environment variable

src/doc/src/reference/unstable.md

@@ -83,7 +83,6 @@ For the latest nightly, see the [nightly version] of this page.
     * [build-std-features](#build-std-features) --- Sets features to use with the standard library.
     * [binary-dep-depinfo](#binary-dep-depinfo) --- Causes the dep-info file to track binary dependencies.
     * [panic-abort-tests](#panic-abort-tests) --- Allows running tests with the "abort" panic strategy.
-    * [check-cfg](#check-cfg) --- Compile-time validation of `cfg` expressions.
     * [host-config](#host-config) --- Allows setting `[target]`-like configuration settings for host build targets.
     * [target-applies-to-host](#target-applies-to-host) --- Alters whether certain flags will be passed to host build targets.
     * [gc](#gc) --- Global cache garbage collection.
@@ -1127,44 +1126,6 @@ You can use the flag like this:
 cargo rustdoc -Z unstable-options --output-format json
 ```
 
-## check-cfg
-
-* RFC: [#3013](https://github.com/rust-lang/rfcs/pull/3013)
-* Tracking Issue: [#10554](https://github.com/rust-lang/cargo/issues/10554)
-
-`-Z check-cfg` command line enables compile time checking of Cargo features as well as `rustc`
-well known names and values in `#[cfg]`, `cfg!`, `#[link]` and `#[cfg_attr]` with the `rustc`
-and `rustdoc` unstable `--check-cfg` command line.
-
-You can use the flag like this:
-
-```
-cargo check -Z unstable-options -Z check-cfg
-```
-
-### `cargo::rustc-check-cfg=CHECK_CFG`
-
-The `rustc-check-cfg` instruction tells Cargo to pass the given value to the
-`--check-cfg` flag to the compiler. This may be used for compile-time
-detection of unexpected conditional compilation name and/or values.
-
-This can only be used in combination with `-Zcheck-cfg` otherwise it is ignored
-with a warning.
-
-If you want to integrate with Cargo features, only use `-Zcheck-cfg` instead of
-trying to do it manually with this option.
-
-You can use the instruction like this:
-
-```rust,no_run
-// build.rs
-println!("cargo::rustc-check-cfg=cfg(foo, bar)");
-```
-
-```
-cargo check -Z unstable-options -Z check-cfg
-```
-
 ## codegen-backend
 
 The `codegen-backend` feature makes it possible to select the codegen backend used by rustc using a profile.
@@ -1771,3 +1732,11 @@ The `-Z registry-auth` feature has been stabilized in the 1.74 release with the
 requirement that a credential-provider is configured.
 
 See [Registry Authentication](registry-authentication.md) documentation for details.
+
+## check-cfg
+
+The `-Z check-cfg` feature has been stabilized in the CURRENT_CARGO_RELEASE release by
+making it the default behavior.
+
+See the [build script documentation](build-scripts.md#rustc-check-cfg) for informations
+about specifying custom cfgs.