Stabilize #[cfg(version(...))]

[est31]

Stabilization report

This proposes the stabilization of cfg_version (tracking issue, RFC 2523).

What is being stabilized

Permit users to cfg gate code sections based on the currently present rust version.

#[cfg(version("1.87"))]
pub fn from_utf8_unwrap(buf: &[u8]) -> &str {
    str::from_utf8(buf).unwrap()
}

#[cfg(not(version("1.87")))]
pub fn from_utf8_unwrap(buf: &[u8]) -> &str {
    std::str::from_utf8(buf).unwrap()
}

Tests

The first test was added by the original implementation PR #71314 , and is mostly a test for the allowed and not allowed ways to specify the version as part of the attribute. It has seen some changes as the implementation of cfg_version has been changed. As of this PR, the test ensures:

• #[cfg(version(1.20.0))] is not allowed, deviating from the RFC
• The expected syntax is #[cfg(version("1.20.0"))]
• small shortenings like #[cfg(version("1.20"))] are allowed, but #[cfg(version("1"))] is not
• postfixes to the version, like #[cfg(version("1.20.0-stable"))] are not allowed
• #[cfg(version = "1.20.0")] is not supported, and there is a warning of the unexpected_cfgs lint (but no compilation error)

The stabilization PR also adds a functional test, which ensures that cfg_version actually works.

• #[cfg(version = "1.20.0")] acts as if the cfg was false due to the wrong syntax, even if the compiler version is above the specified version
• cfg!(version("1.50.4")) evals as false on 1.50.3, and cfg!(version("1.50.3")) evals as true.

Lastly, there is assume-incomplete.rs using macros instead of RUSTC_OVERRIDE_VERSION_STRING.

This PR makes cfg(version) respect RUSTC_OVERRIDE_VERSION_STRING, to make it easier to test things, and adds a test based on that.

Development of the implementation

The initial implementation was added by PR #71314 which used the version_check crate.

PR #72001 made cfg(version(1.20)) eval to false on nightly builds with version 1.20.0, upon request from the lang team. This decision was pushed back on by dtolnay in this comment, leading to nikomatsakis reversing his decision.

Ultimately, a compromise was agreed upon, in which nightly releases are treated as "complete" i.e. cfg(version(1.20)) evals to true on nightly builds with version 1.20.0, but there is a nightly flag -Z assume-incomplete-release to opt into the behaviour that doesn't do this assumption. This compromise was implemented in PR #81468.

PR #81259 made us adopt our own parsing code instead of using the version_check crate.

Unresolved questions

Should we lint for cfg(version) probing for a compiler version below the specified MSRV? Part of a larger discussion on MSRV specific behaviour in the Rust compiler. It feels like it should be a rustc lint though instead of a clippy lint.

Future work

The stabilization doesn't close the tracking issue, as the #[cfg(accessible(...))] part of the work is still not stabilized, currently requiring an implementation (if an implementation is something we'd want to merge in the first place).

See also

Earlier stabilization report

TODOs before stabilization

• incompatible_msrv doesn't respect #[cfg(version(...))] rust-clippy#14827 . Not a hard blocker, but the lint is warning by default and people will probably hit it in fairly common combinations.
• should we sync up with the cargo implementation? There is currently nothing implemented in cargo yet. Tracking Issue for cfg_version cargo#15531
• reference PR: Document #[cfg(version(...))] reference#1828

[rustbot]

r? @jieyouxu

rustbot has assigned @jieyouxu.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred in compiler/rustc_attr_data_structures

cc @jdonszelmann

Some changes occurred in compiler/rustc_attr_parsing

cc @jdonszelmann

[traviscross]

Suggested change

	/// Allow conditional compilation depending on rust version
	/// Allow conditional compilation depending on Rust version.

[traviscross]

This looks right to me. Thanks to @est31 for putting this together and for the careful stabilization report. I propose that we do this.

@rfcbot fcp merge

[rfcbot]

Team member @traviscross has proposed to merge this. The next step is review by the rest of the tagged team members:

