mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rework and improve unstable documentation of check-cfg

Browse Source
This commit is contained in:
Urgau 2023-12-22 19:25:15 +01:00
parent 2a3e63551f
commit 3611014722
1 changed files with 128 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
src/doc/unstable-book/src/compiler-flags/check-cfg.md
View File

@ -4,18 +4,16 @@ The tracking issue for this feature is: [#82450](https://github.com/rust-lang/ru
------------------------ ------------------------
This feature allows you to enable complete or partial checking of configuration. This feature enables checking of conditional configuration.
`rustc` accepts the `--check-cfg` option, which specifies whether to check conditions and how to `rustc` accepts the `--check-cfg` option, which specifies whether to check conditions and how to
check them. The `--check-cfg` option takes a value, called the _check cfg specification_. The check them. The `--check-cfg` option takes a value, called the _check cfg specification_.
check cfg specification is parsed using the Rust metadata syntax, just as the `--cfg` option is. This specification has one form:
`--check-cfg` option take one form: 1. `--check-cfg cfg(...)` mark a configuration and it's expected values as expected.
1. `--check-cfg cfg(...)` enables checking the values within list-valued conditions. *No implicit expectation is added when using `--cfg`. Users are expected to
pass all expected names and values using the _check cfg specification_.*
NOTE: No implicit expectation is added when using `--cfg` for both forms. Users are expected to
pass all expected names and values using `cfg(...)`.
## The `cfg(...)` form ## The `cfg(...)` form
@ -23,7 +21,7 @@ The `cfg(...)` form enables checking the values within list-valued conditions. I
basic form: basic form:
```bash ```bash
rustc --check-cfg 'cfg(name1, ..., nameN, values("value1", "value2", ... "valueN"))' rustc --check-cfg 'cfg(name, values("value1", "value2", ... "valueN"))'
``` ```
where `name` is a bare identifier (has no quotes) and each `"value"` term is a quoted literal where `name` is a bare identifier (has no quotes) and each `"value"` term is a quoted literal
@ -31,162 +29,186 @@ string. `name` specifies the name of the condition, such as `feature` or `my_cfg
When the `cfg(...)` option is specified, `rustc` will check every `#[cfg(name = "value")]` When the `cfg(...)` option is specified, `rustc` will check every `#[cfg(name = "value")]`
attribute, `#[cfg_attr(name = "value")]` attribute, `#[link(name = "a", cfg(name = "value"))]` attribute, `#[cfg_attr(name = "value")]` attribute, `#[link(name = "a", cfg(name = "value"))]`
and `cfg!(name = "value")` call. It will check that the `"value"` specified is present in the attribute and `cfg!(name = "value")` macro call. It will check that the `"value"` specified is
list of expected values. If `"value"` is not in it, then `rustc` will report an `unexpected_cfgs` present in the list of expected values. If `"value"` is not in it, then `rustc` will report an
lint diagnostic. The default diagnostic level for this lint is `Warn`. `unexpected_cfgs` lint diagnostic. The default diagnostic level for this lint is `Warn`.
The command line `--cfg` arguments are currently *NOT* checked but may very well be checked in *The command line `--cfg` arguments are currently *NOT* checked but may very well be checked in
the future. the future.*
To enable checking of values, but to provide an empty set of expected values, use these forms: To enable checking of values, but to provide an *none*/empty set of expected values
(ie. expect `#[cfg(name)]`), use these forms:
```bash ```bash
rustc --check-cfg 'cfg(name1, ..., nameN)' rustc --check-cfg 'cfg(name)'
rustc --check-cfg 'cfg(name1, ..., nameN, values())' rustc --check-cfg 'cfg(name, values())'
``` ```
To enable checking of name but not values (i.e. unknown expected values), use this form: To enable checking of name but not values (i.e. unknown expected values), use this form:
```bash ```bash
rustc --check-cfg 'cfg(name1, ..., nameN, values(any()))' rustc --check-cfg 'cfg(name, values(any()))'
```
To avoid repeating the same set of values, use this form:
```bash
rustc --check-cfg 'cfg(name1, ..., nameN, values("value1", "value2", ... "valueN"))'
``` ```
The `--check-cfg cfg(...)` option can be repeated, both for the same condition name and for The `--check-cfg cfg(...)` option can be repeated, both for the same condition name and for
different names. If it is repeated for the same condition name, then the sets of values for that different names. If it is repeated for the same condition name, then the sets of values for that
condition are merged together (presedence is given to `any()`). condition are merged together (precedence is given to `values(any())`).
## Well known names and values ## Well known names and values
`rustc` has a internal list of well known names and their corresponding values. `rustc` has a internal list of well known names and their corresponding values.
Those well known names and values follows the same stability as what they refer to. Those well known names and values follows the same stability as what they refer to.
Well known values checking is always enabled as long as a `--check-cfg` argument is present. Well known names and values checking is always enabled as long as at least one
`--check-cfg` argument is present.
Well known names checking is always enable as long as a `--check-cfg` argument is present As of `2024-01-09T`, the list of known names is as follows:
**unless** any `cfg(any())` argument is passed.
To disable checking of well known names, use this form: <!--- See CheckCfg::fill_well_known in compiler/rustc_session/src/config.rs -->
```bash - `debug_assertions`
rustc --check-cfg 'cfg(any())' - `doc`
``` - `doctest`
- `miri`
- `overflow_checks`
- `panic`
- `proc_macro`
- `relocation_model`
- `sanitize`
- `sanitizer_cfi_generalize_pointers`
- `sanitizer_cfi_normalize_integers`
- `target_abi`
- `target_arch`
- `target_endian`
- `target_env`
- `target_family`
- `target_feature`
- `target_has_atomic`
- `target_has_atomic_equal_alignment`
- `target_has_atomic_load_store`
- `target_os`
- `target_pointer_width`
- `target_thread_local`
- `target_vendor`
- `test`
- `unix`
- `windows`
NOTE: If one want to enable values and names checking without having any cfg to declare, one Like with `values(any())`, well known names checking can be disabled by passing `cfg(any())`
can use an empty `cfg()` argument. as argument to `--check-cfg`.
## Examples ## Examples
### Equivalence table
This table describe the equivalence of a `--cfg` argument to a `--check-cfg` argument.
| `--cfg` | `--check-cfg` |
|-----------------------------|----------------------------------------------------------|
| *nothing* | *nothing* or `--check-cfg=cfg()` (to enable the checking) |
| `--cfg foo` | `--check-cfg=cfg(foo) or --check-cfg=cfg(foo, values())` |
| `--cfg foo=""` | `--check-cfg=cfg(foo, values(""))` |
| `--cfg foo="bar"` | `--check-cfg=cfg(foo, values("bar"))` |
| `--cfg foo="1" --cfg foo="2"` | `--check-cfg=cfg(foo, values("1", "2"))` |
| `--cfg foo="1" --cfg bar="2"` | `--check-cfg=cfg(foo, values("1")) --check-cfg=cfg(bar, values("2"))` |
| `--cfg foo --cfg foo="bar"` | `--check-cfg=cfg(foo) --check-cfg=cfg(foo, values("bar"))` |
NOTE: There is (currently) no way to express that a condition name is expected but no (!= none)
values are expected. Passing an empty `values()` means *(none)* in the sense of `#[cfg(foo)]`
with no value. Users are expected to NOT pass a `--check-cfg` with that condition name.
### Example: Cargo-like `feature` example
Consider this command line: Consider this command line:
```bash ```bash
rustc --check-cfg 'cfg(feature, values("lion", "zebra"))' \ rustc --check-cfg 'cfg(feature, values("lion", "zebra"))' \
--cfg 'feature="lion"' -Z unstable-options \ --cfg 'feature="lion"' -Z unstable-options example.rs
example.rs
``` ```
This command line indicates that this crate has two features: `lion` and `zebra`. The `lion` This command line indicates that this crate has two features: `lion` and `zebra`. The `lion`
feature is enabled, while the `zebra` feature is disabled. Exhaustive checking of names and feature is enabled, while the `zebra` feature is disabled.
values are enabled by default. Consider compiling this code: Given the `--check-cfg` arguments, exhaustive checking of names and
values are enabled.
`example.rs`:
```rust ```rust
// This is expected, and tame_lion() will be compiled #[cfg(feature = "lion")] // This condition is expected, as "lion" is an expected value of `feature`
#[cfg(feature = "lion")]
fn tame_lion(lion: Lion) {} fn tame_lion(lion: Lion) {}
// This is expected, and ride_zebra() will NOT be compiled. #[cfg(feature = "zebra")] // This condition is expected, as "zebra" is an expected value of `feature`
#[cfg(feature = "zebra")] // but the condition will still evaluate to false
fn ride_zebra(zebra: Zebra) {} // since only --cfg feature="lion" was passed
fn ride_zebra(z: Zebra) {}
// This is UNEXPECTED, and will cause a compiler warning (by default). #[cfg(feature = "platypus")] // This condition is UNEXPECTED, as "platypus" is NOT an expected value of
#[cfg(feature = "platypus")] // `feature` and will cause a compiler warning (by default).
fn poke_platypus() {} fn poke_platypus() {}
// This is UNEXPECTED, because 'feechure' is not a known condition name, #[cfg(feechure = "lion")] // This condition is UNEXPECTED, as 'feechure' is NOT a expected condition
// and will cause a compiler warning (by default). // name, no `cfg(feechure, ...)` was passed in `--check-cfg`
#[cfg(feechure = "lion")]
fn tame_lion() {} fn tame_lion() {}
// This is UNEXPECTED, because 'windows' is a well known condition name, #[cfg(windows = "unix")] // This condition is UNEXPECTED, as while 'windows' is a well known
// and because 'windows' doesn't take any values, // condition name, it doens't expect any values
// and will cause a compiler warning (by default).
#[cfg(windows = "unix")]
fn tame_windows() {} fn tame_windows() {}
``` ```
### Example: Checking condition names, but not values ### Example: Multiple names and values
```bash ```bash
# This turns on checking for condition names, but not values, such as 'feature' values.
rustc --check-cfg 'cfg(is_embedded, has_feathers, values(any()))' \
--cfg has_feathers -Z unstable-options
```
```rust
#[cfg(is_embedded)] // This is expected as "is_embedded" was provided in cfg()
fn do_embedded() {} // and because names exhaustiveness was not disabled
#[cfg(has_feathers)] // This is expected as "has_feathers" was provided in cfg()
fn do_features() {} // and because names exhaustiveness was not disabled
#[cfg(has_feathers = "zapping")] // This is expected as "has_feathers" was provided in cfg()
// and because no value checking was enable for "has_feathers"
// no warning is emitted for the value "zapping"
fn do_zapping() {}
#[cfg(has_mumble_frotz)] // This is UNEXPECTED because names checking is enable and
// "has_mumble_frotz" was not provided in cfg()
fn do_mumble_frotz() {}
```
### Example: Checking feature values, but not condition names
```bash
# This turns on checking for feature values, but not for condition names.
rustc --check-cfg 'cfg(feature, values("zapping", "lasers"))' \
--check-cfg 'cfg(any())' \
--cfg 'feature="zapping"' -Z unstable-options
```
```rust
#[cfg(is_embedded)] // This is doesn't raise a warning, because names checking was
// disabled by 'cfg(any())'
fn do_embedded() {}
#[cfg(has_feathers)] // Same as above, 'cfg(any())' was provided so no name
// checking is performed
fn do_features() {}
#[cfg(feature = "lasers")] // This is expected, "lasers" is in the cfg(feature) list
fn shoot_lasers() {}
#[cfg(feature = "monkeys")] // This is UNEXPECTED, because "monkeys" is not in the
// cfg(feature) list
fn write_shakespeare() {}
```
### Example: Checking both condition names and feature values
```bash
# This turns on checking for feature values and for condition names.
rustc --check-cfg 'cfg(is_embedded, has_feathers)' \ rustc --check-cfg 'cfg(is_embedded, has_feathers)' \
--check-cfg 'cfg(feature, values("zapping", "lasers"))' \ --check-cfg 'cfg(feature, values("zapping", "lasers"))' \
--cfg has_feathers --cfg 'feature="zapping"' -Z unstable-options --cfg has_feathers --cfg 'feature="zapping"' -Z unstable-options
``` ```
```rust ```rust
#[cfg(is_embedded)] // This is expected because "is_embedded" was provided in cfg() #[cfg(is_embedded)] // This condition is expected, as 'is_embedded' was provided in --check-cfg
fn do_embedded() {} // and doesn't take any value fn do_embedded() {} // and doesn't take any value
#[cfg(has_feathers)] // This is expected because "has_feathers" was provided in cfg() #[cfg(has_feathers)] // This condition is expected, as 'has_feathers' was provided in --check-cfg
fn do_features() {} // and deosn't take any value fn do_features() {} // and doesn't take any value
#[cfg(has_mumble_frotz)] // This is UNEXPECTED, because "has_mumble_frotz" was never provided #[cfg(has_mumble_frotz)] // This condition is UNEXPECTED, as 'has_mumble_frotz' was NEVER provided
// in any --check-cfg arguments
fn do_mumble_frotz() {} fn do_mumble_frotz() {}
#[cfg(feature = "lasers")] // This is expected, "lasers" is in the cfg(feature) list #[cfg(feature = "lasers")] // This condition is expected, as "lasers" is an expected value of `feature`
fn shoot_lasers() {} fn shoot_lasers() {}
#[cfg(feature = "monkeys")] // This is UNEXPECTED, because "monkeys" is not in #[cfg(feature = "monkeys")] // This condition is UNEXPECTED, as "monkeys" is NOT an expected value of
// the cfg(feature) list // `feature`
fn write_shakespeare() {} fn write_shakespeare() {}
``` ```
### Example: Condition names without values
```bash
rustc --check-cfg 'cfg(is_embedded, has_feathers, values(any()))' \
--cfg has_feathers -Z unstable-options
```
```rust
#[cfg(is_embedded)] // This condition is expected, as 'is_embedded' was provided in --check-cfg
// as condition name
fn do_embedded() {}
#[cfg(has_feathers)] // This condition is expected, as "has_feathers" was provided in --check-cfg
// as condition name
fn do_features() {}
#[cfg(has_feathers = "zapping")] // This condition is expected, as "has_feathers" was provided in
// and because *any* values is expected for 'has_feathers' no
// warning is emitted for the value "zapping"
fn do_zapping() {}
#[cfg(has_mumble_frotz)] // This condition is UNEXPECTED, as 'has_mumble_frotz' was not provided
// in any --check-cfg arguments
fn do_mumble_frotz() {}
```