Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(ref): Simplify check-cfg build.rs docs #13937

Merged
merged 6 commits into from
May 20, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 10 additions & 20 deletions src/doc/src/reference/build-scripts.md
weihanglo marked this conversation as resolved.
Show resolved Hide resolved
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