API Availability and Target Conditionals

Wed, Oct 30, 2019

Writing code for multiple Apple platforms can be tricky, this post aims to provide some guidance and explanations for ways to write code that works on different Apple platforms (iOS, macOS, watchOS, tvOS) and different versions of SDKs, and the OSes at runtime.

Target conditionals

First, let’s take a look at how to tell apart the OS you are compiling for at build time, using the preprocessor (in case of Objective-C) or compilation conditions (Swift).

Swift

In Swift checking the OS you are building for at comile time is done using compilation conditionals and specific platform condition functions:

The os() function can be used to check for the OS the code is compiled for, it takes one argument, which is the operating system name (not quoted). Possible operating system names at the time of writing are macOS, iOS, tvOS, watchOS and Linux.

For example:

#if os(macOS)
    // This code is only compiled for macOS
#elseif os(iOS) || os(tvOS)
    // This code is only compiled for iOS or tvOS
#endif

Of course sometimes you need to check if you are running the simualtor or not, to do that there is the targetEnvironment() function. It takes one argument, which is the target environment name (not quoted). Possible values are simulator and macCatalyst (since Swift 5.1).

#if os(iOS) && targetEnvironment(simulator)
    // This code is only compiled for the iOS simulator
#endif

Objective-C, C and C++

For Objective-C, C and C++ conditional compilation is handled by the preprocessor. Apple provides the TargetConditionals.h header which contains specific defines for this.

This header has a lot of defines, I will only list the most useful ones here:

TARGET_OS_OSX: Compiling for macOS
TARGET_OS_IOS: Compiling for iOS
TARGET_OS_TV: Compiling for tvOS
TARGET_OS_WATCH: Compiling for watchOS
TARGET_OS_MACCATALYST: Compiling for Catalyst
TARGET_OS_SIMULATOR: Compiling for Simulator

For example:

#if TARGET_OS_OSX
    // This code is only compiled for macOS
#elif TARGET_OS_IOS || TARGET_OS_TV
    // This code is only compiled for iOS or tvOS
#endif

To check if compiling for the simulator, just use the TARGET_OS_SIMULATOR define:

#if TARGET_OS_IOS && TARGET_OS_SIMULATOR
    // This code is only compiled for the iOS simulator
#endif

Note that there is a TARGET_OS_MAC define, while this sounds like it will be true only for macOS, it is actually true for all Darwin OSes including iOS and tvOS. Another define which can be confusing is the TARGET_OS_IPHONE, which is actually true for all “mobile” platforms, so iOS, tvOS, watchOS and Catalyst.

Clang-specific preprocessor extensions

Since Clang 6.0 or Xcode 9.3 (r320734) Clang has preprocessor extensions similar to the Swift condition functions which can be used to achieve the same as with the target conditional defines above.

To check the OS code is compiled for, there is the __is_target_os() preprocessor macro, which takes a single argument, the operating system name. Possible values for Apple OSes are macOS, iOS, tvOS, watchOS.

For example:

#if __is_target_os(macOS)
    // This code is only compiled for macOS
#elif __is_target_os(iOS) || __is_target_os(tvOS)
    // This code is only compiled for iOS or tvOS
#endif

To check what environement the code is compiled for, similar to Swift there is the __is_target_environment() preprocessor macro, which takes as argument the environment name. Possible values are simulator and macabi (Catalyst).

#if __is_target_os(iOS) && __is_target_environment(simulator)
    // This code is only compiled for the iOS simulator
#endif

API availability

Something that usually is closely related to above discussed conditional compilation is the need to handle API availability gracefully. There are various aspects to consider about API availability, one is API availability at runtime, another is API availability at compile time depending on the used SDK version.

What is API availability?

API availability, as the name suggests, means if a specific API (function, class, method, etc.) is actually available.

macOS, iOS, tvOS and watchOS handle API availability in the same way, when a new API is introduced it is annotate with a specific macro that indicates the availability of that API. The macro expands to annotations for the API that indicate how the linker is expected to handle linking to it and can provide additional warnings or errors during compilation when using a deprecated API or trying to use a “too new” API in an application set to run on older appleOS versions that lack this API.

