Tracking Issue for rustc `--check-cfg` integration

[weihanglo]

Summary

RFC: #3013
rustc tracking issue: rust-lang/rust#82450

Documentation:

• https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#check-cfg
• https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#cargorustc-check-cfgcheck_cfg

This tracks the integration of rustc --check-cfg flag (RFC #3013), which enables complete or partial checking of conditional compilation configuration at compile time.

Unresolved Issues

• Should these flags be enabled by default? What's the unintrusive interface to provide for users to opt-out the checking?
• If we feel the diagnostic on using a feature when no features are defined is insufficient, then do we feel it would not be incongruous with the design to fix this in the future? (see Fix --check-cfg invocations with zero features #13011).

Post-RFC decisions

• Support cargo:rustc-check-cfg despite :: being introduced in 1.77 and this being released after that. This was done to allow for wider MSRVs while using this feature

Future Extensions

No response

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Implementation history:

• Add -Z check-cfg-features to enable compile-time checking of features #10408
• Add -Z check-cfg-features support for rustdoc #10428
• Add support for rustc --check-cfg well known names and values #10486
• Improve support of condition compilation checking  #10566
• Add unstable rustc-check-cfg build script output #10539
• Adjust -Zcheck-cfg for new rustc syntax and behavior #12845
• Remove outdated option to -Zcheck-cfg warnings #12884
• Fix --check-cfg invocations with zero features #13011
• Include declared list of features in fingerprint for -Zcheck-cfg #13012
• Go back to passing an empty values() when no features are declared #13316

[est31]

Over in rust-lang/rust#93628 I've discovered two things:

• First, a papercut: apparently there are empty values() calls when the feature is enabled, even if there is another values(...) call with content present already. In that case, values() is not needed, right?
• Second, due to There is no way to set RUSTFLAGS for build scripts (or proc macros) when cross-compiling #4423 specifying custom --check-cfg inside RUSTFLAGS does not reach all of cargo's units, as in, there is no way to specify custom flags for the host units. Apparently it's still an open question how one should enable people to specify custom possible cfg names, but the way bootstrap does it via RUSTFLAGS is IMO not enough to get --check-cfg stabilized. Even if a user-friendly way via toml editing exists, ideally there would also be a way that can be set programmatically via some kind of environment variable. edit: resolved, see Tracking Issue for rustc --check-cfg integration #10554 (comment)

[Urgau]

* First, a papercut: apparently there are empty `values()` calls when the feature is enabled, even if there is another `values(...)` call with content present already. In that case, `values()` is not needed, right?

You're mixing things, bootstrap (the tool that build rustc, rustdoc, ...) use cargo -Zcheck-cfg=names,values,features to enable:

• well known names: --check-cfg=names()
• well known values: --check-cfg=values()
• well known features: --check-cfg=values(feature, ...)

And then use RUSTFLAGS to set extra check cfg (most of them will go any when cargo beta has support for rustc-check-cfg in build script). Cargo is not involved at all in this process so if there are duplicates, nothing can be done. This explain what you see.

Concerning empty values() the unstable book as a section about it check-cfg values:
     If values() is specified, then rustc will enable the checking of well-known values defined by itself. Note that it's necessary to specify the values() form to enable the checking of well known values, specifying the other forms doesn't implicitly enable it.

Btw, this should have been posted on the rust-lang/rust Tracking Issue for RFC 3013: Checking conditional compilation at compile time.

* Second, due to [There is no way to set RUSTFLAGS for build scripts when cross-compiling #4423](https://github.com/rust-lang/cargo/issues/4423) specifying custom `--check-cfg` inside `RUSTFLAGS` does not reach all of cargo's units, as in, there is no way to specify custom flags for the host units. Apparently it's [still an open question](https://github.com/rust-lang/rust/issues/82450#issuecomment-1046819607) how one should enable people to specify custom possible cfg names, but the way bootstrap does it via `RUSTFLAGS` is IMO not enough to get `--check-cfg` stabilized. Even if a user-friendly way via toml editing exists, ideally there would also be a way that can be set programmatically via some kind of environment variable.

Why would this be a concern for stabilization ? I don't think it's that big of a deal, bootstrap and the rust-lang/rust codebase is very special, the vast majority of project who would use check-cfg (which is less probably than 1%) would simply add rustc-check-cfg to their build script or in their Cargo.toml. I don't think anyone would use RUSTFLAGS for this.

Nevertheless I agree that I would be great if there was a way to forward RUSTFLAGS to proc-macro when --target is specified.

[est31]

Concerning empty values() the unstable book as a section about it check-cfg values:

Oh I see, that's a weird choice that IMO violates the least surprise principle. I've thought that this was some genuine bug of cargo's integration of --check-cfg. I guess how that feature can be improved is indeed discussed in the rustc tracking issue. But it's a papercut, shrug.

the vast majority of project who would use check-cfg (which is less probably than 1%) would simply add rustc-check-cfg to their build script or in their Cargo.toml. I don't think anyone would use RUSTFLAGS for this.

My original reasoning was that there is a use case of wanting to enable some feature that needs different code across a code base. You can sort of do that with per-cargo-package features but they are not convenient to use when you have deep dependency hierarchies. So some projects like the rust compiler opt to use RUSTFLAGS instead. I don't think it's something exclusive to the compiler, others might do it similarly. I think the blocker is for some mechanism for multi crate projects to share the list of available cfgs.

Edit: with your general argument over in rust-lang/rust#93628 (comment) that cfgs specified in RUSTFLAGS don't reach crates either, I think you are right that it's not useful. The rust compiler's bootstrap was running into the issue because it went out of its way to specify the bootstrap cfg for proc macros as well. So I think my second concern is resolved now.

[illicitonion]

I recently released an update to a reasonably popular crate (thousands of reverse dependencies, 10M downloads) which had a significantly behaviour regression, and caused noticeable ecosystem breakage (including a spurious report of nightly being broken).

We had tests for the regression, but they were never getting run because they were hidden behind a feature, and there was a typo in the cfg(feature) attribute, meaning we weren't actually running those tests in CI.

I just tested out this feature for our example breakage, and it would have prevented us from releasing that broken code. I'd love to see it stabilise! The only modification I'd suggest is defaulting to deny rather than warn.