OperatingSystem.IsIOS API is problematic

[marek-safar]

Background and Motivation

.NET 6 heavily relies on the platform compatibility analyzer, linker and operating system detection on the mobile platforms. Currently there's a parity between the values returned by OperatingSystem.IsXXX() APIs, the UnsupportedOSPlatform("xxx") and attributes. The target framework moniker (TFM) also uses the same XXX syntax for platform suffix. All the OperatingSystem.IsXXX() APIs are mutually exclusive and at most one of them returns true on a given platform.

Unlike most TFMs the Mac Catalyst has an implicit relationship with the iOS TFM. Application targeting net6.0-maccatalyst may consume library assets that were built with net6.0-ios TFMs. This creates a disparity where this relationship is not captured by the OperatingSystem.IsIOS/IsMacCatalyst APIs and the unavailable Mac Catalyst APIs have to include explicit UnsupportedOSPlatform("maccatalyst") annotations even though they don't target net6.0-maccatalyst directly. Failure to do so would currently be silently ignored and a transitive library consumption will not produce Platform Compatibility Analyzer warnings.

Additionally, libraries targeting net6.0 and including iOS specific logic can easily fall into a trap of guarding the code with OperatingSystem.IsIOS() when the correct condition is OperatingSystem.IsIOS() || OperatingSystem.IsMacCatalyst().

Similarly, in native C / Objective-C / Swift code the platform availability guards implicitly imply the Mac Catalyst as a variant of iOS.

Platform guard example in C

Consider the following C code:

#include <stdio.h>

int main()
{
#if __is_target_os(ios)
    printf("__is_target_os(ios): true\n");
#endif
    if (__builtin_available(iOS 16, *)) {
        printf("__builtin_available iOS 16\n");
    }
    if (__builtin_available(iOS 10, *)) {
        printf("__builtin_available iOS 10\n");
    }
    if (__builtin_available(iOS 16, macCatalyst 11, *)) {
        printf("__builtin_available macCatalyst\n");
    }
}

It can be compiled for Mac Catalyst by running clang -target x86_64-apple-ios13.0-macabi avail.c -o avail and it produces the following output:

__is_target_os(ios): true
__builtin_available iOS 10
__builtin_available macCatalyst

The interpretation is that __is_target_os(...) treats Mac Catalyst as iOS variant. __builtin_available uses the iOS <version> value on Mac Catalyst unless an explict check is specified.

Proposed solutions

Proposal A

• OperatingSystem.IsIOS() would return true on both Mac Catalyst and iOS. In majority of the cases that is what the developer wants to check since Mac Catalyst is supposed to be a superset of iOS. Current runtime checks that do OperatingSystem.IsIOS() || OperatingSystem.IsTvOS() || OperatingSystem.IsMacCatalyst() would be shortened to OperatingSystem.IsIOS() || OperatingSystem.IsTvOS().
• Keep UnsupportedOSPlatform("XXX") consistent with OperatingSystem.IsXXX, both in the Platform Compatibility Analyzer and in linker. Thus specifying UnsupportedOSPlatform("ios") would imply that an API is also unsupported on Mac Catalyst. Duplicate UnsupportedOSPlatform("ios") and UnsupportedOSPlatform("maccatalyst") attributes would coalesce into one.
• For the rare case where you actually want to behave differently on iOS and MacCatalyst you would use a combination of the checks / attributes. An iOS-only API would be decorated with [UnsupportedOSPlatform("maccatalyst")] and runtime check would be !OperatingSystem.IsMacCatalyst(). A MacCatalyst-only API would be decorated with [UnsupportedOSPlatform("ios")] and [SupportedOSPlatform("maccatalyst")] (or similar). Code block guarding specifically for iOS and not Mac Catalyst would use OperatingSystem.IsIOS() && !OperatingSystem.IsMacCatalyst().

Proposal B

• Add OperatingSystem.IsIOSOrMacCatalyst() API with appropriate UnsupportedOSPlatformGuard attributes. This would simplify the checks in code while keeping the OperatingSystem.IsXXX APIs more consistent. There's a potential error for the caller to keep using IsIOS where IsIOSOrMacCatalyst should have been used. Casual observation suggests that most of the IsIOS() API usages in .NET runtime itself would be replaceable with this alternate API since they do IsIOS() || IsMacCatalyst() check anyway.

