RFC: cfg_target_version

[ChrisDenton]

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

[bjorn3]

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.

[ChrisDenton]

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]

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]

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]

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.

[madsmtm]

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]

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]

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).

[ChrisDenton]

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.

[madsmtm]

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.

[ChrisDenton]

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

[madsmtm]

Nit: Linking a 5 year old commit cannot really be called "current" anymore ;). It's a fine example though, just wish it was more honest. Maybe:

Suggested change

	For example, the [current `Mutex` impl](https://github.com/rust-lang/rust/blob/234099d1d12bef9d6e81a296222fbc272dc51d89/library/std/src/sys/windows/mutex.rs#L1-L20) has a Windows 7 fallback. Users who only ever intend to run their code on newer versions of Windows will still pay a runtime cost for this dynamic API detection.
	For example, when the standard library still supported Windows 7 by default, [the `Mutex` impl](https://github.com/rust-lang/rust/blob/234099d1d12bef9d6e81a296222fbc272dc51d89/library/std/src/sys/windows/mutex.rs#L1-L20) had a Windows 7 fallback. Users who only ever intended to run their code on newer versions of Windows still paid a runtime cost for this dynamic API detection.

[madsmtm]

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.

[madsmtm]

Remark: I want to note here that I want version validation, and I want it everywhere ;).

E.g. writing just #[cfg(os_version_min("macos", "invalid"))] should give an error stating that invalid is not a valid version string, and ideally regardless of what target I am currently compiling for.

[ChrisDenton]

That might work for built-in targets but it can't work for external targets when we don't have the target spec (which admittedly are still unstable but still).

[madsmtm]

I guess I'm doubtful of the benefit of this feature to external targets, but yeah, I'd be fine with not having validation for those.

[madsmtm]

To further the bikeshedding: os_version_min is definitely wrong, it should at the very least be version_min (since it works for libc too, which is not an OS).

But how about the name available?

exftern "C" {
    #[cfg(any(
        available("libc", "x.y.z"),
        available("macos", "10.12"),
    ))]
    fn foo();
}

if cfg!(available("windows", "10.0.10240")) {
    // ...
}

A nice thing about available is that it reads a tiny bit more like English:

#[cfg(version_min("macos", "10.12"))] // configured where version minimum macOS 10.12
#[cfg(available("macos", "10.12"))]   // configured where available macOS 10.12.

While still avoiding the "does cfg!(xyz("macos", "10.12")) mean >10.12 or >=10.12" issue.

This could also tie in nicely with a macro available! that first does the static check, and then falls back to a runtime version check against e.g. gnu_get_libc_version() (not proposing this macro here, and probably not implement-able everywhere either, but just to get the idea across):

if available!("libc", "x.y.z") || available!("macos", "10.12") {
    // ... Dynamically use some new feature or API, maybe with `dlsym` or libloading.
}

(Note: I'm heavily biased by Swift's @available).

[Nemo157]

cfg(available) is confusable with cfg(accessible).

[retep998]

If we wanted parity with cfg(version), we could do something like cfg(target_version("macos", "10.12")). They both follow the >= rule, so it would be good to align their naming scheme.

[ChrisDenton]

To be truly consistent we'd need cfg(version) to be like cfg(version("rust", "1.123")).

But ok, I'll change this (again) to use cfg(target_version). However, if there's more bikeshedding I'll probably wait for lang to decide because it's a pain to update.

[madsmtm]

I think it's fine to leave the name as os_version_min for now, and only change it once we reach a consensus. Just noting the alternatives in the RFC text would be enough.

Also, adding another option: cfg(platform_version("macos", "10.12")).

[ChrisDenton]

Ok I'll leave it pending t-lang feedback but add some of the ideas to the RFC.

Though I do think platform_version, os_version and target_version all sound more or less like synonyms to me.

[traviscross]

Whatever else we do, I'd suggest we drop the _min. That's going to be implied, just as it is for cfg(version("..")).

[ChrisDenton]

I've renamed to target_version as that is, I think, at least closer to the final name and seems to have the most support above. But whether or not that's the final name is still an open question.

[madsmtm]

Another unresolved question to add: How should this work in Cargo [target.'cfg(os_version_min(...))'.dependencies] sections?

[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.