Apple Platforms Coding Conventions: Difference between revisions
No edit summary |
mNo edit summary |
||
| (13 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
[[Category:iOS]] | |||
[[Category:macOS]] | |||
[[Category:tvOS]] | |||
[[Category:watchOS]] | |||
==Objective-C== | == Objective-C == | ||
=== | === ARC (Automated Reference Counting) === | ||
Qt uses manual reference counting, | Qt uses manual reference counting, ARC usage is currently prohibited. | ||
'''Rationale:''' | '''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=== | === 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.] | 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 | '''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 properties and dot notation === | ||
Use that instead of calling getters and setters. | 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 | '''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== | == OS Versions == | ||
We want Qt to work on new OS versions, including pre-releases. As platform developers we are not concerned about | 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 | Dropping support for old versions is done on a semi-regular basis. Inputs are | ||
* Market Share | * Market Share | ||
* Is Apple still security-patching the version? | * Is Apple still security-patching the version? | ||
* Is it a maintenance burden? | * 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. | * 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 | * New features may not work on the old(est) platforms | ||
| Line 38: | Line 39: | ||
* Removal in the next release. | * Removal in the next release. | ||
Gradual loss of quality is ''not'' a goal. | 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 | 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== | == Xcode version support == | ||
In general, if we support a given | 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 [http://en.wikipedia.org/wiki/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]. | Use [NSApplication sharedApplication]. | ||
'''Rationale''': While a little longer to type, [NSApplication sharedApplication] is type-safe | '''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=== | === Deployment === | ||
Qt binaries are ''forward compatible'': Compile on 10.X and run on 10.X+. | 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 | 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. | ||
Latest revision as of 21:08, 24 August 2018
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
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.