Apple Platforms Coding Conventions: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
mNo edit summary
 
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
=OS X and and iOS Coding Conventions=
[[Category:iOS]]
[[Category:macOS]]
[[Category:tvOS]]
[[Category:watchOS]]


==Objective-C==
== Objective-C ==


===<span class="caps">ARC</span> (Automated Reference Counting)===
=== ARC (Automated Reference Counting) ===


Qt uses manual reference counting, <span class="caps">ARC</span> usage is currently prohibited.
Qt uses manual reference counting, ARC usage is currently prohibited.


'''Rationale:''' <span class="caps">ARC</span> requires a 64-bit build. There is little benefit of using <span class="caps">ARC</span> for the 64-bit builds only since we still have to maintain the manual reference counting code paths. <span class="caps">ARC</span> can be used when Qt no longer support 32-bit builds.
'''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 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.
'''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. Cocoa and <span class="caps">UIK</span>it 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).
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 <span class="caps">ARC</span> when 32-bit support is finally dropped.
'''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 “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.
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?


There process of dropping support is gradual:
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.<br /> QWebKit/WebEngine lives its own life depending on upstream support
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 than OS X.)
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 OS X 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] ''[en.wikipedia.org]'' for a versions and requirements overview.
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.


==OS X and iOS code sharing==
== Code sharing ==


'''Both''' OS X and iOS set Q_OS_MAC. OS X sets Q_OS_OSX. iOS sets Q_OS_iOS. On the Qmake side this corresponds mac, osx, and ios.
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_MACX.
Don't use Q_OS_MAC, Q_OS_MACX or Q_OS_OSX (or mac, macx or osx in qmake).


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


==OS X / Cocoa==
== macOS / AppKit ==


===<span class="caps">NSA</span>pp vs [NSApplication sharedApplication]===
=== NSApp vs [NSApplication sharedApplication] ===


Use [NSApplication sharedApplication].
Use [NSApplication sharedApplication].


'''Rationale''': While a little longer to type, [NSApplication sharedApplication] is type-safe an can save us from compiler errors.
'''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 <span class="caps">MAC</span>_OS_X_VERSION_MAX_ALLOWED and QSysInfo::MacintoshVersion in the Qt source code to see the pattern in use.
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.
 
==Cocoa Touch==

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

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.