From a6a1bd18f8f48829122bed2cf411c4c8111bb75b Mon Sep 17 00:00:00 2001 From: Urgau Date: Sun, 10 Mar 2024 00:00:35 +0100 Subject: [PATCH] Adjust documentation for newly stabilized -Zcheck-cfg --- src/doc/src/reference/build-scripts.md | 45 +++++++++++++++++++++++- src/doc/src/reference/unstable.md | 47 +++++--------------------- 2 files changed, 52 insertions(+), 40 deletions(-) diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index dc74fea95e3a..e5c15afc14cb 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/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... + +
+ + +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-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 diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index e5656b54f7b4..05bec3a6c012 100644 --- a/src/doc/src/reference/unstable.md +++ b/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.