Adjust documentation for newly stabilized -Zcheck-cfg

Author: Urgau

src/doc/src/reference/build-script-examples.md

@@ -456,6 +456,9 @@ values](https://github.com/sfackler/rust-openssl/blob/dc72a8e2c429e46c275e528b61
 ```rust,ignore
 // (portion of build.rs)
 
+println!("cargo::rustc-check-cfg=cfg(ossl101,ossl102)");
+println!("cargo::rustc-check-cfg=cfg(ossl110,ossl110g,ossl111)");
+
 if let Ok(version) = env::var("DEP_OPENSSL_VERSION_NUMBER") {
     let version = u64::from_str_radix(&version, 16).unwrap();
 

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) -- Register custom `cfg`s as
+  expected for 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,10 @@ 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]. Custom cfgs
+must either be expected using the [`cargo::rustc-check-cfg`](#rustc-check-cfg)
+instruction or usage will need to allow the [`unexpected_cfgs`][unexpected-cfgs]
+lint to avoid unexpected cfgs warnings.
 
 Note that this does *not* affect Cargo's dependency resolution. This cannot be
 used to enable an optional dependency, or enable other Cargo features.
@@ -249,6 +254,41 @@ identifier, the value should be a string.
 [cargo features]: features.md
 [conditional compilation]: ../../reference/conditional-compilation.md
 [option-cfg]: ../../rustc/command-line-arguments.md#option-cfg
+[unexpected-cfgs]: ../../rustc/lints/listing/warn-by-default.md#unexpected-cfgs
+
+### `cargo::rustc-check-cfg=CHECK_CFG` {#rustc-check-cfg}
+
+Add to the list of expected config names and values that is used when checking
+the _reachable_ cfg expressions.
+
+For details on the syntax of `CHECK_CFG`, see `rustc` [`--check-cfg` flag][option-check-cfg].
+See also the [`unexpected_cfgs`][unexpected-cfgs] lint.
+
+The instruction can be used 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...
+
+#### Example of using `cargo::rustc-check-cfg` and `cargo::rustc-cfg` together
+
+```rust,no_run
+// build.rs
+println!("cargo::rustc-check-cfg=cfg(foo, values(\"bar\"))");
+if foo_bar_condition {
+    println!("cargo::rustc-cfg=foo=\"bar\"");
+}
+```
+
+[option-check-cfg]: ../../rustc/command-line-arguments.md#option-check-cfg
 
 ### `cargo::rustc-env=VAR=VALUE` {#rustc-env}
 

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.
@@ -1154,44 +1153,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.
@@ -1798,3 +1759,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 1.80 release by making it the
+default behavior.
+
+See the [build script documentation](build-scripts.md#rustc-check-cfg) for informations
+about specifying custom cfgs.