development/cargo
development/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo synced 2024-10-30 03:28:38 +00:00
Code Issues Projects Releases Packages Wiki Activity

Auto merge of #13937 - epage:docs, r=weihanglo

Browse source 
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:
bors 2024-05-20 14:59:24 +00:00
commit ef60a454f1
1 changed files with 13 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
src/doc/src/reference/build-scripts.md
View file

@ -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}