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

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
Line 1: Line 1:
=OS X and and iOS Coding Conventions=
h1. OS X and and iOS Coding Conventions


==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. 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 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. 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 <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 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 &quot;official&amp;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?


* Market Share
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.
* Is Apple still security-patching the version?
* Is it a maintenance burden?


There process of dropping support is gradual:
Gradual loss of quality is ''not'' a goal.<br />QWebKit/WebEngine lives its own life depending on upstream support


* Deploy-only (no binary package support). Compile-from-source is usually not a problem and a good way of testing compatibility.
We would like to move to a &quot;the only version is the current version&amp;quot; world. (This is currently more true on iOS than OS X.)
* 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.<br /> QWebKit/WebEngine lives its own life depending on upstream support
== Xcode version 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.)
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 &quot;wikipedia article&amp;quot;:http://en.wikipedia.org/wiki/Xcode for a versions and requirements overview.


==Xcode version support==
== OS X and iOS code sharing ==
 
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.
 
==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.
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 ==


===<span class="caps">NSA</span>pp vs [NSApplication sharedApplication]===
=== 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 <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 QSysInfo::MacintoshVersion in the Qt source code to see the pattern in use.
 
==Cocoa Touch==

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&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
* 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&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

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

NSApp vs [NSApplication sharedApplication]

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.