mirror of
https://github.com/rust-lang/cargo
synced 2024-09-13 21:11:44 +00:00
Adjust documentation for newly stabilized -Zcheck-cfg
This commit is contained in:
parent
a5669e8fa3
commit
60a5026885
|
@ -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();
|
||||
|
||||
|
|
|
@ -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}
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in a new issue