• @joshtriplett
• @nikomatsakis
• @scottmcm
• @tmandry
• @traviscross

Concerns:

• has_cfg_version resolved by Stabilize #[cfg(version(...))] #141137 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

[traviscross]

Thanks also to @epage for perhaps prodding us along here, in his recent talk, by pointing out the cost to ecosystem compile time performance of not doing this.

[traviscross]

Regarding whether we should hold off merging this stabilization until the change to Cargo is ready, if we do want to do that, we can simply mark this as S-blocked without holding up the FCP. On the question itself, I'm curious to hear from the @rust-lang/cargo team their thoughts and any particular reasons for why we might want to hold off merging the lang-side change here pending the Cargo-side work.

[Noratrieb]

(not about this file specifically)
I think the example of the stabilization report, let chains, are a particularly bad example here because they're syntax, and syntax is, except for some old legacy stuff, gated pre-expansion, so cfg(version) won't actually help there. It would probably make sense to mention this in the reference that this can't really be used for conditionally making use of syntax, or rather that such uses requires going through an intermediary macro_rules to avoid parsing it on the old version.

[madsmtm]

Or putting the syntax in a separate module IIRC.

[Noratrieb]

Yes, anything that won't be parsed before the cfg is expanded.

[est31]

Updated the example to use a libs function instead. The example still fails compilation on the old release, because #[cfg(version(...))] errors on compilers that don't have the stabilization yet, so it's only useful when your MSRV is >= the release that #[cfg(version(...))] stabilized in.

It's actually maybe something that one can discuss, whether to support #[cfg(version = "...")] as well. This syntax does not error on older compilers, or on current ones. The disadvantage is two different ways of doing things and possible breakage because it might activate some blocks within #[cfg(version = "...")], but I'd say that breakage is rather theoretical.

In the long term, #[cfg(version = "...")] is not neccessary: it's only helpful for the transitory period.

[traviscross]

If we were to take the breakage here, I'm not sure why we wouldn't just make #[cfg(version = "..")] the one way to write this.

The concern I recall hearing was the worry that people might think this was a version equality constraint rather than a ^ or >= constraint, but that doesn't seem to be a problem for Cargo dependencies, where e.g. time = "0.1.12" means time = "^0.1.12", or for the MSRV field itself, e.g. rust-version = "1.89".

If we were still concerned, we could require people to write the ^ explicitly, e.g. #[cfg(version = "^1.89")].

[traviscross]

Looking at the RFC, the question was considered in the context of cfg(accessible(..)) vs cfg(accessible = ..)), where yes, the former definitely seems better.

[madsmtm]

Re cfg(version = "..."), see the RFC text. This is actually also listed in the unresolved questions in the tracking issue, and was discussed briefly on the tracking issue.

IMO, I think we should only support cfg(version = "...") if we emitted all the (hundreds of) valid version="1.0", version="1.0.0", version="1.1", version="1.1.0", etc. as part of rustc --print cfg too.

Unless we want to diverge from cfg(key = "value") being a static thing? I can see the value in that as well, it'd be useful for many other cfg attributes.

EDIT: Sorry, GH didn't update, so posted this before I saw TC's response.

[traviscross]

It does seem at this point that we should probably just stabilize cfg(version("..")). We could always decide later about doing more.

[joshtriplett]

Regarding cfg(version = "..."), see #141137 (comment) .

[madsmtm]

What's the reasoning we don't use this syntax again?

From reading #71314, it seems like it was punted on for later because of implementation difficulty. Maybe that's not true any more?

I'd prefer writing #[cfg(version(1.87.1))] over #[cfg(version("1.87.1"))]. Having two levels of grouping, both parentheses and quotes, seems redundant.

[traviscross]

It makes a certain sense to me to quote it as it is a "version string". In attributes, we generally still try to match the general grammar of Rust, and we wouldn't accept an unquoted 1.87.1 as an argument anywhere else.

[madsmtm]

we wouldn't accept an unquoted 1.87.1 as an argument anywhere else.