This sounds all very abstract and complex, so let’s have a look at this using an example, the clock_gettime() function. If we look at the manpage for clock_gettime we can see that it was introduced in macOS 10.12:

HISTORY
     These functions first appeared in Mac OSX 10.12

So let’s have a look at how the header declares this function:

__CLOCK_AVAILABILITY
int clock_gettime(clockid_t __clock_id, struct timespec *__tp);

So these functions are annotate with __CLOCK_AVAILABILITY, which expands to:

__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)

So to be more precise than what the man page tells us, this API is available since macOS 10.12, iOS 10.0, tvOS 10.0 and watchOS 3.0, great!

Of course that still doesn’t provide the full story, to understand what exactly the availability macros do, let’s have a look at the header defining those, Availability.h. Checking this header, we can see that these macros actually expand to (indirectly using a other macros) use of the availability attribute. I recommend reading this for all the details about how exactly this works. The most important takeaway for the purpose of this article is the following:

A declaration can typically be used even when deploying back to a platform version prior to when the declaration was introduced. When this happens, the declaration is weakly linked, as if the weak_import attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.

Note that in addition to the Availability.h header, there is the AvailabilityMacros.h header which works similar to the Availability.h header. Depending on the Framework, it might use either the Availability.h or the older AvailabilityMacros.h header.

Checking API availability at runtime

Now let’s see how we can use such a “partially” avaialble function:

#include <stdio.h>
#include <time.h>

int main(int argc, char const *argv[])
{
    struct timespec value;
    if (clock_gettime(CLOCK_REALTIME, &value) == 0) {
        printf("Realtime seconds: %ld\n", value.tv_sec);
    }
}

If we now compile this targeting macOS 10.14 like that, it just works as expected:

$ clang --target=x86_64-apple-macosx10.14 -Wunguarded-availability availability.c && ./a.out

Realtime seconds: 1572996298

But if we were to try to compile targeting macOS 10.10, we would get a warning:

$ clang --target=x86_64-apple-macosx10.10 -Wunguarded-availability availability.c && ./a.out
availability.c:7:9: warning: 'clock_gettime' is only available on macOS 10.12 or newer
      [-Wunguarded-availability]
    if (clock_gettime(CLOCK_REALTIME, &value) == 0) {
        ^~~~~~~~~~~~~
[…]/usr/include/time.h:178:5: note: 
      'clock_gettime' has been marked as being introduced in macOS 10.12 here, but the deployment target is macOS 10.10.0
[…]
Realtime seconds: 1572996508

The -Wunguarded-availability flag is what causes the compiler to emit this warning. For APIs available since macOS 10.13, iOS 11, watchOS 4 and tvOS 11 you will get these warnings even without specifying this flag, as there is a new flag, -Wunguarded-availability-new which is enabled by default in recent Clang/Xcode versions.

As the name of the warning already gives it away, it only warns about “unguarded” availability, which implies we can “guard” such API usage. There are two ways how this can be done.

Checking the symbols address

The “old” way to check if a partially available function is available would be to check its address:

if (&clock_gettime == NULL) {
    // clock_gettime is not available!
}

Not only is this a bit weird to read, it has some downsides:

The compiler will still warn about this
Objective-C methods and classes can’t easily be checked this way
It is cumbersome to check all relevant symbols this way

Using the availability helper

Fortunately since some time there is a bette way to handle this! In fact, the compiler would already points this out in the partial availability warning:

note: enclose 'clock_gettime' in a __builtin_available check to silence this warning

So let’s do that:

#include <stdio.h>
#include <time.h>

int main(int argc, char const *argv[])
{
    struct timespec value;
    if (__builtin_available(macOS 10.12, *)) {
        if (clock_gettime(CLOCK_REALTIME, &value) == 0) {
            printf("Realtime seconds: %ld\n", value.tv_sec);
        }
    } else {
        // clock_gettime not available!
        return 1;
    }
}

And now it will compile without warning again! On macOS at least, that is. We can check multiple platform versions just by listing them all:

if (__builtin_available(macOS 10.12, iOS 10.0, *)) {
    // Running on macOS 10.12 or iOS 10.0 or higher
}

The star at the end is mandatory and means “all other platforms”. So the previous check that just listed macOS would still compile for iOS and crash at runtime when ran on iOS versions lower than iOS 10 which lack clock_gettime. So take care to cover all cases where the code will run in your availability check!

In Objective-C there is the @available helper which looks a bit nicer than the longer version from C but is used in the exact same way:

if (@available(macOS 10.12, iOS 10.0, *)) {
    // Running on macOS 10.12 or iOS 10.0 or higher
}

In Swift there is #available, again the usage is the same except for the different name:

if #available(macOS 10.12, iOS 10.0, *) {
    // Running on macOS 10.12 or iOS 10.0 or higher
}

