Add min_$TARGET_API_version cfg predicates

[rylev]

This RFC adds various min_$TARGET_API_version cfg predicates which allow users to conditionally compile code based on the minimum supported API version for a particular target platform API such as libc, the windows build version, macOS version, etc.. For example, this allows for conditionally compiling code for Windows 10+ that will not be compiled when targeting older versions of Windows.

Zulip discussion thread
Pre-RFC discourse thread

cc @joshtriplett

Rendered

[rylev]

This RFC could potentially help with preventing accidentally introducing platform API dependencies that break the min_api_version like has happened in rust-lang/rust#80804.

[rylev]

I am currently looking for feedback from folks with perspectives on other OS versioning schemes. This seems like a good solution for Windows and Linux (most likely macOS), but what about others like freeBSD?

[SimonSapin]

This is the first use of >= in cfg, right?

Am I reading the Versioning schema section correctly that the ordering used to resolved these comparison to boolean is not str::cmp despite the syntax using string literals, but a custom target-specific ordering where for example "6.1.7599" < "Windows7" < "6.1.7601"? A classic problem with string ordering is that for example "10" comes before "9".

What’s the default behavior for targets that don’t specify an ordering?

What’s the stability story for this ordering evolving over time? For example if Rust 1.73.0 introduces a support for a "Windows11" value with specific ordering compared to numeric values, what happens to code using it in older compilers?

Should target-specific parsing be fallible, with unknown/invalid values used in cfg causing a compilation error?

[aDotInTheVoid]

Another question, what does versioning on linux based OSs mean? Should we switch on the kernel version, libc version, distro version or something else.

Eg on android, the relevent version is the API version, not the kernel version. Linux distros are unique (afaik) for being the only os where the kernel and other parts of the API are versioned seperatly.

[CryZe]

Yeah it almost sounds like there should be different version keys or so that a target can have.

[rylev]

I must admit I was only thinking about the libc version. What are some examples of changes to the kernel that would not bubble through to changes in libc which the user would like to conditionally compile code on?

What is meant by target_api_version is the platform's API that it exposes for end applications.

[rtyler]

I was summoned by @skade to provide The BSD Perspective ™️ . As far as I can tell in the BSD world this would largely come down to the API changes that happen at a libc level more than anything else, which from a versioning standpoint, typically means a major release number (e.g. 12.x). From that angle, I think the proposal as written looks reasonable.

@yoshuawuyts' suggested iteration feels like it would be more ergonomic for my use, but after I think about it more, I think it would be just as simple to do:

#[cfg(all(target_os="netbsd", target_min_version="9.0"))]

To @aDotInTheVoid's feedback, I'm interpreting the version to imply uname -r, which in BSDs is sufficient to consider kernel + libc, but on my Linux workstation uname -r is 5.9.14-1-default while my "OS version" (/etc/issue) is 20201216 (openSUSE Tumbleweed). My libc version however is 2.32-3.1 (according to the package manager) or 2.32 (according to the library itself).

For the express purposes of this API, I don't think the OS version means anything useful, but I'm sure if you gave that to Rust developers, we'd find some use for it 😆 From a programmatic standpoint,

Personally, I think the api in the target_min_api_version identifier is misleading. If the intent is to capture the version of symbols which are available from the libc or libc-equivalent, I would call the target_sys_min_version or something along those lines. On Linux hosts I would pin that to whatever glibc is, BSDs, whatever OS version is, and same for Windows.

[rylev]

This is the first use of >= in cfg, right?

Yes I believe it is

Am I reading the Versioning schema section correctly

Yes you are. The schema should be controlled through means other than naive string comparison.

What’s the default behavior for targets that don’t specify an ordering?

The RFC states: "Many targets don't support a min_target_api_versison and any min_target_api_version check will return false. " The thought being that it's safer to not compile code when the answer for a check is not really defined rather than to compile the code. Most checks of this should be accompanied by a check for the target_os to ensure that the check makes sense.