I can see the argument, though I don't see why that should necessarily be an absolute? Syntactically, you can write let x = 1.87.1, though that's of course parsed as "literal 1.87" + "field access 1" (which then fails because floats don't have any fields).

Idk., I just think it's unfortunate that we limit ourselves here, since I suspect the vast majority of cases where cfg(version(...)) is useful, you wouldn't need to specify the patch version - looking at the changelog, I actually cannot find a single use-case where you'd want cfg(version(major.minor.patch)) where patch wouldn't just be 0?

If we wanted this syntax, an option could be to disallow patch versions to begin with?

---

A difficulty with major.minor.patch is on the macro-side, I see a few ways to solve this:

1. The heavy-weight: Introduce a new token literal LitKind::Version and change $x:literal over an edition to contain this as well.

2. Define that the token parsing is cfg(version($major_minor:literal $(. $patch:tt)?)).

3. Specialize parsing of this as one token, but try to hide it from the language. Though that has unclear interactions with macros such as:

   macro_rules! split {
       ($x:tt) => { cfg!(version(1.87 . $x)) };
   }
   
   macro_rules! split {
       ($x:tt) => { cfg!(version($x . 87 . 1)) };
   }

   Maybe we can disallow those? But we'd want a stable way for proc-macros to create the required TokenTree::Literal.

Regardless, I think what I'm saying with this is that while this doesn't have an immediately clean solution, the solution space isn't empty, and I think it's worthwhile it to choose one of these options to get the cleaner syntax. But I guess I'm also motivated here by future attributes with versions in them.

[madsmtm]

CC @petrochenkov who reviewed the implementation PR that did cfg(version("major.minor.patch")) (with the quotes).

[epage]

From a tokenization perspective, a string fits best. A major/minor version could look like a float which we don't have now but I do want to explore bools, ints, and floats for --cfg for cargo "globals" though I don't have use cases for #[cfg] operators for these at this time

[jieyouxu]

I'll hold off on reviewing the impl until some of the design questions are settled (looks like there are unresolved design concerns), please ping me if it's ready for impl review.

[joshtriplett]

The proposal as originally reviewed and approved was for cfg(version(...)), and adding cfg(version = "...") was considered and rejected, in part because of the potential confusion of "equals". But this discussion has given an additional reason we shouldn't accept it:

It's already not going to be functional in any version older than the version that stabilizes cfg(version(...)). Changing the syntax to make it parse and evaluate as always false in old versions is not a feature, since code that still supports those older versions may need to do version detection that distinguishes some of those older versions (e.g. "is this 1.70 or newer").

I would argue that it's a bug to silently ignore it in older versions, precisely because it'll be non-functional: cfg(version = "1.70") will be silently false in 1.70, 1.71, 1.72, up through whatever version stabilizes version checks.

Pieces of the ecosystem can switch to cfg(version(...)) as their MSRVs become sufficiently new that it works.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[joshtriplett]

Regardless of whether we want has_cfg_version or not, I'd like to flag the process problem of making last-minute changes as part of stabilization, in the last day of FCP, within 24 hours of proposing them, and then having that FCP conclude. FCP isn't just for team members, it's meant to be a comment period for the community as well, and the 10-day period ensures that people have time to see it.

[traviscross]

Leaving nominated to make sure lang members who already checked their boxes are aware of the change. I discussed it in the last meeting and no one expressed opposition to the idea of has_cfg_version, so I don't think we need to restart fcp.

In the spec call, @joshtriplett and I briefly discussed the existence of the has_cfg_version change. Probably, though, it's still best process to just restart to give him the opportunity to review and recheck the box, and that also signals to others watching that the proposal has changed.

@rfcbot cancel

(Edit: @joshtriplett and I raced on these messages.)

[rfcbot]

@traviscross proposal cancelled.

[traviscross]

Proposing for merge with the inclusion of cfg(has_cfg_version).

@rfcbot fcp merge

[rfcbot]

Team member @traviscross has proposed to merge this. The next step is review by the rest of the tagged team members:

• @joshtriplett
• @nikomatsakis
• @scottmcm
• @tmandry
• @traviscross

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

[traviscross]

@est31, if you would, please update the stabilization report to include cfg(has_cfg_version).

[jieyouxu]

Meta remark: Hi, as the implementation reviewer, I would like to remark that:

1. It would be much easier to review stabilizations if significant design deviations and decisions were made and landed separately from and before the stabilization PR, and
2. If the stabilization PR is limited to mostly mechanical feature gate changes, it'd be easier to access the maturity of the implementation.

[RalfJung]

Yeah I think we should still do that (i.e. split up this PR), also to make it easier to revert just the stabilization should that be needed.

[traviscross]

Yes, agreed. The has_cfg_version change should definitely go in its own PR. It's convenient on the lang side too if these stabilization PRs are mechanical in the way that you say.

Having talked with others, though, about similar observations and concerns about it being clear to everyone what the proposal is and what's being stabilized, let's actually go further and just close this PR and ask for a new v2 stabilization PR to be opened after has_cfg_version has landed in nightly and a new stabilization report is ready that includes it.

@rfcbot cancel

[joshtriplett]

@traviscross Though, if we decide to go ahead and stabilize cfg(version(...)) without has_cfg_version we don't need to jump through those hoops.

[traviscross]

Yes, agreed. The PR author accepted the change, though, and made it part of the proposal. That's why I'd say it deserves a new PR at this point.

[joshtriplett]

Leaving aside the procedural concern about last-minute changes...

Regarding has_cfg_version itself: while this is not a blocking objection if everyone else is in favor, I do think it would have been reasonable to simply let people continue using build-script-based detection if they're not willing to upgrade their MSRV, since they'll still have to do so if they actually want to distinguish between older versions.

has_cfg_version would prove rather challenging to use correctly. In versions of Rust that don't support it, it'll produce:

warning: unexpected cfg condition name: has_cfg_version

If you want your code to build warning-free, you'll have to make sure rustc is aware of it, which requires adding a lints.rust.unexpected_cfgs stanza to Cargo.toml, or similar.

And you also have to write cfg(has_cfg_version) as a separate #[cfg(...)] attribute. If you write, for instance, #[cfg(all(has_cfg_version, version("...")))], compilers that don't have version available to stable code will error, because version is "experimental and subject to change". You have to write, instead, #[cfg(has_cfg_version)] followed by #[cfg(version(...))].

For people using current Rust, nothing will catch either of those problems; you'll only see them if you go back and build with older Rust. And once you do, you'll have to take the additional step of adding the Cargo.toml stanza to solve the first problem.

And for the especially common case of "add this dependency if building on older Rust", it's not obvious whether it'd be feasible to make that work in older Cargo. And in the corresponding Rust code trying to use either the dependency for old Rust or the support in new Rust, AFAICT, has_cfg_version can't solve the problem of cfg(not(version(...))), because you can't write an "or" by just chaining. As far as I can tell, you'd have to duplicate. (You could pull code into a module to reduce the duplication, but it's still added complexity.)

