RFC: cfg_target_version #3750

ChrisDenton · 2024-12-27T11:09:52Z

This RFC builds on the work of @rylev and @chriswailes. As suggested by @tmandry I have stripped it down to an MVP that just adds target_version (aka os_version_min in previous RFCs).

Rendered

text/3750-cfg-os-version-min.md

bjorn3 · 2025-01-03T13:16:21Z

text/3750-cfg-os-version-min.md

+A set of comparison functions can be provided by `rustc` for common formats such as 2- and 3-part semantic versioning.
+When a platform detects a key it doesn’t support it will return `false` and emit a warning.
+
+Each target platform will set the minimum API versions it supports.


So there is no way for the user to configure which minimum API version they want to use? That would make it impossible for eg the libc crate to gate api's behind #[cfg(os_version_min)] corresponding to the libc version that introduced the API in question.

Yes. One of the issues with the original proposals was there was too much going on. This RFC aims to add the minimally useful feature. Adding compiler flags and Cargo configs to control the minimum version can be a future extension.

With this RFC it is still possible for libc to gate APIs like that. However, you'd need a new target in order to set a different minimal libc version.

Aloso · 2025-01-03T14:10:19Z

The idea is great, but I think the syntax can be improved. It makes more sense to have this feature under the existing target_os config, so here's an idea:

cfg(target_os("windows", min_version = "..."))

Another idea:

cfg(target_os = "windows >= ...")

ChrisDenton · 2025-01-03T14:27:17Z

That may work for windows but not, for example, Linux where you may want to cfg on the kernel version or the libc version (or even both).

libc isn't really a target_os.

Aloso · 2025-01-03T21:58:14Z

Right, so this could be done with a target_libc attribute, like

cfg(target_libc("glibc", min_version = "..."))

But of course this would add more complexity.

madsmtm

Thanks for reviving this @ChrisDenton! I'd be willing to implement at least the Apple parts of this, and probably also other parts.

text/3750-cfg-os-version-min.md

Co-authored-by: Mads Marquart <[email protected]>

madsmtm · 2025-01-05T17:31:33Z

text/3750-cfg-os-version-min.md

+# Future possibilities
+[future-possibilities]: #future-possibilities
+
+The compiler could allow setting a higher minimum OS version than the target's default.


Remark: I'll add that rustc already has a mechanism for doing exactly this on Apple platforms, namely the *_DEPLOYMENT_TARGET family of environment variables.

madsmtm · 2025-01-05T17:31:42Z

text/3750-cfg-os-version-min.md

+
+**Note:** Here it would be important to link to documentation showing the `cfg` predicates and the different version strings that are supported.
+
+# Reference-level explanation


I think we need to discuss here what happens when you link libraries compiled with different (even though we're not specifying how the user, we will need a mechanism for it at some point)

Specifically, it'd be nice to talk about the pre-compiled standard library, and how it effectively becomes a requirement to use -Zbuild-std if the user wants to enable this kind of stuff for the standard library.

madsmtm · 2025-01-05T17:33:14Z

text/3750-cfg-os-version-min.md

+
+**Note:** Here it would be important to link to documentation showing the `cfg` predicates and the different version strings that are supported.
+
+# Reference-level explanation


Possibly also interesting is soundness concerns (what happens if I use a standard library compiled with a newer version of glibc/Windows APIs/macOS APIs, while I link with a binary compiled for older APIs?).

I don't think there are any soundness concerns, at least not on Apple platforms (the dynamic linker will simply fail to work if using an API for a newer system), but it's important that we're certain of this (and that function pointers for example aren't simply replaced by NULL if loaded on an older OS).

There aren't unsoundness issues for Windows. Either a dll or symbol is available or it isn't and there's an error. EDIT: I'm being told that attempting to use incompatible glibcs will also cause an error.

