From c56052902562be75d8090869207f60dd6a66e311 Mon Sep 17 00:00:00 2001 From: Urgau Date: Wed, 17 Apr 2024 07:58:15 +0200 Subject: [PATCH 01/13] Announce automatic checking of cfgs at compile-time --- posts/2024-04-29-check-cfg.md | 115 ++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 posts/2024-04-29-check-cfg.md diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-04-29-check-cfg.md new file mode 100644 index 000000000..585df7458 --- /dev/null +++ b/posts/2024-04-29-check-cfg.md @@ -0,0 +1,115 @@ +--- +layout: post +title: "Automatic checking of cfgs at compile-time" +author: Urgau +team: The Cargo Team +--- + +# Automatic checking of cfgs at compile-time + +The Cargo and Compiler team are delighted to announce that starting with Rust 1.80 (or nightly-2024-04-XX) every _reachable_ `#[cfg]`s will be automatically checked for expected config names and values. + +This can help with verifying that the crate is correctly handling conditional compilation for different target platforms or features. It ensures that the cfg settings are consistent between what is intended and what is used, helping to catch potential bugs or errors early in the development process. + +Addressing a common pitfall for new and advanced users. + +This is another step to our commitment to provide user-focused tooling and we are eager and excited to finally see it fixed, more than two years since the original [RFC 3013](https://github.com/rust-lang/rfcs/pull/3013)[^1]. + +[^1]: The stabilized implementation and RFC 3013 diverge significantly, in particular there is only one form for `--check-cfg`: `cfg()` (instead of `values()` and `names()` being incomplete and subtlety incompatible with each other). + +## A look at the feature + +Every time a Cargo feature is declared that feature is transformed into a config that is passed to `rustc` (the Rust compiler) so it can verify with its [well known cfgs](TODO) if any of the `#[cfg]`, `#![cfg_attr]` and `cfg!` have unexpected configs and report a warning with the `unexpected_cfgs` lint. + +*`Cargo.toml`*: + +```toml +[package] +name = "foo" + +[features] +lasers = [] +zapping = [] +``` + +*`src/lib.rs`:* +```rust +#[cfg(feature = "lasers")] // This condition is expected + // as "lasers" is an expected value of `feature` +fn shoot_lasers() {} + +#[cfg(feature = "monkeys")] // This condition is UNEXPECTED + // as "monkeys" is NOT an expected value of `feature` +fn write_shakespeare() {} + +#[cfg(windosw)] // This condition is UNEXPECTED + // it's supposed to be `windows` +fn win() {} +``` + +*`cargo check`*: +![cargo-check](https://github.com/rust-lang/rust/assets/3616612/c6ecdb34-b92c-42b8-9f80-7066b76541ff) + +## Custom cfgs and build scripts + +> In Cargo point-of-view: a custom cfg is one that is neither defined by `rustc` nor by a Cargo feature. Think of `tokio_unstable`, `has_foo`, ... but not `feature = "lasers"`, `unix`, ... + +Some crates use custom cfgs that they either expected from the environment (`RUSTFLAGS`or other means) or is enabled by some logic in the crate `build.rs`. For those crates Cargo provides a new instruction: [`cargo::rustc-check-cfg`](TODO)[^2] (or `cargo:rustc-check-cfg` for older Cargo version). + +[^2]: `cargo::rustc-check-cfg` take action since Rust 1.80, between Rust 1.77 and Rust 1.79 *(included)* it silently did nothing and before that (so Rust 1.76 and below) it warned when used without the unstable Cargo `-Zcheck-cfg`. + +The syntax to use is described in the [rustc book](https://doc.rust-lang.org/rustc/index.html) section [checking configuration](TODO), but in a nut shell the basic syntax of `--check-cfg` is: + +> `cfg(name, values("value1", "value2", ..., "valueN"))` + +Note that every custom cfgs must always be expected, regardless if the cfg is active or not! + +### `build.rs` example + +`build.rs`: +```rust +fn main() { + println!("cargo::rustc-check-cfg=cfg(has_foo)"); // <-- new with Cargo 1.80 + if has_foo() { + println!("cargo::rustc-cfg=has_foo"); + } +} +``` + +> Note: Each `cargo::rustc-cfg` must always have a accompanying _unconditional_ `cargo::rustc-check-cfg` directive otherwise you risk having warnings like this:`unexpected cfg condition name: has_foo`. + +### Equivalence table + +| `cargo::rustc-cfg` | `cargo::rustc-check-cfg` | +|-------------------------|------------------------------------------------| +| `foo` | `cfg(foo)` or `cfg(foo, values(none()))` | +| `foo=""` | `cfg(foo, values(""))` | +| `foo="bar"` | `cfg(foo, values("bar"))` | +| `foo="1"` and `foo="2"` | `cfg(foo, values("1", "2"))` | +| `foo="1"` and `bar="2"` | `cfg(foo, values("1"))` and `cfg(bar, values("2"))` | +| `foo` and `foo="bar"` | `cfg(foo, values(none(), "bar"))` | + +More details can be found on the [`rustc` book](TODO). + +## Frequently asked questions + +### Can it be disabled? + +No, it's **always on** for Cargo and _cannot_ be disabled. + +### How does it interact with the `RUSTFLAGS` env ? + +You should be able to use the `RUSTFLAGS` environment variable like it was before. +*Currently `--cfg` arguments are not checked, only usage in code are.* + +This means that doing `RUSTFLAGS="--cfg tokio_unstable" cargo check` will not report any warnings, unless `tokio_unstable` is used within your local crates, in which case crate author will need to make sure that that custom cfg is expected with `cargo::rustc-check-cfg` in the `build.rs` of that crate. + +### How to expect custom cfgs without a `build.rs` ? + +There is not **currently no way** to expect a custom cfg other than with `cargo::rustc-check-cfg` in a `build.rs`. + +Crate author that don't want to use a `build.rs` are encouraged to use Cargo features instead. + +### Does it affect dependencies ? + +No, the lint only affects local packages; only those will report the lint. From 3fdb57104bcad76aa87114185f7167ec33ba7552 Mon Sep 17 00:00:00 2001 From: Urgau <3616612+Urgau@users.noreply.github.com> Date: Wed, 17 Apr 2024 10:34:19 +0200 Subject: [PATCH 02/13] Apply some suggestions from programmerjake Co-authored-by: Jacob Lifshay --- posts/2024-04-29-check-cfg.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-04-29-check-cfg.md index 585df7458..7b9141252 100644 --- a/posts/2024-04-29-check-cfg.md +++ b/posts/2024-04-29-check-cfg.md @@ -11,9 +11,9 @@ The Cargo and Compiler team are delighted to announce that starting with Rust 1. This can help with verifying that the crate is correctly handling conditional compilation for different target platforms or features. It ensures that the cfg settings are consistent between what is intended and what is used, helping to catch potential bugs or errors early in the development process. -Addressing a common pitfall for new and advanced users. +This addresses a common pitfall for new and advanced users. -This is another step to our commitment to provide user-focused tooling and we are eager and excited to finally see it fixed, more than two years since the original [RFC 3013](https://github.com/rust-lang/rfcs/pull/3013)[^1]. +This is another step to our commitment to provide user-focused tooling and we are eager and excited to finally see it fixed, after more than two years since the original [RFC 3013](https://github.com/rust-lang/rfcs/pull/3013)[^1]. [^1]: The stabilized implementation and RFC 3013 diverge significantly, in particular there is only one form for `--check-cfg`: `cfg()` (instead of `values()` and `names()` being incomplete and subtlety incompatible with each other). @@ -58,7 +58,7 @@ Some crates use custom cfgs that they either expected from the environment (`RUS [^2]: `cargo::rustc-check-cfg` take action since Rust 1.80, between Rust 1.77 and Rust 1.79 *(included)* it silently did nothing and before that (so Rust 1.76 and below) it warned when used without the unstable Cargo `-Zcheck-cfg`. -The syntax to use is described in the [rustc book](https://doc.rust-lang.org/rustc/index.html) section [checking configuration](TODO), but in a nut shell the basic syntax of `--check-cfg` is: +The syntax to use is described in the [rustc book](https://doc.rust-lang.org/rustc/index.html) section [checking configuration](TODO), but in a nutshell the basic syntax of `--check-cfg` is: > `cfg(name, values("value1", "value2", ..., "valueN"))` From b02d576c9103f20f51217347368be3f708cff943 Mon Sep 17 00:00:00 2001 From: Urgau <3616612+Urgau@users.noreply.github.com> Date: Wed, 17 Apr 2024 16:57:49 +0200 Subject: [PATCH 03/13] Apply second round of suggestions from code review Co-authored-by: Jacob Lifshay --- posts/2024-04-29-check-cfg.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-04-29-check-cfg.md index 7b9141252..05589a07a 100644 --- a/posts/2024-04-29-check-cfg.md +++ b/posts/2024-04-29-check-cfg.md @@ -7,7 +7,7 @@ team: The Cargo Team Date: Thu, 18 Apr 2024 13:29:21 +0200 Subject: [PATCH 04/13] Apply suggestions and update links to rustc book Co-authored-by: Nathan Stocks --- posts/2024-04-29-check-cfg.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-04-29-check-cfg.md index 05589a07a..01f039483 100644 --- a/posts/2024-04-29-check-cfg.md +++ b/posts/2024-04-29-check-cfg.md @@ -19,7 +19,7 @@ This is another step to our commitment to provide user-focused tooling and we ar ## A look at the feature -Every time a Cargo feature is declared that feature is transformed into a config that is passed to `rustc` (the Rust compiler) so it can verify with its [well known cfgs](TODO) if any of the `#[cfg]`, `#![cfg_attr]` and `cfg!` have unexpected configs and report a warning with the `unexpected_cfgs` lint. +Every time a Cargo feature is declared that feature is transformed into a config that is passed to `rustc` (the Rust compiler) so it can verify with its [well known cfgs](https://doc.rust-lang.org/nightly/rustc/check-cfg.html#well-known-names-and-values) if any of the `#[cfg]`, `#![cfg_attr]` and `cfg!` have unexpected configs and report a warning with the `unexpected_cfgs` lint. *`Cargo.toml`*: @@ -56,9 +56,9 @@ fn win() {} Some crates use custom cfgs that they either expected from the environment (`RUSTFLAGS`or other means) or is enabled by some logic in the crate `build.rs`. For those crates Cargo provides a new instruction: [`cargo::rustc-check-cfg`](TODO)[^2] (or `cargo:rustc-check-cfg` for older Cargo version). -[^2]: `cargo::rustc-check-cfg` will start working in Rust 1.80 (or nightly-2024-04-XX), between Rust 1.77 and Rust 1.79 *(included)* it silently did nothing and before that (so Rust 1.76 and below) it warned when used without the unstable Cargo `-Zcheck-cfg`. +[^2]: `cargo::rustc-check-cfg` will start working in Rust 1.80 (or nightly-2024-04-XX). From Rust 1.77 to Rust 1.79 *(inclusive)* it is silently ignored. In Rust 1.76 and below a warning is emitted when used without the unstable Cargo flag `-Zcheck-cfg`. -The syntax to use is described in the [rustc book](https://doc.rust-lang.org/rustc/index.html) section [checking configuration](TODO), but in a nutshell the basic syntax of `--check-cfg` is: +The syntax to use is described in the [rustc book](https://doc.rust-lang.org/nightly/rustc/) section [checking configuration](https://doc.rust-lang.org/nightly/rustc/check-cfg.html), but in a nutshell the basic syntax of `--check-cfg` is: > `cfg(name, values("value1", "value2", ..., "valueN"))` @@ -89,7 +89,7 @@ fn main() { | `foo="1"` and `bar="2"` | `cfg(foo, values("1"))` and `cfg(bar, values("2"))` | | `foo` and `foo="bar"` | `cfg(foo, values(none(), "bar"))` | -More details can be found on the [`rustc` book](TODO). +More details can be found on the [`rustc` book](https://doc.rust-lang.org/nightly/rustc/check-cfg.html). ## Frequently asked questions @@ -108,8 +108,8 @@ This means that doing `RUSTFLAGS="--cfg tokio_unstable" cargo check` will not re There is not **currently no way** to expect a custom cfg other than with `cargo::rustc-check-cfg` in a `build.rs`. -Crate author that don't want to use a `build.rs` are encouraged to use Cargo features instead. +Crate authors that don't want to use a `build.rs` are encouraged to use Cargo features instead. -### Does it affect dependencies ? +### Does the lint affect dependencies? No, the lint only affects local packages; only those will report the lint. From 8375ca81e53f6c342d0d2858afe299c6453c74ba Mon Sep 17 00:00:00 2001 From: Urgau Date: Thu, 18 Apr 2024 19:49:21 +0200 Subject: [PATCH 05/13] Add section for non-Cargo based build systems + fix typos --- posts/2024-04-29-check-cfg.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-04-29-check-cfg.md index 01f039483..3b536ec55 100644 --- a/posts/2024-04-29-check-cfg.md +++ b/posts/2024-04-29-check-cfg.md @@ -97,19 +97,23 @@ More details can be found on the [`rustc` book](https://doc.rust-lang.org/nightl The feature is **always on** and _cannot_ be disabled from Cargo, but like any other lints it can be controlled: `#![allow(unexpected_cfgs)]`. -### How does it interact with the `RUSTFLAGS` env ? +### Does the lint affect dependencies? + +No, the lint only affects local packages; only those will report the lint. + +### How does it interact with the `RUSTFLAGS` env? You should be able to use the `RUSTFLAGS` environment variable like it was before. *Currently `--cfg` arguments are not checked, only usage in code are.* This means that doing `RUSTFLAGS="--cfg tokio_unstable" cargo check` will not report any warnings, unless `tokio_unstable` is used within your local crates, in which case crate author will need to make sure that that custom cfg is expected with `cargo::rustc-check-cfg` in the `build.rs` of that crate. -### How to expect custom cfgs without a `build.rs` ? +### How to expect custom cfgs without a `build.rs`? -There is not **currently no way** to expect a custom cfg other than with `cargo::rustc-check-cfg` in a `build.rs`. +There is **currently no way** to expect a custom cfg other than with `cargo::rustc-check-cfg` in a `build.rs`. Crate authors that don't want to use a `build.rs` are encouraged to use Cargo features instead. - -### Does the lint affect dependencies? -No, the lint only affects local packages; only those will report the lint. +### How does it interact with other build systems? + +Non-Cargo based build systems are not affected by the lint by default. Build system authors that wish to have the same functionality should look at the `rustc` documentation for the [`--check-cfg`](https://doc.rust-lang.org/nightly/rustc/check-cfg.html) flag for a detailed explanation of how to achieve the same functionality. From 6b2803f8d6ca50d3053805372dc1ab837a0e8346 Mon Sep 17 00:00:00 2001 From: Urgau Date: Fri, 19 Apr 2024 19:37:38 +0200 Subject: [PATCH 06/13] Host the SVG on the blog directly instead of a third-party website --- posts/2024-04-29-check-cfg.md | 2 +- .../2024-04-29-check-cfg/cargo-check.svg | 79 +++++++++++++++++++ 2 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 static/images/2024-04-29-check-cfg/cargo-check.svg diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-04-29-check-cfg.md index 3b536ec55..10d47820b 100644 --- a/posts/2024-04-29-check-cfg.md +++ b/posts/2024-04-29-check-cfg.md @@ -48,7 +48,7 @@ fn win() {} ``` *`cargo check`*: -![cargo-check](https://github.com/rust-lang/rust/assets/3616612/c6ecdb34-b92c-42b8-9f80-7066b76541ff) +![cargo-check](../../../../images/2024-04-29-check-cfg/cargo-check.svg) ## Custom cfgs and build scripts diff --git a/static/images/2024-04-29-check-cfg/cargo-check.svg b/static/images/2024-04-29-check-cfg/cargo-check.svg new file mode 100644 index 000000000..e62e98b9e --- /dev/null +++ b/static/images/2024-04-29-check-cfg/cargo-check.svg @@ -0,0 +1,79 @@ + + + + + + + Checking foo v0.0.0 (/tmp/foo) + + warning: unexpected `cfg` condition value: `monkeys` + + --> src/lib.rs:5:7 + + | + + 5 | #[cfg(feature = "monkeys")] + + | ^^^^^^^^^^^^^^^^^^^ + + | + + = note: expected values for `feature` are: `lasers`, `zapping` + + = help: consider adding `monkeys` as a feature in `Cargo.toml` + + = note: see <https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#check-cfg> + + for more information about checking conditional configuration + + = note: `#[warn(unexpected_cfgs)]` on by default + + + + warning: unexpected `cfg` condition name: `windosw` + + --> src/lib.rs:9:7 + + | + + 9 | #[cfg(windosw)] + + | ^^^^^^^ help: there is a config with a similar name: `windows` + + | + + = help: consider using a Cargo feature instead or adding + + `println!("cargo:rustc-check-cfg=cfg(windosw)");` to the top of a `build.rs` + + = note: see <https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#check-cfg> + + for more information about checking conditional configuration + + + + warning: `foo` (lib) generated 2 warnings + + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s + + + + + + From 80c2bb930f24b143a2b2877069660d4bea3da963 Mon Sep 17 00:00:00 2001 From: Urgau Date: Fri, 3 May 2024 21:34:08 +0200 Subject: [PATCH 07/13] Schedule for the 8th of may and populate last remaining links --- ...2024-04-29-check-cfg.md => 2024-05-08-check-cfg.md} | 10 +++++----- .../cargo-check.svg | 0 2 files changed, 5 insertions(+), 5 deletions(-) rename posts/{2024-04-29-check-cfg.md => 2024-05-08-check-cfg.md} (92%) rename static/images/{2024-04-29-check-cfg => 2024-05-08-check-cfg}/cargo-check.svg (100%) diff --git a/posts/2024-04-29-check-cfg.md b/posts/2024-05-08-check-cfg.md similarity index 92% rename from posts/2024-04-29-check-cfg.md rename to posts/2024-05-08-check-cfg.md index 10d47820b..2d13498c0 100644 --- a/posts/2024-04-29-check-cfg.md +++ b/posts/2024-05-08-check-cfg.md @@ -7,7 +7,7 @@ team: The Cargo Team In Cargo point-of-view: a custom cfg is one that is neither defined by `rustc` nor by a Cargo feature. Think of `tokio_unstable`, `has_foo`, ... but not `feature = "lasers"`, `unix`, ... -Some crates use custom cfgs that they either expected from the environment (`RUSTFLAGS`or other means) or is enabled by some logic in the crate `build.rs`. For those crates Cargo provides a new instruction: [`cargo::rustc-check-cfg`](TODO)[^2] (or `cargo:rustc-check-cfg` for older Cargo version). +Some crates use custom cfgs that they either expected from the environment (`RUSTFLAGS`or other means) or is enabled by some logic in the crate `build.rs`. For those crates Cargo provides a new instruction: [`cargo::rustc-check-cfg`](https://doc.rust-lang.org/nightly/cargo/reference/build-scripts.html#rustc-check-cfg)[^2] (or `cargo:rustc-check-cfg` for older Cargo version). -[^2]: `cargo::rustc-check-cfg` will start working in Rust 1.80 (or nightly-2024-04-XX). From Rust 1.77 to Rust 1.79 *(inclusive)* it is silently ignored. In Rust 1.76 and below a warning is emitted when used without the unstable Cargo flag `-Zcheck-cfg`. +[^2]: `cargo::rustc-check-cfg` will start working in Rust 1.80 (or nightly-2024-05-08). From Rust 1.77 to Rust 1.79 *(inclusive)* it is silently ignored. In Rust 1.76 and below a warning is emitted when used without the unstable Cargo flag `-Zcheck-cfg`. The syntax to use is described in the [rustc book](https://doc.rust-lang.org/nightly/rustc/) section [checking configuration](https://doc.rust-lang.org/nightly/rustc/check-cfg.html), but in a nutshell the basic syntax of `--check-cfg` is: @@ -89,7 +89,7 @@ fn main() { | `foo="1"` and `bar="2"` | `cfg(foo, values("1"))` and `cfg(bar, values("2"))` | | `foo` and `foo="bar"` | `cfg(foo, values(none(), "bar"))` | -More details can be found on the [`rustc` book](https://doc.rust-lang.org/nightly/rustc/check-cfg.html). +More details can be found in the [`rustc` book](https://doc.rust-lang.org/nightly/rustc/check-cfg.html). ## Frequently asked questions diff --git a/static/images/2024-04-29-check-cfg/cargo-check.svg b/static/images/2024-05-08-check-cfg/cargo-check.svg similarity index 100% rename from static/images/2024-04-29-check-cfg/cargo-check.svg rename to static/images/2024-05-08-check-cfg/cargo-check.svg From 2682b15f41a6d3fed7f22cd03e97be8d0419b712 Mon Sep 17 00:00:00 2001 From: Urgau Date: Sat, 4 May 2024 16:02:46 +0200 Subject: [PATCH 08/13] Change the schedule to tomorrow (2024-05-05) --- posts/{2024-05-08-check-cfg.md => 2024-05-05-check-cfg.md} | 6 +++--- .../cargo-check.svg | 0 2 files changed, 3 insertions(+), 3 deletions(-) rename posts/{2024-05-08-check-cfg.md => 2024-05-05-check-cfg.md} (96%) rename static/images/{2024-05-08-check-cfg => 2024-05-05-check-cfg}/cargo-check.svg (100%) diff --git a/posts/2024-05-08-check-cfg.md b/posts/2024-05-05-check-cfg.md similarity index 96% rename from posts/2024-05-08-check-cfg.md rename to posts/2024-05-05-check-cfg.md index 2d13498c0..3944e6368 100644 --- a/posts/2024-05-08-check-cfg.md +++ b/posts/2024-05-05-check-cfg.md @@ -7,7 +7,7 @@ team: The Cargo Team Date: Sat, 4 May 2024 16:31:19 +0200 Subject: [PATCH 09/13] Stylist nitpicks --- posts/2024-05-05-check-cfg.md | 25 +++++++++++-------- .../2024-05-05-check-cfg/cargo-check.svg | 10 ++++---- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/posts/2024-05-05-check-cfg.md b/posts/2024-05-05-check-cfg.md index 3944e6368..cb5ef2789 100644 --- a/posts/2024-05-05-check-cfg.md +++ b/posts/2024-05-05-check-cfg.md @@ -5,9 +5,7 @@ author: Urgau team: The Cargo Team --- -# Automatic checking of cfgs at compile-time - -The Cargo and Compiler team are delighted to announce that starting with Rust 1.80 (or nightly-2024-05-05) every _reachable_ `#[cfg]` will be automatically checked that they match the expected config names and values. +The Cargo and Compiler team are delighted to announce that starting with Rust 1.80 (or nightly-2024-05-05) every _reachable_ `#[cfg]` will be **automatically checked** that they match the **expected config names and values**. This can help with verifying that the crate is correctly handling conditional compilation for different target platforms or features. It ensures that the cfg settings are consistent between what is intended and what is used, helping to catch potential bugs or errors early in the development process. @@ -33,26 +31,30 @@ zapping = [] ``` *`src/lib.rs`:* + ```rust #[cfg(feature = "lasers")] // This condition is expected - // as "lasers" is an expected value of `feature` + // as "lasers" is an expected value + // of the `feature` cfg fn shoot_lasers() {} #[cfg(feature = "monkeys")] // This condition is UNEXPECTED - // as "monkeys" is NOT an expected value of `feature` + // as "monkeys" is NOT an expected + // value of the `feature` cfg fn write_shakespeare() {} #[cfg(windosw)] // This condition is UNEXPECTED - // it's supposed to be `windows` + // it's supposed to be `windows` fn win() {} ``` *`cargo check`*: + ![cargo-check](../../../../images/2024-05-05-check-cfg/cargo-check.svg) ## Custom cfgs and build scripts -> In Cargo point-of-view: a custom cfg is one that is neither defined by `rustc` nor by a Cargo feature. Think of `tokio_unstable`, `has_foo`, ... but not `feature = "lasers"`, `unix`, ... +> In Cargo point-of-view: a custom cfg is one that is neither defined by `rustc` nor by a Cargo feature. Think of `tokio_unstable`, `has_foo`, ... but not `feature = "lasers"`, `unix` or `debug_assertions` Some crates use custom cfgs that they either expected from the environment (`RUSTFLAGS`or other means) or is enabled by some logic in the crate `build.rs`. For those crates Cargo provides a new instruction: [`cargo::rustc-check-cfg`](https://doc.rust-lang.org/nightly/cargo/reference/build-scripts.html#rustc-check-cfg)[^2] (or `cargo:rustc-check-cfg` for older Cargo version). @@ -60,7 +62,9 @@ Some crates use custom cfgs that they either expected from the environment (`RUS The syntax to use is described in the [rustc book](https://doc.rust-lang.org/nightly/rustc/) section [checking configuration](https://doc.rust-lang.org/nightly/rustc/check-cfg.html), but in a nutshell the basic syntax of `--check-cfg` is: -> `cfg(name, values("value1", "value2", ..., "valueN"))` +``` +cfg(name, values("value1", "value2", ..., "valueN")) +``` Note that every custom cfgs must always be expected, regardless if the cfg is active or not! @@ -69,7 +73,8 @@ Note that every custom cfgs must always be expected, regardless if the cfg is ac `build.rs`: ```rust fn main() { - println!("cargo::rustc-check-cfg=cfg(has_foo)"); // <-- new with Cargo 1.80 + println!("cargo::rustc-check-cfg=cfg(has_foo)"); + // ^^^^^^^^^^^^^^^^^^^^^^ new with Cargo 1.80 if has_foo() { println!("cargo::rustc-cfg=has_foo"); } @@ -95,7 +100,7 @@ More details can be found in the [`rustc` book](https://doc.rust-lang.org/nightl ### Can it be disabled? -The feature is **always on** and _cannot_ be disabled from Cargo, but like any other lints it can be controlled: `#![allow(unexpected_cfgs)]`. +The feature is **always on** and _cannot_ be disabled from Cargo, but like any other lints it can be controlled: `#![warn(unexpected_cfgs)]`. ### Does the lint affect dependencies? diff --git a/static/images/2024-05-05-check-cfg/cargo-check.svg b/static/images/2024-05-05-check-cfg/cargo-check.svg index e62e98b9e..ec63dcdd5 100644 --- a/static/images/2024-05-05-check-cfg/cargo-check.svg +++ b/static/images/2024-05-05-check-cfg/cargo-check.svg @@ -20,15 +20,15 @@ - Checking foo v0.0.0 (/tmp/foo) + Checking foo v0.0.0 (foo/) warning: unexpected `cfg` condition value: `monkeys` - --> src/lib.rs:5:7 + --> src/lib.rs:6:7 | - 5 | #[cfg(feature = "monkeys")] + 6 | #[cfg(feature = "monkeys")] | ^^^^^^^^^^^^^^^^^^^ @@ -48,11 +48,11 @@ warning: unexpected `cfg` condition name: `windosw` - --> src/lib.rs:9:7 + --> src/lib.rs:11:7 | - 9 | #[cfg(windosw)] + 11| #[cfg(windosw)] | ^^^^^^^ help: there is a config with a similar name: `windows` From 97e7058fd2f1fdf71778173d1ca38f2cccf2caeb Mon Sep 17 00:00:00 2001 From: Urgau Date: Sat, 4 May 2024 17:16:08 +0200 Subject: [PATCH 10/13] Double-column and put unconditional in bold --- posts/2024-05-05-check-cfg.md | 2 +- static/images/2024-05-05-check-cfg/cargo-check.svg | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/posts/2024-05-05-check-cfg.md b/posts/2024-05-05-check-cfg.md index cb5ef2789..898834723 100644 --- a/posts/2024-05-05-check-cfg.md +++ b/posts/2024-05-05-check-cfg.md @@ -81,7 +81,7 @@ fn main() { } ``` -> Note: Each `cargo::rustc-cfg` must always have a accompanying _unconditional_ `cargo::rustc-check-cfg` directive otherwise you risk having warnings like this:`unexpected cfg condition name: has_foo`. +> Each `cargo::rustc-cfg` must always have a accompanying **unconditional** `cargo::rustc-check-cfg` directive otherwise you risk having warnings like this: `unexpected cfg condition name: has_foo`. ### Equivalence table diff --git a/static/images/2024-05-05-check-cfg/cargo-check.svg b/static/images/2024-05-05-check-cfg/cargo-check.svg index ec63dcdd5..c6531e13a 100644 --- a/static/images/2024-05-05-check-cfg/cargo-check.svg +++ b/static/images/2024-05-05-check-cfg/cargo-check.svg @@ -60,7 +60,7 @@ = help: consider using a Cargo feature instead or adding - `println!("cargo:rustc-check-cfg=cfg(windosw)");` to the top of a `build.rs` + `println!("cargo::rustc-check-cfg=cfg(windosw)");` to the top of a `build.rs` = note: see <https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#check-cfg> From 09e360c87cef39474f88a47bdede06ae98e91521 Mon Sep 17 00:00:00 2001 From: Urgau Date: Sun, 5 May 2024 10:11:05 +0200 Subject: [PATCH 11/13] Update SVG with latest diagnostics updates --- static/images/2024-05-05-check-cfg/cargo-check.svg | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/static/images/2024-05-05-check-cfg/cargo-check.svg b/static/images/2024-05-05-check-cfg/cargo-check.svg index c6531e13a..889afeabf 100644 --- a/static/images/2024-05-05-check-cfg/cargo-check.svg +++ b/static/images/2024-05-05-check-cfg/cargo-check.svg @@ -1,4 +1,4 @@ - + = help: consider adding `monkeys` as a feature in `Cargo.toml` - = note: see <https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#check-cfg> + = note: see <https://doc.rust-lang.org/nightly/cargo/reference/build-scripts.html - for more information about checking conditional configuration + #rustc-check-cfg> for more information about checking conditional configuration = note: `#[warn(unexpected_cfgs)]` on by default @@ -60,11 +60,11 @@ = help: consider using a Cargo feature instead or adding - `println!("cargo::rustc-check-cfg=cfg(windosw)");` to the top of a `build.rs` + `println!("cargo::rustc-check-cfg=cfg(windosw)");` to the top of the `build.rs` - = note: see <https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#check-cfg> + = note: see <https://doc.rust-lang.org/nightly/cargo/reference/build-scripts.html - for more information about checking conditional configuration + #rustc-check-cfg> for more information about checking conditional configuration From 1337eada48b6bb7fae7601e07a62856ab55fad56 Mon Sep 17 00:00:00 2001 From: Urgau Date: Mon, 6 May 2024 00:26:33 +0200 Subject: [PATCH 12/13] Changed publication date to 2024-05-06 --- posts/{2024-05-05-check-cfg.md => 2024-05-06-check-cfg.md} | 2 +- .../cargo-check.svg | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename posts/{2024-05-05-check-cfg.md => 2024-05-06-check-cfg.md} (98%) rename static/images/{2024-05-05-check-cfg => 2024-05-06-check-cfg}/cargo-check.svg (100%) diff --git a/posts/2024-05-05-check-cfg.md b/posts/2024-05-06-check-cfg.md similarity index 98% rename from posts/2024-05-05-check-cfg.md rename to posts/2024-05-06-check-cfg.md index 898834723..45d98842f 100644 --- a/posts/2024-05-05-check-cfg.md +++ b/posts/2024-05-06-check-cfg.md @@ -50,7 +50,7 @@ fn win() {} *`cargo check`*: -![cargo-check](../../../../images/2024-05-05-check-cfg/cargo-check.svg) +![cargo-check](../../../../images/2024-05-06-check-cfg/cargo-check.svg) ## Custom cfgs and build scripts diff --git a/static/images/2024-05-05-check-cfg/cargo-check.svg b/static/images/2024-05-06-check-cfg/cargo-check.svg similarity index 100% rename from static/images/2024-05-05-check-cfg/cargo-check.svg rename to static/images/2024-05-06-check-cfg/cargo-check.svg From e65e0ad02640e3afdc073aca5688e0613ef584c9 Mon Sep 17 00:00:00 2001 From: Urgau <3616612+Urgau@users.noreply.github.com> Date: Mon, 6 May 2024 07:47:40 +0200 Subject: [PATCH 13/13] Apply suggestions from epage Co-authored-by: Ed Page --- posts/2024-05-06-check-cfg.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/posts/2024-05-06-check-cfg.md b/posts/2024-05-06-check-cfg.md index 45d98842f..b1f4535eb 100644 --- a/posts/2024-05-06-check-cfg.md +++ b/posts/2024-05-06-check-cfg.md @@ -17,7 +17,7 @@ This is another step to our commitment to provide user-focused tooling and we ar ## A look at the feature -Every time a Cargo feature is declared that feature is transformed into a config that is passed to `rustc` (the Rust compiler) so it can verify with its [well known cfgs](https://doc.rust-lang.org/nightly/rustc/check-cfg.html#well-known-names-and-values) if any of the `#[cfg]`, `#![cfg_attr]` and `cfg!` have unexpected configs and report a warning with the `unexpected_cfgs` lint. +Every time a Cargo feature is declared that feature is transformed into a config that is passed to `rustc` (the Rust compiler) so it can verify with it along with [well known cfgs](https://doc.rust-lang.org/nightly/rustc/check-cfg.html#well-known-names-and-values) if any of the `#[cfg]`, `#![cfg_attr]` and `cfg!` have unexpected configs and report a warning with the `unexpected_cfgs` lint. *`Cargo.toml`*: @@ -81,7 +81,7 @@ fn main() { } ``` -> Each `cargo::rustc-cfg` must always have a accompanying **unconditional** `cargo::rustc-check-cfg` directive otherwise you risk having warnings like this: `unexpected cfg condition name: has_foo`. +> Each `cargo::rustc-cfg` should have an accompanying **unconditional** `cargo::rustc-check-cfg` directive to avoid warnings like this: `unexpected cfg condition name: has_foo`. ### Equivalence table @@ -100,11 +100,11 @@ More details can be found in the [`rustc` book](https://doc.rust-lang.org/nightl ### Can it be disabled? -The feature is **always on** and _cannot_ be disabled from Cargo, but like any other lints it can be controlled: `#![warn(unexpected_cfgs)]`. +For Cargo users, the feature is **always on** and _cannot_ be disabled, but like any other lints it can be controlled: `#![warn(unexpected_cfgs)]`. ### Does the lint affect dependencies? -No, the lint only affects local packages; only those will report the lint. +No, like most lints, `unexpected_cfgs` will only be reported for local packages thanks to [cap-lints](https://doc.rust-lang.org/rustc/lints/levels.html#capping-lints). ### How does it interact with the `RUSTFLAGS` env?