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.88"))]
pub fn maybe_env() -> u32 {
    if let Ok(hello) = std::env::var("HELLO")
        && let Ok(v) = hello.parse()
    {
        v
    } else {
        0
    }
}

#[cfg(not(version("1.88")))]
pub fn maybe_env() -> u32 {
    if let Ok(hello) = std::env::var("HELLO") {
        if let Ok(v) = hello.parse() {
            return v;
        }
    }
    0
}

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

[rust-log-analyzer]

The job mingw-check-tidy failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

info: removing rustup binaries
info: rustup is uninstalled
##[group]Image checksum input
mingw-check-tidy
# We use the ghcr base image because ghcr doesn't have a rate limit
# and the mingw-check-tidy job doesn't cache docker images in CI.
FROM ghcr.io/rust-lang/ubuntu:22.04

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  g++ \
---

COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/

# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
           --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#12 2.900 Building wheels for collected packages: reuse
#12 2.901   Building wheel for reuse (pyproject.toml): started
#12 3.111   Building wheel for reuse (pyproject.toml): finished with status 'done'
#12 3.112   Created wheel for reuse: filename=reuse-4.0.3-cp310-cp310-manylinux_2_35_x86_64.whl size=132719 sha256=d2a2565e7037ad3883fb9337653f2e25bbb588534fbef3697286cbc26d1bf634
#12 3.112   Stored in directory: /tmp/pip-ephem-wheel-cache-xsmojaxc/wheels/3d/8d/0a/e0fc6aba4494b28a967ab5eaf951c121d9c677958714e34532
#12 3.114 Successfully built reuse
#12 3.115 Installing collected packages: boolean-py, binaryornot, tomlkit, reuse, python-debian, markupsafe, license-expression, jinja2, chardet, attrs
#12 3.510 Successfully installed attrs-23.2.0 binaryornot-0.4.4 boolean-py-4.0 chardet-5.2.0 jinja2-3.1.4 license-expression-30.3.0 markupsafe-2.1.5 python-debian-0.1.49 reuse-4.0.3 tomlkit-0.13.0
#12 3.510 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 4.042 Collecting virtualenv
#12 4.078   Downloading virtualenv-20.31.2-py3-none-any.whl (6.1 MB)
#12 4.155      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.1/6.1 MB 80.9 MB/s eta 0:00:00
#12 4.213 Collecting platformdirs<5,>=3.9.1
#12 4.216   Downloading platformdirs-4.3.8-py3-none-any.whl (18 kB)
#12 4.233 Collecting distlib<1,>=0.3.7
#12 4.237   Downloading distlib-0.3.9-py2.py3-none-any.whl (468 kB)
#12 4.244      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 469.0/469.0 KB 88.0 MB/s eta 0:00:00
#12 4.279 Collecting filelock<4,>=3.12.2
#12 4.282   Downloading filelock-3.18.0-py3-none-any.whl (16 kB)
#12 4.365 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#12 4.557 Successfully installed distlib-0.3.9 filelock-3.18.0 platformdirs-4.3.8 virtualenv-20.31.2
#12 4.557 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 DONE 4.6s

#13 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#13 DONE 0.0s
---
DirectMap4k:      145344 kB
DirectMap2M:     8243200 kB
DirectMap1G:    10485760 kB
##[endgroup]
Executing TIDY_PRINT_DIFF=1 python2.7 ../x.py test            --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
+ TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
##[group]Building bootstrap
    Finished `dev` profile [unoptimized] target(s) in 0.05s
##[endgroup]
WARN: currently no CI rustc builds have rustc debug assertions enabled. Please either set `rust.debug-assertions` to `false` if you want to use download CI rustc or set `rust.download-rustc` to `false`.
downloading https://static.rust-lang.org/dist/2025-05-12/rustfmt-nightly-x86_64-unknown-linux-gnu.tar.xz
---
[TIMING] core::build_steps::tool::Tidy { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu } -- 0.000
fmt check
fmt: checked 6011 files
tidy check
tidy error: Stray file with UI testing output: "/checkout/tests/ui/feature-gates/feature-gate-cfg-version.stderr"
tidy: Skipping binary file check, read-only filesystem
removing old virtual environment
tidy error: The Unstable Book has a 'language feature' section 'cfg-version' which doesn't correspond to an unstable language feature
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (25.1.1)
linting python files
All checks passed!
checking python file formatting
26 files already formatted
checking C++ file formatting
some tidy checks failed
Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:01:53
  local time: Sat May 17 15:09:17 UTC 2025
  network time: Sat, 17 May 2025 15:09:17 GMT
##[error]Process completed with exit code 1.
Post job cleanup.

[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

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]

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]

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.