I don't know if that's true of all OSes but Rust libs do carry around metadata with them so if they declare incompatible versions then the compiler could simply error. And linking together native static libraries compiled for different API versions would seem to be squarely in the realm of "you must know what you're doing" (and that's true more broadly when linking native libs). However, considering the current narrow scope of this RFC, it would not be a situation that arises any more often than it currently does. So it may only worth a mention in future possibilities.

I'd actually like to update my previous statement, I suspect that it may actually be unsound to use the combination dependency (compiled for newer OS) + user_crate (compiled for older OS) + link (for older OS), since e.g. LLVM may do codegen optimizations that are only valid on newer architectures (which one can do because Apple restricts OS upgrades after a certain point, so we know that newer OS versions only run on newer hardware, and can be required to have for example a certain level of SIMD features).

Related here is #3716.

But I agree that this is only tangentially related to the RFC.

text/3750-cfg-os-version-min.md

ChrisDenton · 2025-01-27T05:52:31Z

Ok I've rewritten this a bit and further simplified it based on feedback.

Based on in-progress RFC: rust-lang/rfcs#3750. Only implemented for Apple platforms for now, but written in a way that should be easily expandable to include other platforms.

madsmtm

I've created a tracking issue for this feature in rust-lang/rust#136866, and filed a PR implementing it (unstably) for Apple platforms in rust-lang/rust#136867. I guess that at least shows feasibility of the RFC.

text/3750-cfg-os-version-min.md

Based on in-progress RFC: rust-lang/rfcs#3750. Only implemented for Apple platforms for now, but written in a way that should be easily expandable to include other platforms.

Co-authored-by: Mads Marquart <[email protected]>

Add `__isPlatformVersionAtLeast` and `__isOSVersionAtLeast` symbols ## Motivation When Objective-C code uses ``@available(...)`,` Clang inserts a call to [`__isPlatformVersionAtLeast`](https://github.com/llvm/llvm-project/blob/llvmorg-20.1.0/compiler-rt/lib/builtins/os_version_check.c#L276) (`__isOSVersionAtLeast` in older Clang versions). These symbols not being available sometimes ends up causing linker errors. See the new test `tests/run-make/apple-c-available-links` for a minimal reproducer. The workaround is to link `libclang_rt.osx.a`, see e.g. alexcrichton/curl-rust#279. But that's very difficult for users to figure out (and the backreferences to that issue indicates that people are still running into this in their own projects every so often). For another recent example, this is preventing `rustc` from using LLVM assertions on macOS, see #62592 (comment) and #134275 (comment). It is also a blocker for [setting the correct minimum OS version in `cc-rs`](#136113), since fixing this in `cc-rs` might end up introducing linker errors in places where we weren't before (by default, if using e.g. ``@available(macos` 10.15, *)`, the symbol usually happens to be left out, since `clang` defaults to compiling for the host macOS version, and thus things _seem_ to work - but the availability check actually compiles down to nothing, which is a huge correctness footgun for running on older OSes). (My super secret evil agenda is also to expose some variant of ``@available`` in Rust's `std` after rust-lang/rfcs#3750 progresses further, will probably file an ACP for this later. But I believe this PR has value regardless of those future plans, since we'd be making C/Objective-C/Swift interop easier). ## Solution Implement `__isPlatformVersionAtLeast` and `__isOSVersionAtLeast` as part of the "public ABI" that `std` exposes. **This is insta-stable**, in the same sense that additions to `compiler-builtins` are insta-stable, though the availability of these symbols can probably be considered a "quality of implementation" detail rather than a stable promise. I originally proposed to implement this in `compiler-builtins`, see rust-lang/compiler-builtins#794, but we discussed moving it to `std` instead ([Zulip thread](https://rust-lang.zulipchat.com/#narrow/channel/219381-t-libs/topic/Provide.20.60__isPlatformVersionAtLeast.60.20in.20.60std.60.3F/with/507880717)), which makes the implementation substantially simpler, and we avoid gnarly issues with requiring the user to link `libSystem.dylib` (since `std` unconditionally does that). Note that this does not solve the linker errors for (pure) `#![no_std]` users, but that's _probably_ fine, if you are using ``@available`` to test the OS version on Apple platforms, you're likely also using `std` (and it is still possible to work around by linking `libclang_rt.*.a`). A thing to note about the implementation, I've choosen to stray a bit from LLVM's upstream implementation, and not use `_availability_version_check` since [it has problems when compiling with an older SDK](llvm/llvm-project#64227). Instead, we use `sysctl kern.osproductversion` when available to still avoid the costly PList lookup in most cases, but still with a fall back to the PList lookup when that is not available (with the PList fallback being is similar to LLVM's implementation). ## Testing Apple has a lot of different "modes" that they can run binaries in, which can be a bit difficult to find your bearings in, but I've tried to be as thorough as I could in testing them all. Tested using roughly the equivalent of `./x test library/std -- platform_version` on the following configurations: - macOS 14.7.3 on a Macbook Pro M2 - `aarch64-apple-darwin` - `x86_64-apple-darwin` (under Rosetta) - `aarch64-apple-ios-macabi` - `x86_64-apple-ios-macabi` (under Rosetta) - `aarch64-apple-ios` (using Xcode's "Designed for iPad" setting) - `aarch64-apple-ios-sim` (in iOS Simulator, as iPhone with iOS 17.5) - `aarch64-apple-ios-sim` (in iOS Simulator, as iPad with iOS 18.2) - `aarch64-apple-tvos-sim` (in tvOS Simulator) - `aarch64-apple-watchos-sim` (in watchOS Simulator) - `aarch64-apple-ios-sim` (in visionOS simulator, using Xcode's "Designed for iPad" setting) - `aarch64-apple-visionos-sim` (in visionOS Simulator) - macOS 15.3.1 VM - `aarch64-apple-darwin` - `aarch64-apple-ios-macabi` - macOS 10.12.6 on an Intel Macbook from 2013 - `x86_64-apple-darwin` - `i686-apple-darwin` - `x86_64-apple-ios` (in iOS Simulator) - iOS 9.3.6 on a 1st generation iPad Mini - `armv7-apple-ios` with an older compiler Along with manually inspecting the output of `version_from_sysctl()` and `version_from_plist()`, and verifying that they actually match what's expected. I believe the only real omissions here would be: - `aarch64-apple-ios` on a newer iPhone that has `sysctl` available (iOS 11.4 or above). - `aarch64-apple-ios` on a Vision Pro using Xcode's "Designed for iPad" setting. But I don't have the hardware available to test those. `@rustbot` label O-apple A-linkage -T-compiler -A-meta -A-run-make try-job: aarch64-apple try-job: x86_64-apple

Add `__isPlatformVersionAtLeast` and `__isOSVersionAtLeast` symbols ## Motivation When Objective-C code uses ``@available(...)`,` Clang inserts a call to [`__isPlatformVersionAtLeast`](https://github.com/llvm/llvm-project/blob/llvmorg-20.1.0/compiler-rt/lib/builtins/os_version_check.c#L276) (`__isOSVersionAtLeast` in older Clang versions). These symbols not being available sometimes ends up causing linker errors. See the new test `tests/run-make/apple-c-available-links` for a minimal reproducer. The workaround is to link `libclang_rt.osx.a`, see e.g. alexcrichton/curl-rust#279. But that's very difficult for users to figure out (and the backreferences to that issue indicates that people are still running into this in their own projects every so often). For another recent example, this is preventing `rustc` from using LLVM assertions on macOS, see #62592 (comment) and #134275 (comment). It is also a blocker for [setting the correct minimum OS version in `cc-rs`](#136113), since fixing this in `cc-rs` might end up introducing linker errors in places where we weren't before (by default, if using e.g. ``@available(macos` 10.15, *)`, the symbol usually happens to be left out, since `clang` defaults to compiling for the host macOS version, and thus things _seem_ to work - but the availability check actually compiles down to nothing, which is a huge correctness footgun for running on older OSes). (My super secret evil agenda is also to expose some variant of ``@available`` in Rust's `std` after rust-lang/rfcs#3750 progresses further, will probably file an ACP for this later. But I believe this PR has value regardless of those future plans, since we'd be making C/Objective-C/Swift interop easier). ## Solution Implement `__isPlatformVersionAtLeast` and `__isOSVersionAtLeast` as part of the "public ABI" that `std` exposes. **This is insta-stable**, in the same sense that additions to `compiler-builtins` are insta-stable, though the availability of these symbols can probably be considered a "quality of implementation" detail rather than a stable promise. I originally proposed to implement this in `compiler-builtins`, see rust-lang/compiler-builtins#794, but we discussed moving it to `std` instead ([Zulip thread](https://rust-lang.zulipchat.com/#narrow/channel/219381-t-libs/topic/Provide.20.60__isPlatformVersionAtLeast.60.20in.20.60std.60.3F/with/507880717)), which makes the implementation substantially simpler, and we avoid gnarly issues with requiring the user to link `libSystem.dylib` (since `std` unconditionally does that). Note that this does not solve the linker errors for (pure) `#![no_std]` users, but that's _probably_ fine, if you are using ``@available`` to test the OS version on Apple platforms, you're likely also using `std` (and it is still possible to work around by linking `libclang_rt.*.a`). A thing to note about the implementation, I've choosen to stray a bit from LLVM's upstream implementation, and not use `_availability_version_check` since [it has problems when compiling with an older SDK](llvm/llvm-project#64227). Instead, we use `sysctl kern.osproductversion` when available to still avoid the costly PList lookup in most cases, but still with a fall back to the PList lookup when that is not available (with the PList fallback being is similar to LLVM's implementation). ## Testing Apple has a lot of different "modes" that they can run binaries in, which can be a bit difficult to find your bearings in, but I've tried to be as thorough as I could in testing them all. Tested using roughly the equivalent of `./x test library/std -- platform_version` on the following configurations: - macOS 14.7.3 on a Macbook Pro M2 - `aarch64-apple-darwin` - `x86_64-apple-darwin` (under Rosetta) - `aarch64-apple-ios-macabi` - `x86_64-apple-ios-macabi` (under Rosetta) - `aarch64-apple-ios` (using Xcode's "Designed for iPad" setting) - `aarch64-apple-ios-sim` (in iOS Simulator, as iPhone with iOS 17.5) - `aarch64-apple-ios-sim` (in iOS Simulator, as iPad with iOS 18.2) - `aarch64-apple-tvos-sim` (in tvOS Simulator) - `aarch64-apple-watchos-sim` (in watchOS Simulator) - `aarch64-apple-ios-sim` (in visionOS simulator, using Xcode's "Designed for iPad" setting) - `aarch64-apple-visionos-sim` (in visionOS Simulator) - macOS 15.3.1 VM - `aarch64-apple-darwin` - `aarch64-apple-ios-macabi` - macOS 10.12.6 on an Intel Macbook from 2013 - `x86_64-apple-darwin` - `i686-apple-darwin` - `x86_64-apple-ios` (in iOS Simulator) - iOS 9.3.6 on a 1st generation iPad Mini - `armv7-apple-ios` with an older compiler Along with manually inspecting the output of `version_from_sysctl()` and `version_from_plist()`, and verifying that they actually match what's expected. I believe the only real omissions here would be: - `aarch64-apple-ios` on a newer iPhone that has `sysctl` available (iOS 11.4 or above). - `aarch64-apple-ios` on a Vision Pro using Xcode's "Designed for iPad" setting. But I don't have the hardware available to test those. `@rustbot` label O-apple A-linkage -T-compiler -A-meta -A-run-make try-job: aarch64-apple try-job: x86_64-apple*

ChrisDenton added 2 commits December 27, 2024 11:05

RFC: cfg_os_version_min

c08880c

Update RFC PR number

d78f82b

ehuss added the T-lang Relevant to the language team, which will review and decide on the RFC. label Dec 31, 2024

Nemo157 reviewed Jan 2, 2025

View reviewed changes

text/3750-cfg-os-version-min.md Outdated Show resolved Hide resolved

Remove "in use"

58ae3de

bjorn3 reviewed Jan 3, 2025

View reviewed changes

madsmtm mentioned this pull request Jan 4, 2025

How do we handle availability? madsmtm/objc2#266

Open

madsmtm requested changes Jan 4, 2025

View reviewed changes

This was referenced Jan 4, 2025

Add text for the CFG OS Version RFC #3379

Closed

Add min_$TARGET_API_version cfg predicates #3036

Closed

ChrisDenton and others added 3 commits January 4, 2025 19:19

Update text/3750-cfg-os-version-min.md

0b8f912

Co-authored-by: Mads Marquart <[email protected]>

Mention other possible syntax

c3f33b8

Update prior art to include how C does it

6e2245c

madsmtm reviewed Jan 5, 2025

View reviewed changes

Kijewski reviewed Jan 11, 2025

View reviewed changes

text/3750-cfg-os-version-min.md Outdated Show resolved Hide resolved

workingjubilee mentioned this pull request Jan 17, 2025

Support QNX 7.1 with io-sock+libstd and QNX 8.0 (no_std only) rust-lang/rust#133631

Merged

ChrisDenton added 4 commits January 27, 2025 05:30

Update motivation and guide

35dc984

Update reference level explanation

5332c9b

Add a linting section

859a733

Remove double "additional"

6c7e0c6

ChrisDenton added 6 commits January 27, 2025 05:54

Add default supported target motivation

16c6321

Add a note about the standard library

68c00f8

Expand on the version string

6b54296

Note that a higher baseline isn't yet supported

a9b5b74

Fix some headings

b71051b

Update 3750-cfg-os-version-min.md

5cde247

madsmtm mentioned this pull request Feb 11, 2025

Tracking Issue for cfg_os_version_min rust-lang/rust#136866

Open

10 tasks

madsmtm mentioned this pull request Feb 11, 2025

Implement cfg_os_version_min rust-lang/rust#136867

Draft

madsmtm reviewed Feb 11, 2025

View reviewed changes

text/3750-cfg-os-version-min.md Outdated Show resolved Hide resolved

madsmtm mentioned this pull request Mar 25, 2025

Add __isPlatformVersionAtLeast and __isOSVersionAtLeast symbols rust-lang/rust#138944

Open

madsmtm mentioned this pull request Apr 8, 2025

Implement old version fallback using dlsym kornelski/rust-security-framework#223

Open

ChrisDenton and others added 6 commits April 9, 2025 23:46

Update text/3750-cfg-os-version-min.md

d9715b4

Co-authored-by: Mads Marquart <[email protected]>

Update text/3750-cfg-os-version-min.md

35ee570

Co-authored-by: Mads Marquart <[email protected]>

Update text/3750-cfg-os-version-min.md

157b501

Co-authored-by: Mads Marquart <[email protected]>

Update text/3750-cfg-os-version-min.md

0edbe04

Co-authored-by: Mads Marquart <[email protected]>

Update text/3750-cfg-os-version-min.md

cd0e8a9

Co-authored-by: Mads Marquart <[email protected]>

Update text/3750-cfg-os-version-min.md

fb06a58

Co-authored-by: Mads Marquart <[email protected]>

madsmtm mentioned this pull request May 19, 2025

Stabilize #[cfg(version(...))] rust-lang/rust#141137

Closed

3 tasks

ChrisDenton added 2 commits May 20, 2025 09:30

Rename os_version_min to target_version

cf3cd1d

Rename file

482144c

ChrisDenton changed the title ~~RFC: cfg_os_version_min~~ RFC: cfg_target_version May 20, 2025


		Note: Here it would be important to link to documentation showing the `cfg` predicates and the different version strings that are supported.

		# Reference-level explanation

RFC: cfg_target_version #3750

Are you sure you want to change the base?

RFC: cfg_target_version #3750

Uh oh!

Conversation

ChrisDenton commented Dec 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bjorn3 Jan 3, 2025

Choose a reason for hiding this comment

Uh oh!

ChrisDenton Jan 3, 2025

Choose a reason for hiding this comment

Uh oh!

Aloso commented Jan 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisDenton commented Jan 3, 2025

Uh oh!

Aloso commented Jan 3, 2025

Uh oh!

madsmtm left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

madsmtm Jan 5, 2025

Choose a reason for hiding this comment

Uh oh!

madsmtm Jan 5, 2025

Choose a reason for hiding this comment

Uh oh!

madsmtm Jan 5, 2025

Choose a reason for hiding this comment

Uh oh!

ChrisDenton Jan 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

madsmtm Jan 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ChrisDenton commented Jan 27, 2025

Uh oh!

madsmtm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ChrisDenton commented Dec 27, 2024 •

edited

Loading

Aloso commented Jan 3, 2025 •

edited

Loading

madsmtm left a comment •

edited

Loading

ChrisDenton Jan 27, 2025 •

edited

Loading