• Teach the Platform Compatibility analyzer about the additional TFM relationship and enforce additional rules when targeting net6.0-ios and not targeting net6.0-maccatalyst in a library code (ie. adding explicit supported/unsupported MacCatalyst annotations where iOS annotations are present; additional checks for use of the IsIOS() API). [TODO]

Additional design considerations

• Should OperatingSystem.IsXXX map the TFM fallbacks in general?
• Should there be a relation to how RIDs are structured too?
• Should IsLinux() return true on Android?
  Likely not; the API surface is significantly different, there's prior art with Flutter:

  This value is false if the operating system is a specialized version of Linux that identifies itself by a different name, for example Android (see isAndroid).

/cc @terrajobst @jeffhandley for design decisions

Kudos to @filipnavara for the write-up.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

Tagging subscribers to this area: @tannergooding
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

.NET 6 heavily relies on the platform compatibility analyzer, linker and operating system detection on the mobile platforms. Currently there's a parity between the values returned by OperatingSystem.IsXXX() APIs, the UnsupportedOSPlatform("xxx") and attributes. The target framework moniker (TFM) also uses the same XXX syntax for platform suffix. All the OperatingSystem.IsXXX() APIs are mutually exclusive and at most one of them returns true on a given platform.

Unlike most TFMs the Mac Catalyst has an implicit relationship with the iOS TFM. Application targeting net6.0-maccatalyst may consume library assets that were built with net6.0-ios TFMs. This creates a disparity where this relationship is not captured by the OperatingSystem.IsIOS/IsMacCatalyst APIs and the unavailable Mac Catalyst APIs have to include explicit UnsupportedOSPlatform("maccatalyst") annotations even though they don't target net6.0-maccatalyst directly. Failure to do so would currently be silently ignored and a transitive library consumption will not produce Platform Compatibility Analyzer warnings.

Additionally, libraries targeting net6.0 and including iOS specific logic can easily fall into a trap of guarding the code with OperatingSystem.IsIOS() when the correct condition is OperatingSystem.IsIOS() || OperatingSystem.IsMacCatalyst().

Similarly, in native C / Objective-C / Swift code the platform availability guards implicitly imply the Mac Catalyst as a variant of iOS.

Platform guard example in C

Consider the following C code:

#include <stdio.h>

int main()
{
#if __is_target_os(ios)
    printf("__is_target_os(ios): true\n");
#endif
    if (__builtin_available(iOS 16, *)) {
        printf("__builtin_available iOS 16\n");
    }
    if (__builtin_available(iOS 10, *)) {
        printf("__builtin_available iOS 10\n");
    }
    if (__builtin_available(iOS 16, macCatalyst 11, *)) {
        printf("__builtin_available macCatalyst\n");
    }
}

It can be compiled for Mac Catalyst by running clang -target x86_64-apple-ios13.0-macabi avail.c -o avail and it produces the following output:

__is_target_os(ios): true
__builtin_available iOS 10
__builtin_available macCatalyst

The interpretation is that __is_target_os(...) treats Mac Catalyst as iOS variant. __builtin_available uses the iOS <version> value on Mac Catalyst unless an explict check is specified.

Proposed solutions

Proposal A

• OperatingSystem.IsIOS() would return true on both Mac Catalyst and iOS. In majority of the cases that is what the developer wants to check since Mac Catalyst is supposed to be a superset of iOS. Current runtime checks that do OperatingSystem.IsIOS() || OperatingSystem.IsTvOS() || OperatingSystem.IsMacCatalyst() would be shortened to OperatingSystem.IsIOS() || OperatingSystem.IsTvOS().
• Keep UnsupportedOSPlatform("XXX") consistent with OperatingSystem.IsXXX, both in the Platform Compatibility Analyzer and in linker. Thus specifying UnsupportedOSPlatform("ios") would imply that an API is also unsupported on Mac Catalyst. Duplicate UnsupportedOSPlatform("ios") and UnsupportedOSPlatform("maccatalyst") attributes would coalesce into one.
• For the rare case where you actually want to behave differently on iOS and MacCatalyst you would use a combination of the checks / attributes. An iOS-only API would be decorated with [UnsupportedOSPlatform("maccatalyst")] and runtime check would be !OperatingSystem.IsMacCatalyst(). A MacCatalyst-only API would be decorated with [UnsupportedOSPlatform("ios")] and [SupportedOSPlatform("maccatalyst")] (or similar). Code block guarding specifically for iOS and not Mac Catalyst would use OperatingSystem.IsIOS() && !OperatingSystem.IsMacCatalyst().

