Qt wiki will be updated on October 12th 2023 starting at 11:30 AM (EEST) and the maintenance will last around 2-3 hours. During the maintenance the site will be unavailable.
Apple Platforms Coding Conventions: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
h1. OS X and and iOS Coding Conventions | |||
==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. 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 support 32-bit builds. | ||
===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. Cocoa and | Use that instead of calling getters and setters. Cocoa 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 <code>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 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&quot; 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<br />* Market Share<br />* Is Apple still security-patching the version?<br />* Is it a maintenance burden? | ||
* | There process of dropping support is gradual:<br />* Deploy-only (no binary package support). Compile-from-source is usually not a problem and a good way of testing compatibility.<br />* New features may not work on the old(est) platforms<br />* Deprecation in a minor release<br />* Removal in the next release. | ||
* | |||
* | |||
Gradual loss of quality is ''not'' a goal.<br />QWebKit/WebEngine lives its own life depending on upstream support | |||
We would like to move to a "the only version is the current version&quot; world. (This is currently more true on iOS than OS X.) | |||
== 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 "wikipedia article&quot;:http://en.wikipedia.org/wiki/Xcode for a versions and requirements overview. | |||
== OS X and iOS code sharing == | |||
==OS X and iOS 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. | '''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. | ||
Don't use Q_OS_MACX. | |||
OS X and iOS share as much code as possible. This is done via the the static platformsupport library. | OS X and iOS share as much code as possible. This is done via the the static platformsupport library. | ||
==OS X / Cocoa== | == OS X / Cocoa == | ||
=== | === NSApp vs [NSApplication sharedApplication] === | ||
Use [NSApplication sharedApplication]. | Use [NSApplication sharedApplication]. | ||
| Line 62: | Line 53: | ||
'''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 an can save us from compiler errors. | ||
===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 QSysInfo::MacintoshVersion in the Qt source code to see the pattern in use. | ||
Revision as of 10:15, 24 February 2015
h1. OS X and and iOS 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. 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 support 32-bit builds.
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. Cocoa 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 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?
There 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 than OS X.)
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 "wikipedia article":http://en.wikipedia.org/wiki/Xcode for a versions and requirements overview.
OS X and iOS 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.
Don't use Q_OS_MACX.
OS X and iOS share as much code as possible. This is done via the the static platformsupport library.
OS X / Cocoa
Use [NSApplication sharedApplication].
Rationale: While a little longer to type, [NSApplication sharedApplication] is type-safe an can save us from compiler errors.
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 QSysInfo::MacintoshVersion in the Qt source code to see the pattern in use.