Skip to content

Commit

Permalink
Auto merge of #13937 - epage:docs, r=weihanglo
Browse files Browse the repository at this point in the history
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
  • Loading branch information
bors committed May 20, 2024
2 parents 2332d7a + a0fb4ac commit ef60a45
Showing 1 changed file with 10 additions and 20 deletions.
30 changes: 10 additions & 20 deletions src/doc/src/reference/build-scripts.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,13 +258,11 @@ 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
Expand All @@ -273,31 +271,23 @@ The instruction can be used like this:
```rust,no_run
// build.rs
println!("cargo::rustc-check-cfg=cfg(foo, values(\"bar\"))");
if foo_bar_condition {
println!("cargo::rustc-cfg=foo=\"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\"");
}
```
avoid typos, missing check-cfg, stale cfgs...

For a more complete example see in the [build script examples][build-script-examples] page
the [conditional compilation][conditional-compilation-example] example.
See also the
[conditional compilation][conditional-compilation-example] example.

[check-cfg-blog-post]: https://blog.rust-lang.org/2024/05/06/check-cfg.html
[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}
Expand Down

0 comments on commit ef60a45

Please sign in to comment.