What’s the stability story for this ordering evolving over time? For example if Rust 1.73.0 introduces a support for a "Windows11" value with specific ordering compared to numeric values, what happens to code using it in older compilers?

Are you asking if a user has previously used the value "Windows11" which did not exist but now does. This would have previously evaluated to false (presumably with a warning for an unknown value) but now would evaluate to true. This could cause breakage. I wonder if erroring on unknown version strings is the right way to go.

Personally, I think the api in the target_min_api_version identifier is misleading. If the intent is to capture the version of symbols which are available from the libc or libc-equivalent

I think this definition is a bit restrictive as on Windows you would also care about things outside of the CRT like which win32 APIs are available. This does make me wonder if we're not going to find a stable cross platform definition for what target_api_version means.

[rylev]

Cross Platform Challenges

At the core of this question is the fact that Rust binaries typically rely on external symbols to function (unless built with no_std and not using an extern blocks). These symbols are dynamically loaded at runtime and when not available the binary fails to run.

This RFC was motivated by a Windows use case, which has a relatively clear line for when API symbols are introduced. Windows is a monolithic thing with a fairly strict backwards compatibility policy. This means it is relatively easy to know whether an external symbol is guaranteed to be defined by the Windows version number (i.e., the build number).

Other systems might not be as clear for several reasons:

• Removal of APIs: For instance, macOS deprecated and removed carbon APIs in 10.15 meaning that binaries that run on 10.14 that rely on carbon APIs will not run on 10.16.
• Complex versioning: For instance, Linux versions libc and the kernel separately. It was my assumption that the libc version was sufficient for tracking symbol availability, but now I'm not sure.
• Future targets: While it might be possible for us to defined a single number for each current tier 1 target (and some tier 2 ones) that give a clear indication as to what set of symbols are available for use, it is unclear if this will always be the case.

In other words: is it possible to define the set of external, platform-provided symbols a Rust binary relies on with a single number?

[yoshuawuyts]

Removal of APIs: For instance, macOS deprecated and removed carbon APIs in 10.15 meaning that binaries that run on 10.14 that rely on carbon APIs will not run on 10.16.

This point specifically sounds like it could be addressed by something akin to a max_api_version?

[SimonSapin]

What if, instead of a single api_version value with a target-specific ordering, each target may define any number (possibly zero) of version-like values with a custom ordering each?

#[cfg(all(linux, min_kernel_version = "4.0", any(
    all(target_env = "gnu", min_glibc_version = "2.28"), 
    all(target_env = "musl", min_musl_version = "1.1")
)))]

Using different names making it an error to use an undefined value would avoid accidentally comparing "1.1" (which is intended as a musl version number) to a glibc version number.

[rylev]

each target may define any number (possibly zero) of version-like values with a custom ordering each

While this ultimately may be the only way to go, the reason I am trying to avoid this is the proliferation of target specific cfg values. If this can be avoided, we should try to. That being said, this conversation is convincing me that there might not be a single number that can be used cross platform in a meaningful way. Perhaps the next step is to close this RFC and open a new one specifically for Windows (as that was my original motivation) and cite this RFC as a reason for why the cfg predicate item is Windows specific instead of bring cross platform.

[thomcc]

It would be very unfortunate for this RFC to not solve this for macOS and iOS, which have a number of very useful APIs that only exist in certain versions. I know @nvzqz has hit this when working on https://github.com/nvzqz/fruity

[rylev]

I've pushed a new version of the RFC that more closely tracks to what @SimonSapin was suggesting. This gets around all challenges of coming up with a cross platform meaning for min_target_api_version and simply suggests different cfg predicates for the different versioned items in question.