I think the net result is added complexity that users have to deal with for simple version detection, and several easy ways to get it wrong.

[jplatte]

has_cfg_version would prove rather challenging to use correctly. In versions of Rust that don't support it, it'll produce:

warning: unexpected cfg condition name: has_cfg_version

If you want your code to build warning-free, you'll have to make sure rustc is aware of it, which requires adding a lints.rust.unexpected_cfgs stanza to Cargo.toml, or similar.

Since dependencies are built with cap-warnings, I don't think it would be important to do this usually. I don't remember seeing projects have a deny-warnings CI job for their MSRV, it tends to always be stable or nightly.

And you also have to write cfg(has_cfg_version) as a separate #[cfg(...)] attribute. If you write, for instance, #[cfg(all(has_cfg_version, version("...")))], compilers that don't have version available to stable code will error, because version is "experimental and subject to change". You have to write, instead, #[cfg(has_cfg_version)] followed by #[cfg(version(...))].

For people using current Rust, nothing will catch either of those problems; you'll only see them if you go back and build with older Rust. And once you do, you'll have to take the additional step of adding the Cargo.toml stanza to solve the first problem.

Yeah, it's a bit ugly but many projects that set an MSRV have a CI job that tests that things compile with that MSRV, right?

[joshtriplett]

@tmandry wrote:

I would like to see us stabilize these together; otherwise you would have a window of time where #[cfg(version(..))] exists but #[cfg(has_cfg_version)] does not. I think this would add further confusion and historical noise.

I don't think this is inherently the case. Anyone who was prepared to use cfg(version(...)) as it was 24 hours ago would be able to immediately use it. Anyone who doesn't mind jumping through additional hoops in order to use cfg(has_cfg_version) to support pre-cfg-version compilers could do that hoop-jumping once cfg(has_cfg_version) ships.

In other words: it seems like a feature that should make its own case, and ship on its own timeline (namely, not 24 hours, or even 10 days, after being first proposed), rather than being inherently tied to cfg(version(...)) (which has gone through an RFC, and been implemented and considered for some time now).

[jieyouxu]

@tmandry wrote:

I would like to see us stabilize these together; otherwise you would have a window of time where #[cfg(version(..))] exists but #[cfg(has_cfg_version)] does not. I think this would add further confusion and historical noise.

I don't think this is inherently the case. Anyone who was prepared to use cfg(version(...)) as it was 24 hours ago would be able to immediately use it. Anyone who doesn't mind jumping through additional hoops in order to use cfg(has_cfg_version) to support pre-cfg-version compilers could do that hoop-jumping once cfg(has_cfg_version) ships.

In other words: it seems like a feature that should make its own case, and ship on its own timeline (namely, not 24 hours, or even 10 days, after being first proposed), rather than being inherently tied to cfg(version(...)).

FTR, if cargo support for these aren't a stabilization blocker, if we land cfg(has_cfg_version) unstably separately first, then it's mechanically possible to have a joint stabilization PR of cfg(has_cfg_version) + cfg(version(..)), if those are the current design consensus as a joint language feature (i.e. collectively forms the concept of the cfg(version(..)) language feature).

(Of course, this is only if there's design consensus)

[traviscross]

I think the net result is added complexity that users have to deal with for simple version detection, and several easy ways to get it wrong.

You make a compelling case about this being rather hard to use. Both @scottmcm and I were OK with stabilizing cfg(version("..")) without has_cfg_version. Let's take a poll to see where we all fall here. I'll check your box and scottmcm's box based on what he said in the meeting.

The question is, "would you stabilize cfg(version("..")) without has_cfg_version?" We could of course address has_cfg_version separately and later.

@rfcbot poll

[joshtriplett]

@jplatte wrote:

Since dependencies are built with cap-warnings, I don't think it would be important to do this usually.

That doesn't help binaries. And even for libraries, sometimes people work on the library itself, or vendor the library into their workspace, or use it via path dependency, at which point you'll see those warnings.

Also, the issue of handling this in Cargo, and the issue of handling the cfg(not(version(...))) case without code duplication, still remain.

[traviscross]

@rfcbot poll

The bot doesn't like closed issues, so I've opened this question for us here:

• Decide whether to separate cfg(version("..")) and cfg_has_version #141401

[est31]

@traviscross

let's [...] ask for a new v2 stabilization PR to be opened after has_cfg_version has landed in nightly and a new stabilization report is ready that includes it.

Sorry for the large diff caused by has_cfg_version, most of it is noise from tests as I didn't find a way to reorganize the diagnostics. Already finding a way to make that diagnostic optional took me around an hour (before the "AST for errors" work this would have been less than a minute).

In any case, back to the topic, I don't think we should implement has_cfg_version before a cfg(version(...)) stabilization: because then there would be releases (nightlies) that contain has_cfg_version but still give the error for cfg(version(...)). People might encounter those during bisection etc.

If we split up the two, we should merge the PRs in opposite order: cfg(version(...)) first, then has_cfg_version.

But I see that order (has_cfg_version second) is the vibe of #141401 (comment) as well.

However, I can split the RUSTC_OVERRIDE_VERSION_STRING into a separate PR, and re-do a stabilization PR.