Proposal B

• Add OperatingSystem.IsIOSOrMacCatalyst() API with appropriate UnsupportedOSPlatformGuard attributes. This would simplify the checks in code while keeping the OperatingSystem.IsXXX APIs more consistent. There's a potential error for the caller to keep using IsIOS where IsIOSOrMacCatalyst should have been used. Casual observation suggests that most of the IsIOS() API usages in .NET runtime itself would be replaceable with this alternate API since they do IsIOS() || IsMacCatalyst() check anyway.

• Teach the Platform Compatibility analyzer about the additional TFM relationship and enforce additional rules when targeting net6.0-ios and not targeting net6.0-maccatalyst in a library code (ie. adding explicit supported/unsupported MacCatalyst annotations where iOS annotations are present; additional checks for use of the IsIOS() API). [TODO]

Additional design considerations

• Should OperatingSystem.IsXXX map the TFM fallbacks in general?
• Should there be a relation to how RIDs are structured too?
• Should IsLinux() return true on Android?
  Likely not; the API surface is significantly different, there's prior art with Flutter:

  This value is false if the operating system is a specialized version of Linux that identifies itself by a different name, for example Android (see isAndroid).

/cc @terrajobst @jeffhandley for design decisions

Kudos to @filipnavara for the write-up.

Author:	marek-safar
Assignees:	-
Labels:	area-System.Runtime, untriaged
Milestone:	-

[jkotas]

My vote would be for Proposal A since it matches the underlying platform model.

[jeffhandley]

/cc @buyaa-n @adamsitnik

[filipnavara]

@terrajobst Was there any traction on this?

[terrajobst]

All the OperatingSystem.IsXXX() APIs are mutually exclusive and at most one of them returns true on a given platform.

While I think that's true today this wasn't an explicit design goal. In fact, we said before that returning true for multiple operating systems should be allowed because it allows us to add "virtual" operating systems like browser where we want to be able to add more specific checks later, such as IsBrowserChromium().

I think modelling MacCatalyst as a variant of iOS makes sense because that's how Apple positioned it. So my preference would be proposal A but instead of teaching the platform compat analzer about this relationship I propose we explicitly declare the model using attributes:

namespace System
{
    public partial class OperatingSystem
    {
        [SupportedOSPlatformGuard("ios")]
        public static bool IsMacCatalyst();
    }
}

This would mean that code that checks for IsMacCatalyst() never has to check for iOS -- this check is now always implied. I'm not sure how this plays for version numbers. If iOS is supposed to map to MacCatalyst versions 1:1 we can add a property to SupportedOSPlatformGuard to indicate that:

namespace System
{
    public partial class OperatingSystem
    {
        [SupportedOSPlatformGuard("ios", MapVersions = true)]
        public static bool IsMacCatalystVersionAtLeast(int major, int minor = 0, int build = 0);
    }
}

Please note that SupportedOSPlatformGuard is a feature we added for .NET 6. It was meant to only decorate user-provided IsXxxx methods. We'd extend the semantics when being applied to the native OperatingSystem.IsXxx APIs to model an actual compat relationsip between platforms such that [UnsupportedOSPlatform("ios")] also implies that it's unsupported on MacCatalyst.

@jeffhandley @buyaa-n, any thoughts?

[filipnavara]

If iOS is supposed to map to MacCatalyst versions 1:1

It is. There are multiple versions available on MacCatalyst (Darwin, macOS, iOS) but this API and Evironment.OSVersion operates on the iOS one (consistent with Apple and documentation).

[jeffhandley]

This is still on my radar to try to field for Preview 7. I expect we'll be able to look into it middle of next week.

[buyaa-n]

Proposal A

I do not completely understand their relation, is iOS is the parent of MacCatalys? iOS supports MacCatalyst but MacCatalyst not support iOS?

[SupportedOSPlatformGuard("ios")]
public static bool IsMacCatalyst();

Interesting solution, makes sense for above relation, but it is not directly comply with Proposal A expectation:
OperatingSystem.IsIOS() || OperatingSystem.IsTvOS() || OperatingSystem.IsMacCatalyst() would be shortened to
OperatingSystem.IsTvOS() || OperatingSystem.IsMacCatalyst() not OperatingSystem.IsIOS() || OperatingSystem.IsTvOS().