The main challenge with this proposal is the large amount of cfg predicates this may lead to as each versioned item will have its own predicate. This RFC only introduces 4 of them, but the future possibilities hints at there being room for many more. One way around this would be to have a custom syntax for this (e.g., #[cfg(min_api("window_build", "6.0.6000")]), but this might lead to other challenges.

[nvzqz]

Complex versioning: For instance, Linux versions libc and the kernel separately. It was my assumption that the libc version was sufficient for tracking symbol availability, but now I'm not sure.

From my understanding, it's fairly common to invoke syscalls directly in Linux and bypass libc. So it's not only a concern of symbol availability, but also whether the author of a program/library can assume that a syscall will work as expected.

A great example of a similar split is being able to cfg against the Darwin kernel version vs the macOS/iOS/*OS version. There's certain APIs in libsystem that are cleaner to conditionally use if checking kernel version rather than OS version.

[rylev]

@nvzqz Thanks! That's really great context for this. I think everything you've said would be addressed by my latest proposal (assuming we add another cfg option for Darwin kernel version).

[thomcc]

it's fairly common to invoke syscalls directly in Linux and bypass libc

Yeah, seconding this. Several things like futex, perf_event, ... don't have a libc interface, and require you use the syscall directly. Personally, I think there's more of a use case for checking kernel version than libc version (you could always work around a limited libc if you know the kernel version).

Also, what if you wanted to write a hypothetical rust-libc — I could imagine cfg-ing based on a target kernel version would be useful here.

cfg against the Darwin kernel version

Yeah, so, I agree that it's cleaner to check this way — sometimes you know was added in Darwin 19 and it's tedious to look up which macOS/iOS/tvOS/watchOS/etc version it applies to — especially since Big Sur being 11.x complicates the "just add 4" pattern you could use on macOS) but I don't think this is actually a good idea.

While you can query it at runtime (with the kern.version sysctl), there's (AFAIK) no direct runtime API for it, it's not exposed at compile time to C/C++/ObjC/Swift, and stuff like the LC_BUILD_VERSION.minos fields in the MachO file format don't use it — they use the user-facing version.

That is to say: there's a well-defined notion of what "this binary (or code) requires macOS 10.12", but no direct equivalent for Darwin kernel version, and so the compiler would end up needing to map between these, which sounds like a problem (very likely impossible to do without hardcoding the mapping, which would have lots of problems)

Additionally, the fact that the way the version checks work in OS-provided header files on these platforms bothers to list out every version for each platform and not going based a single darwin version feels like a suggestion that we should do the same, if not an indication that either there's a reason for it.

[nagisa]

How would a library set its minimum version? I don't see anything to that effect in this section nor in the reference-level explanation.

[rylev]

This is actually an unanswered question - thanks for bringing it up. The RFC mentions storing this information in the crate metadata but gives no mechanism for doing so. I'm not aware of any existing mechanism that we could use for such a thing. The closest that comes to mind is #![no_std], but having a #![min_windows_build_version] seems like overkill.

If we switch to a dedicated syntax like #[min_version(...)] we could conceivably just store the smallest of those used. Perhaps this is another point in favor of the dedicated syntax.

Originally the proposal was to not have libraries store any information about their minimum supported target. They would simply conditionally compile based on what was passed as the cfg flag through rustc. This was changed at some point, but I'm not sure that was a good idea.

[nagisa]

The min_ prefix in the proposed cfg labels and the >= operator seem duplicate each other in the meaning. Since >= is a new syntax (as is acknowledged later) and would most likely need its own rfc, I think we want to avoid >= in this rfc.

(besides, if we push for >=, what would then the behaviour of #[cfg(min_windows_build_version="6.2.9200")] be?)

[rylev]

The semantics of the min_*_version is that marked code should compile when the set minimum supported build version is at least equal to that version. i.e., if code is marked with #[cfg(min_windows_build_version >= "windows7")], it should compile if the min_windows_build_version is set to "windows10". It has been argued that a plain "=" implies that the code would only compile when the min_windows_build_version matches the version provided exactly.

[ChrisDenton]

The Zulip thread linked up top goes back and forth on >= a couple of times. It might be worth revisiting some of the arguments there to help move the discussion forward and save circling around the same points.

[nagisa]

What would be the expected behaviour in case of invocation such as

rustc --target=x86_64-unknown-linux-gnu --cfg 'min_windows_build_version="6.0.6000"'

(both when no cfgs with min_windows_build_version and when there are some present in the crate code)

[nagisa]

One drawback that comes to mind is that it is possible for users to specify arbitrary foo="x" cfgs today, and so this change (and any future addition for other platforms) as proposed would not be backwards compatible in a strict interpretation of compatibility.

[nagisa]

I would strongly prefer this. Firstly this avoids the can of worms related to backwards compatibility.

As a secondhand benefit something like this could also pave the road to different matching predicates within the version string, much like what we have in cargo. So for instance, crates use semver and so a variety of operators that make sense for semver can be used (rather than just >=):

library = "^1.0"
other_library = ">= 1.0 && <3.34"

If, out there, there's a target that utilizes semantic versioning for itself or its components (I think freebsd is a possible close match here), then utilizing the familiar semver matching algorithms would also make sense for it.

[nagisa]

Specifying a generic mechanism for targets to provide their own versioning schemes, rather than concrete cfgs also sounds like a more productive direction to me. Then the fate of this RFC wouldn't need to linger on us being comfortable with all sorts of versioning schemes proposed for the various targets. Once an RFC with a generic mechanism is merged, we could spend our time on figuring out out the high value versioning cfgs (windows, macos) sooner via other channels (PR FCPs, MCPs etc) even before we know what to do about linux, android or bsds.

[asomers]

Amen. Better to have a single syntax for all operating systems, rather than defining a separate variable name for each.

[nagisa]

Nit: #[cfg(min_windows_build_version >= "6.2.9200"] is missing a closing paren.

[asomers]

I like this. We definitely need some feature like this. If I understand correctly, it would work like this:

1. Applications set min_freebsd_build_version in their build.rs files, either by runtime detection or by fiat.
2. Libraries never set this variable, except for their tests. The compiler forwards it to them based on whatever the application set, and the libraries conditionally compile accordingly.
3. At the bottom of the stack, libc works just like any other library. It conditionally compiles accordingly.

[asomers]

Why does the compiler need to know about each value of the API version string? It seems like the compiler should just forward the version string to each crate as it builds them.

[asomers]

Amen. Better to have a single syntax for all operating systems, rather than defining a separate variable name for each.

[thomcc]

Applications set min_freebsd_build_version in their build.rs files, either by runtime detection or by fiat.
...
At the bottom of the stack, libc works just like any other library. It conditionally compiles accordingly.

This wouldn't work, since the build.rs for the application will run after the build.rs for libc under most circumstances, since the application depends on libc.

At the very least, if thats to change, this would need to be spelled out in the RFC (which I don't think it is? But maybe it's just been too long since I've looked)

[asomers]

Applications set min_freebsd_build_version in their build.rs files, either by runtime detection or by fiat.
...
At the bottom of the stack, libc works just like any other library. It conditionally compiles accordingly.

This wouldn't work, since the build.rs for the application will run after the build.rs for libc under most circumstances, since the application depends on libc.

At the very least, if thats to change, this would need to be spelled out in the RFC (which I don't think it is? But maybe it's just been too long since I've looked)

Oh, I guess I didn't understand correctly. The RFC mentions setting the min_freebsd_build_version in ~/.cargo/config. But IMHO that's not good enough. I think it needs to be controllable by the application being build. Perhaps by a feature flag in Cargo.toml?

[raphaelcohn]

@rylev Could we extend this RFC to be more explicit, and differentiate OS version from libc version? In many BSD derived OSes, this doesn't matter (as the libc is versioned with the OS) but on other platforms, they are not in lock-step.

Further, could we also use this RFC to version any C-like library dependency (ie so)? I've had lots of problems over the years with breaking changes between c libraries wrapped and bound to Rust binaries.

[rylev]

Closing this as I don't currently have time to work on this.

[eholk]

I was tempted to reach for something like this when doing rust-lang/cargo#10322, but ultimately there feature testing seemed like the better approach, since it wasn't exactly clear in which version of Windows 11 the behavior changed.