Note that negating the check or using it together with any other condition is not supported and does not properly guards availability!

Additionally keep in mind that this is a runtime check, so using APIs inside a availability check that are missing in the current SDK version that is compiled with is still an error. To support multiple SDK versions, see the next section for how to check at compile-time!

Checking API availability at compile-time

Sometimes it is necessary to check the availability of a specific API at compile-time, for example when you want to remain compatible with multiple Apple SDKs, where some versions offer new API that you want to use and some versions lack this API.

In the previous section I already mentioned two headers, Availability.h and AvailabilityMacros.h. These headers define two important macros:

__<OS-VARIANT>_VERSION_MAX_ALLOWED: Indicates the maximum version that we are allowed to use APIs from.
__<OS-VARIANT>_VERSION_MIN_REQUIRED: Indicates the minimum required version that we are allowed to use APIs from.

The <OS-VARIANT> needs to be replaced with the OS variant we want to check for and can be MAC_OS_X, IPHONE_OS, TV_OS or WATCH_OS.

The above sounds quite abstract so lets illustrate it with a example. Suppose we have a new API introduced for macOS 10.12, so it is first present in the macOS 10.12 SDK. If we were to compile with that SDK, the __MAC_OS_X_VERSION_MAX_ALLOWED macro is automatically set to the version of the SDK, as that is the maximum macOS version that we can use APIs from, we cannot ever use any APIs newer than the SDK we are using because those are simply not declared. So in case of the 10.12 SDK, __MAC_OS_X_VERSION_MAX_ALLOWED will be 101200.

If we want to stay compatible with older SDKs, we can use the following preprocessor macros:

#include <Availability.h>
#if (TARGET_OS_OSX && __MAC_OS_X_VERSION_MAX_ALLOWED >= 101200)
    if (@available(macOS 10.12, *)) {
        // Use API available since macOS 10.12 SDK
    } else {
        // Fallback to some other API available in 10.11 and older SDKs
    }
#else
    // Fallback to some other API available in 10.11 and older SDKs
#endif

Note that there are defines for the specific appleOS versions in the availability headers, like __MAC_10_12 so it is tempting to write __MAC_OS_X_VERSION_MAX_ALLOWED >= __MAC_10_12 but this will not work because lower SDK versions, like for example the macOS 10.11 SDK will not have the define for higher macOS versions like macOS 10.12!

What is important to note is that the preprocessor checks are done at compile-time, so proper availability handling at runtime is still needed, see the previous section for details about that!

The second macro, __<OS-VARIANT>_VERSION_MIN_REQUIRED, is useful when you have legacy code that you want to disable when targeting recent enough appleOS versions. Suppose we have function needed for macOS <= 10.11, we can easily disable that when targeting macOS 10.12 or higher by using the __MAC_OS_X_VERSION_MIN_REQUIRED macro:

#include <Availability.h>
#if (TARGET_OS_OSX && __MAC_OS_X_VERSION_MIN_REQUIRED <= 101100)
    void compat_stuff_for_1011() {
        // ...
    }
#endif

Of course a lot of other and more complex scenarios are possible with more complex checks, but I won’t cover all of the possibilities here.

Note that the AvailabilityMacros.h header defines MAC_OS_X_VERSION_MIN_REQUIRED without the two leading underscores, but the Availability.h header does not define those. Both define the version with the leading underscores so to prevent confusing code I would recommend to not use the version without the leading underscores.

Note that the above only works for C/C++/Objective-C code, in Swift there is currently no way to check the SDK at compile-time.