Bug 1803775 - Update macOS supported SDKs documentation. r=spohl DONTBUILD

[gecko.git] / widget / cocoa / docs / sdks.md

# A primer on macOS SDKs\r
\r
## Overview\r
\r
A macOS SDK is an on-disk directory that contains header files and meta information for macOS APIs.\r
Apple distributes SDKs as part of the Xcode app bundle. Each Xcode version comes with one macOS SDK,\r
the SDK for the most recent released version of macOS at the time of the Xcode release.\r
The SDK is located at `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk`.\r
\r
Compiling Firefox for macOS requires a macOS SDK. The build system uses the SDK from Xcode.app by\r
default, and you can select a different SDK using the `mozconfig` option `--with-macos-sdk`:\r
\r
```text\r
ac_add_options --with-macos-sdk=/Users/username/SDKs/MacOSX11.3.sdk\r
```\r
\r
## Supported SDKs\r
\r
First off, Firefox runs on 10.12 and above. This is called the "minimum deployment target" and is\r
independent of the SDK version.\r
\r
Our official Firefox builds compiled in CI (continuous integration) currently use the 11.3 SDK (last updated in [bug 1788854](https://bugzilla.mozilla.org/show_bug.cgi?id=1788854)). This is also the minimum supported SDK version for local builds.\r
\r
Compiling with different SDKs breaks from time to time. Such breakages should be [reported in Bugzilla](https://bugzilla.mozilla.org/enter_bug.cgi?blocked=mach-busted&bug_type=defect&cc=:spohl,:mstange&component=General&form_name=enter_bug&keywords=regression&op_sys=macOS&product=Firefox%20Build%20System&rep_platform=All) and fixed quickly.\r
\r
## Obtaining SDKs\r
\r
Sometimes you need an SDK that's different from the one in your Xcode.app, for example\r
to check whether your code change breaks building with other SDKs, or to verify the\r
runtime behavior with the SDK used for CI builds.\r
\r
The easy but slightly questionable way to obtain an SDK is to download it from a public github repo.\r
\r
Here's another option:\r
\r
 1. Have your Apple ID login details ready, and bring enough time and patience for a 5GB download.\r
 2. Check [these tables in the Xcode wikipedia article](https://en.wikipedia.org/wiki/Xcode#Xcode_7.0_-_10.x_(since_Free_On-Device_Development))\r
    and find an Xcode version that contains the SDK you need.\r
 3. Look up the Xcode version number on [xcodereleases.com](https://xcodereleases.com/) and click the Download link for it.\r
 4. Log in with your Apple ID. Then the download should start.\r
 5. Wait for the 5GB Xcode_*.xip download to finish.\r
 6. Open the downloaded xip file. This will extract the Xcode.app bundle.\r
 7. Inside the app bundle, the SDK is at `Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk`.\r
\r
## Effects of the SDK version\r
\r
An SDK only contains declarations of APIs. It does not contain the implementations for these APIs.\r
\r
The implementation of an API is provided by the OS that the app runs on. It is supplied at runtime,\r
when your app starts up, by the dynamic linker. For example, the AppKit implementation comes\r
from `/System/Library/Frameworks/AppKit.framework` from the OS that the app is run on, regardless\r
of what SDK was used when compiling the app.\r
\r
In other words, building with a macOS SDK of a higher version doesn't magically make new APIs available\r
when running on older versions of macOS. And, conversely, building with a lower macOS SDK doesn't limit\r
which APIs you can use if your app is run on a newer version of macOS, assuming you manage to convince the\r
compiler to accept your code.\r
\r
The SDK used for building an app determines three things:\r
\r
 1. Whether your code compiles at all,\r
 2. which range of macOS versions your app can run on (available deployment targets), and\r
 3. certain aspects of runtime behavior.\r
\r
The first is straightforward: An SDK contains header files. If you call an API that's not declared\r
anywhere - neither in a header file nor in your own code - then your compiler will emit an error.\r
(Special case: Calling an unknown Objective-C method usually only emits a warning, not an error.)\r
\r
The second aspect, available deployment targets, is usually not worth worrying about:\r
SDKs have large ranges of supported macOS deployment targets.\r
For example, the 10.15 SDK supports running your app on macOS versions all the way back to 10.6.\r
This information is written down in the SDK's `SDKSettings.plist`.\r
\r
The third aspect, varying runtime behavior, is perhaps the most insidious and surprising aspect, and is described\r
in the next section.\r
\r
## Runtime differences based on macOS SDK version\r
\r
When a new version of macOS is released, existing APIs can change their behavior.\r
These changes are usually described in the AppKit release notes:\r
\r
 - [macOS 10.15 release notes](https://developer.apple.com/documentation/macos_release_notes/macos_catalina_10_15_release_notes?language=objc)\r
 - [macOS 10.14 AppKit release notes](https://developer.apple.com/documentation/macos_release_notes/macos_mojave_10_14_release_notes/appkit_release_notes_for_macos_10_14?language=objc)\r
 - [macOS 10.13 AppKit release notes](https://developer.apple.com/library/archive/releasenotes/AppKit/RN-AppKit/)\r
 - [macOS 10.12 and older AppKit release notes](https://developer.apple.com/library/archive/releasenotes/AppKit/RN-AppKitOlderNotes/)\r
\r
Sometimes, these differences in behavior have the potential to break existing apps. In those instances,\r
Apple often provides the old (compatible) behavior until the app is re-built with the new SDK, expecting\r
developers to update their apps so that they work with the new behavior, at the same time as\r
they update to the new SDK.\r
\r
Here's an [example from the 10.13 release notes](https://developer.apple.com/library/archive/releasenotes/AppKit/RN-AppKit/#10_13NSCollectionView%20Responsive%20Scrolling):\r
\r
> Responsive Scrolling in NSCollectionViews is enabled only for apps linked on or after macOS 10.13.\r
\r
Here, "linked on or after macOS 10.13" means "linked against the macOS 10.13 SDK or newer".\r
\r
Apple's expectation is that you upgrade to the new macOS version when it is released, download a new\r
Xcode version when it is released, synchronize these updates across the machines of all developers\r
that work on your app, use the SDK in the newest Xcode to compile your app, and make changes to your\r
app to be compatible with any behavior changes whenever you update Xcode.\r
This expectation does not always match reality. It definitely doesn't match what we're doing with Firefox.\r
\r
For Firefox, SDK-dependent compatibility behaviors mean that developers who build Firefox locally\r
can see different runtime behavior than the users of our CI builds, if they use a different SDK than\r
the SDK used in CI.\r
That is, unless we change the Firefox code so that it has the same behavior regardless of SDK version.\r
Often this can be achieved by using APIs in a way that's more in line with the API's recommended use.\r
\r
For example, we've had cases of\r
[broken placeholder text in search fields](https://bugzilla.mozilla.org/show_bug.cgi?id=1273106),\r
[missing](https://bugzilla.mozilla.org/show_bug.cgi?id=941325) or [double-drawn focus rings](https://searchfox.org/mozilla-central/rev/9ad88f80aeedcd3cd7d7f63be07f577861727054/widget/cocoa/nsNativeThemeCocoa.mm#149-169),\r
[a startup crash](https://bugzilla.mozilla.org/show_bug.cgi?id=1516437),\r
[fully black windows](https://bugzilla.mozilla.org/show_bug.cgi?id=1494022),\r
[fully gray windows](https://bugzilla.mozilla.org/show_bug.cgi?id=1576113#c4),\r
[broken vibrancy](https://bugzilla.mozilla.org/show_bug.cgi?id=1475694), and\r
[broken colors in dark mode](https://bugzilla.mozilla.org/show_bug.cgi?id=1578917).\r
\r
In most of these cases, the breakage was either very minor, or it was caused by Firefox doing things\r
that were explicitly discouraged, like creating unexpected NSView hierarchies, or relying on unspecified\r
implementation details. (With one exception: In 10.14, HiDPI-aware `NSOpenGLContext` rendering in\r
layer-backed windows simply broke.)\r
\r
And in all of these cases, it was the SDK-dependent compatibility behavior that protected our users from being\r
exposed to the breakage. Our CI builds continued to work because they were built with an older SDK.\r
\r
We have addressed all known cases of breakage when building Firefox with newer SDKs.\r
I am not aware of any current instances of this problem as of this writing (June 2020).\r
\r
For more information about how these compatibility tricks work,\r
read the [Overriding SDK-dependent runtime behavior](#overriding-sdk-dependent-runtime-behavior) section.\r
\r
## Supporting multiple SDKs\r
\r
As described under [Supported SDKs](#supported-sdks), Firefox can be built with a wide variety of SDK versions.\r
\r
This ability comes at the cost of some manual labor; it requires some well-placed `#ifdefs` and\r
copying of header definitions.\r
\r
Every SDK defines the macro `MAC_OS_X_VERSION_MAX_ALLOWED` with a value that matches the SDK version,\r
in the SDK's `AvailabilityMacros.h` header. This header also defines version constants like `MAC_OS_X_VERSION_10_12`.\r
For example, I have a version of the 10.12 SDK which contains the line\r
\r
```cpp\r
#define MAC_OS_X_VERSION_MAX_ALLOWED MAC_OS_X_VERSION_10_12_4\r
```\r
\r
The name `MAC_OS_X_VERSION_MAX_ALLOWED` is rather misleading; a better name would be\r
`MAC_OS_X_VERSION_MAX_KNOWN_BY_SDK`. Compiling with an old SDK *does not* prevent apps from running\r
on newer versions of macOS.\r
\r
With the help of the `MAC_OS_X_VERSION_MAX_ALLOWED` macro, we can make our code adapt to the SDK that's\r
being used. Here's [an example](https://searchfox.org/mozilla-central/rev/9ad88f80aeedcd3cd7d7f63be07f577861727054/toolkit/xre/MacApplicationDelegate.mm#345-351) where the 10.14 SDK changed the signature of\r
[an `NSApplicationDelegate` method](https://developer.apple.com/documentation/appkit/nsapplicationdelegate/1428471-application?language=objc):\r
\r
```objc++\r
- (BOOL)application:(NSApplication*)application\r
    continueUserActivity:(NSUserActivity*)userActivity\r
#if defined(MAC_OS_X_VERSION_10_14) && MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_14\r
      restorationHandler:(void (^)(NSArray<id<NSUserActivityRestoring>>*))restorationHandler {\r
#else\r
      restorationHandler:(void (^)(NSArray*))restorationHandler {\r
#endif\r
  ...\r
}\r
```\r
\r
We can also use this macro to supply missing API definitions in such a way that\r
they don't conflict with the definitions from the SDK.\r
This is described in the "Using macOS APIs" document, under [Using new APIs with old SDKs](./macos-apis.html#using-new-apis-with-old-sdks).\r
\r
## Overriding SDK-dependent runtime behavior\r
\r
This section contains some more details on the compatibility tricks that cause different runtime\r
behavior dependent on the SDK, as described in\r
[Runtime differences based on macOS SDK version](#runtime-differences-based-on-macos-sdk-version).\r
\r
### How it works\r
\r
AppKit is the one system framework I know of that employs these tricks. Let's explore how AppKit makes this work,\r
by going back to the [NSCollectionView example](https://developer.apple.com/library/archive/releasenotes/AppKit/RN-AppKit/#10_13NSCollectionView%20Responsive%20Scrolling) from above:\r
\r
> Responsive Scrolling in NSCollectionViews is enabled only for apps linked on or after macOS 10.13.\r
\r
For each of these SDK-dependent behavior differences, both the old and the new behavior are implemented\r
in the version of AppKit that ships with the new macOS version.\r
At runtime, AppKit selects one of the behaviors based on the SDK version, with a call to\r
`_CFExecutableLinkedOnOrAfter()`. This call checks the SDK version of the main executable of the\r
process that's running AppKit code; in our case that's the `firefox` or `plugin-container` executable.\r
The SDK version is stored in the mach-o headers of the executable by the linker.\r
\r
One interesting design aspect of AppKit's compatibility tricks is the fact that most of these behavior differences\r
can be toggled with a "user default" preference.\r
For example, the "responsive scrolling in NSCollectionViews" behavior change can be controlled with\r
a user default with the name "NSCollectionViewPrefetchingEnabled".\r
The SDK check only happens if "NSCollectionViewPrefetchingEnabled" is not set to either YES or NO.\r
\r
More precisely, this example works as follows:\r
\r
 - `-[NSCollectionView prepareContentInRect:]` is the function that supports both the old and the new behavior.\r
 - It calls `_NSGetBoolAppConfig` for the value "NSCollectionViewPrefetchingEnabled", and also supplies a "default\r
   value function".\r
 - If the user default is not set, the default value function is called. This function has the name\r
   `NSCollectionViewPrefetchingEnabledDefaultValueFunction`.\r
 - `NSCollectionViewPrefetchingEnabledDefaultValueFunction` calls `_CFExecutableLinkedOnOrAfter(13)`.\r
\r
You can find many similar toggles if you list the AppKit symbols that end in `DefaultValueFunction`,\r
for example by executing `nm /System/Library/Frameworks/AppKit.framework/AppKit | grep DefaultValueFunction`.\r
\r
### Overriding SDK-dependent runtime behavior\r
\r
You can set these preferences programmatically, in a way that `_NSGetBoolAppConfig()` can pick them up,\r
for example with [`registerDefaults`](https://developer.apple.com/documentation/foundation/nsuserdefaults/1417065-registerdefaults?language=objc)\r
or like this:\r
\r
```objc++\r
[[NSUserDefaults standardUserDefaults] setBool:YES forKey:@"NSViewAllowsRootLayerBacking"];\r
```\r
\r
The AppKit release notes mention this ability but ask for it to only be used for debugging purposes:\r
\r
> In some cases, we provide defaults (preferences) settings which can be used to get the old or new behavior,\r
> independent of what system an application was built against. Often these preferences are provided for\r
> debugging purposes only; in some cases the preferences can be used to globally modify the behavior\r
> of an application by registering the values (do it somewhere very early, with `-[NSUserDefaults registerDefaults:]`).\r
\r
It's interesting that they mention this at all because, as far as I can tell, none of these values are documented.\r