Apple Platforms Coding Conventions

Objective-C

ARC (Automated Reference Counting)

Qt uses manual reference counting, ARC usage is currently prohibited.

Rationale: ARC requires a 64-bit build on macOS prior to macOS Sierra (v10.12). There is little benefit of using ARC for the 64-bit builds only since we still have to maintain the manual reference counting code paths. ARC can be used when Qt no longer supports 32-bit builds or no longer supports versions of macOS prior to 10.12.

Patching the Cocoa runtime

Qt does not patch or polyfill the Cocoa runtime using class_addMethod(). [There are some instances of this in Qt 5.3, but we do not want to expand the usage.]

Rationale: Using this technique to work around OS version differences would be convenient. However, as a library we want to be conservative and don't change the runtime. We also don't want to introduce another abstraction layer in addition to the version abstraction patterns already in Qt.

Use properties and dot notation

Use that instead of calling getters and setters. AppKit and UIKit are doing the same. Use them in Qt's own Objective C classes as well. (We need to check which compiler versions, that we support, still need the synthesize directive + ivar declaration. Ideally, we should move away from that too).

Rationale: This is how Objective C works nowadays. It also adds the possibility of adding properties to classes through categories. Finally, it will ease the transition to ARC when 32-bit support or pre-Sierra macOS support is finally dropped.

OS Versions

We want Qt to work on new OS versions, including pre-releases. As platform developers we are not concerned about "official" support in the project, but would rather see Qt work right away. The main restriction is practical difficulties related to developing and testing on pre-release OS versions.

Dropping support for old versions is done on a semi-regular basis. Inputs are

• Market Share
• Is Apple still security-patching the version?
• Is it a maintenance burden?

The process of dropping support is gradual:

• Deploy-only (no binary package support). Compile-from-source is usually not a problem and a good way of testing compatibility.
• New features may not work on the old(est) platforms
• Deprecation in a minor release
• Removal in the next release.

Gradual loss of quality is not a goal. QWebKit/WebEngine lives its own life depending on upstream support

We would like to move to a "the only version is the current version" world. (This is currently more true on iOS, tvOS, and watchOS than macOS.)

Xcode version support

In general, if we support a given macOS version as a development platform then we support the most recent Xcode available for that version. Refer to the Xcode wikipedia article for a versions and requirements overview.

Code sharing

All Apple platforms (macOS, iOS, tvOS, and watchOS) set Q_OS_DARWIN. macOS sets Q_OS_MACOS. iOS sets Q_OS_iOS. tvOS sets Q_OS_TVOS. watchOS sets Q_OS_WATCHOS. On the qmake side this corresponds to darwin, macos, ios, tvos, and watchos.

Don't use Q_OS_MAC, Q_OS_MACX or Q_OS_OSX (or mac, macx or osx in qmake).

All Apple platforms (macOS, iOS, tvOS, and watchOS) share as much code as possible. This is done via the the static platformsupport library.

macOS / AppKit

NSApp vs [NSApplication sharedApplication]

Use [NSApplication sharedApplication].

Rationale: While a little longer to type, [NSApplication sharedApplication] is type-safe and can save us from compiler errors. NOTE: This may no longer be the case with more recent SDKs.

Deployment

Qt binaries are forward compatible: Compile on 10.X and run on 10.X+.

Qt binaries are backwards compatible: Compile on 10.X and run on prior versions. How far back you can go depends on the Qt version in use. This is accomplished by compile-time and run-time version checks (weak linking). Grep for MAC_OS_X_VERSION_MAX_ALLOWED and QOperatingSystemVersion::MacOS and QOperatingSystemVersion::IOS (QSysInfo::MacintoshVersion is deprecated and should not be used) in the Qt source code to see the pattern in use.