From 36110147229f49024187df6b17175dd5810a26bc Mon Sep 17 00:00:00 2001 From: Urgau Date: Fri, 22 Dec 2023 19:25:15 +0100 Subject: [PATCH] Rework and improve unstable documentation of check-cfg --- .../src/compiler-flags/check-cfg.md | 234 ++++++++++-------- 1 file changed, 128 insertions(+), 106 deletions(-) diff --git a/src/doc/unstable-book/src/compiler-flags/check-cfg.md b/src/doc/unstable-book/src/compiler-flags/check-cfg.md index 8ab6e83d99e..e8fc2fe986e 100644 --- a/src/doc/unstable-book/src/compiler-flags/check-cfg.md +++ b/src/doc/unstable-book/src/compiler-flags/check-cfg.md @@ -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 -check them. The `--check-cfg` option takes a value, called the _check cfg specification_. The -check cfg specification is parsed using the Rust metadata syntax, just as the `--cfg` option is. +check them. The `--check-cfg` option takes a value, called the _check cfg specification_. +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. - -NOTE: No implicit expectation is added when using `--cfg` for both forms. Users are expected to -pass all expected names and values using `cfg(...)`. +*No implicit expectation is added when using `--cfg`. Users are expected to +pass all expected names and values using the _check cfg specification_.* ## The `cfg(...)` form @@ -23,7 +21,7 @@ The `cfg(...)` form enables checking the values within list-valued conditions. I basic form: ```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 @@ -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")]` 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 -list of expected values. If `"value"` is not in it, then `rustc` will report an `unexpected_cfgs` -lint diagnostic. The default diagnostic level for this lint is `Warn`. +attribute and `cfg!(name = "value")` macro call. It will check that the `"value"` specified is +present in the list of expected values. If `"value"` is not in it, then `rustc` will report an +`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 future. +*The command line `--cfg` arguments are currently *NOT* checked but may very well be checked in +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 -rustc --check-cfg 'cfg(name1, ..., nameN)' -rustc --check-cfg 'cfg(name1, ..., nameN, values())' +rustc --check-cfg 'cfg(name)' +rustc --check-cfg 'cfg(name, values())' ``` To enable checking of name but not values (i.e. unknown expected values), use this form: ```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 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 `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. -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 -**unless** any `cfg(any())` argument is passed. +As of `2024-01-09T`, the list of known names is as follows: -To disable checking of well known names, use this form: + -```bash -rustc --check-cfg 'cfg(any())' -``` + - `debug_assertions` + - `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 -can use an empty `cfg()` argument. +Like with `values(any())`, well known names checking can be disabled by passing `cfg(any())` +as argument to `--check-cfg`. ## 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: ```bash rustc --check-cfg 'cfg(feature, values("lion", "zebra"))' \ - --cfg 'feature="lion"' -Z unstable-options \ - example.rs + --cfg 'feature="lion"' -Z unstable-options example.rs ``` 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 -values are enabled by default. Consider compiling this code: +feature is enabled, while the `zebra` feature is disabled. +Given the `--check-cfg` arguments, exhaustive checking of names and +values are enabled. +`example.rs`: ```rust -// This is expected, and tame_lion() will be compiled -#[cfg(feature = "lion")] +#[cfg(feature = "lion")] // This condition is expected, as "lion" is an expected value of `feature` fn tame_lion(lion: Lion) {} -// This is expected, and ride_zebra() will NOT be compiled. -#[cfg(feature = "zebra")] -fn ride_zebra(zebra: Zebra) {} +#[cfg(feature = "zebra")] // This condition is expected, as "zebra" is an expected value of `feature` + // but the condition will still evaluate to false + // 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")] +#[cfg(feature = "platypus")] // This condition is UNEXPECTED, as "platypus" is NOT an expected value of + // `feature` and will cause a compiler warning (by default). fn poke_platypus() {} -// This is UNEXPECTED, because 'feechure' is not a known condition name, -// and will cause a compiler warning (by default). -#[cfg(feechure = "lion")] +#[cfg(feechure = "lion")] // This condition is UNEXPECTED, as 'feechure' is NOT a expected condition + // name, no `cfg(feechure, ...)` was passed in `--check-cfg` fn tame_lion() {} -// This is UNEXPECTED, because 'windows' is a well known condition name, -// and because 'windows' doesn't take any values, -// and will cause a compiler warning (by default). -#[cfg(windows = "unix")] +#[cfg(windows = "unix")] // This condition is UNEXPECTED, as while 'windows' is a well known + // condition name, it doens't expect any values fn tame_windows() {} ``` -### Example: Checking condition names, but not values +### Example: Multiple names and values ```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)' \ --check-cfg 'cfg(feature, values("zapping", "lasers"))' \ --cfg has_feathers --cfg 'feature="zapping"' -Z unstable-options ``` ```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 -#[cfg(has_feathers)] // This is expected because "has_feathers" was provided in cfg() -fn do_features() {} // and deosn't take any value +#[cfg(has_feathers)] // This condition is expected, as 'has_feathers' was provided in --check-cfg +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() {} -#[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() {} -#[cfg(feature = "monkeys")] // This is UNEXPECTED, because "monkeys" is not in - // the cfg(feature) list +#[cfg(feature = "monkeys")] // This condition is UNEXPECTED, as "monkeys" is NOT an expected value of + // `feature` 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() {} +```