mirror of
https://github.com/rust-lang/cargo
synced 2024-10-30 03:28:38 +00:00
Auto merge of #13937 - epage:docs, r=weihanglo
docs(ref): Simplify check-cfg build.rs docs ### What does this PR try to resolve? After looking over the rust documentation updates, decided to look over Cargo's build.rs documentation. - Removed link to the blog post as that is not evergreen documentation - Collapsed down the example to put more emphasis on the more complete example ### How should we test and review this PR? ### Additional information
This commit is contained in:
commit
ef60a454f1
1 changed files with 13 additions and 23 deletions
|
@ -258,32 +258,16 @@ identifier, the value should be a string.
|
|||
|
||||
### `cargo::rustc-check-cfg=CHECK_CFG` {#rustc-check-cfg}
|
||||
|
||||
*See the announcement [blog post][check-cfg-blog-post] for more a global view of the feature.*
|
||||
|
||||
Add to the list of expected config names and values that is used when checking
|
||||
the _reachable_ cfg expressions.
|
||||
the _reachable_ cfg expressions with the [`unexpected_cfgs`][unexpected-cfgs] lint.
|
||||
|
||||
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 syntax of `CHECK_CFG` mirrors the `rustc` [`--check-cfg` flag][option-check-cfg], see
|
||||
[Checking conditional configurations][checking-conditional-configurations] for more details.
|
||||
|
||||
> Note: `cargo:rustc-check-cfg` (single-colon) can be used if your MSRV is below Rust 1.77
|
||||
|
||||
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\"))");
|
||||
|
@ -292,12 +276,18 @@ if foo_bar_condition {
|
|||
}
|
||||
```
|
||||
|
||||
For a more complete example see in the [build script examples][build-script-examples] page
|
||||
the [conditional compilation][conditional-compilation-example] example.
|
||||
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.
|
||||
|
||||
[check-cfg-blog-post]: https://blog.rust-lang.org/2024/05/06/check-cfg.html
|
||||
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, stale cfgs...
|
||||
|
||||
See also the
|
||||
[conditional compilation][conditional-compilation-example] example.
|
||||
|
||||
[checking-conditional-configurations]: ../../rustc/check-cfg.html
|
||||
[option-check-cfg]: ../../rustc/command-line-arguments.md#option-check-cfg
|
||||
[build-script-examples]: build-script-examples.md
|
||||
[conditional-compilation-example]: build-script-examples.md#conditional-compilation
|
||||
|
||||
### `cargo::rustc-env=VAR=VALUE` {#rustc-env}
|
||||
|
|
Loading…
Reference in a new issue