Android API level needs to be visible in Swift

[grynspan]

Motivation

In Android, new API is guarded by API level. For instance, timespec_get() was introduced with Android API level 29. API level can be determined by checking the value of __ANDROID_API__ defined in the system header <android/api-level.h>.

This value is not visible to Swift, meaning that code that is conditionally dependent on the availability of some API needs to check for it (and provide a fallback path!) in C or C++ rather than in Swift.

Proposed solution

I propose we teach the compiler, when targetting Android, to expose the API level similar to how the Swift language mode and compiler version are exposed:

var ts = timespec()
#if _apiLevel(>=29)
timespec_get(&ts, TIME_UTC)
#else
clock_gettime(CLOCK_REALTIME, &ts)
#endif
return ts

Alternatives considered

• Exposing the API level as a macro would result in it being evaluated too late and the compiler wouldn't be able to ignore the API usage.
• Exposing the API level as the de facto OS version (#available(Android 29, *)) would have a similar problem.
• "Just do it in C" is generally not the solution we want for Swift projects.

Additional information

No response

[grynspan]

@finagolfin @compnerd Could use your thoughts here. :)

[compnerd]

There's another option of mapping OS release to API level, but that isn't very precise either. The difference between the iOS and Android here is that the information is statically available for Android. IIRC the OS check on Darwin was static with mmin-macosx-version was specified and dynamic if the availability was indeterminate. For Android, something like that with a weak linkage in the indeterminate case would be really nice.

[grynspan]

There's another option of mapping OS release to API level, but that isn't very precise either.

See my "alternatives" section, yeah. #available would potentially be evaluated too late to be useful unless Android has weak linking support à la Darwin.

[bc-lee]

For Android, something like that with a weak linkage in the indeterminate case would be really nice.

It is possible. The macro __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ is specifically designed for this purpose. When defined, the NDK treats all symbols unavailable on the current platform as weak, similar to how it's done on Darwin.

For more information, see this guide and refer to the implementation details in android/versioning.h and time.h.

[grynspan]

We'd need some way for the underlying machinery of #available() to query the API level for the running system (i.e. a runtime value, not a compile-time constant.) I think the system property "ro.build.version.sdk" gives us that value?

[bc-lee]

I think so. https://github.com/llvm/llvm-project/blob/5ef02a3fd4758ae1b9151ac581eebd1109b4daad/compiler-rt/lib/builtins/os_version_check.c#L321

[finagolfin]

It's something Android porters like @drodriguez have talked about for years, but nobody got around to adding. Since Android usually builds with the API version in the build triple, it should be easy to pass in at compile time to Swift code, just as it is currently passed in by SwiftPM when compiling C/C++ code with clang and Swift's ClangImporter, which then invoke this code that sets it in clang. So only Swift code is currently oblivious of the Android API used, past time that was remedied.

[finagolfin]

We should assign somebody to work on this: @compnerd, is this something you Browser Company people would add? It all depends on who needs it, whether @marcprux for Skip or you guys or somebody else entirely.

[compnerd]

This is definitely something that would be nice to have. This is similar to the long standing feature request on Windows for availability support. I think that would allow us to surface both of these in the best way possible, but that isn't something that we can take on just right now with the other items that are outstanding.