|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page developing-on-mac.html |
|
44 \title Developing Qt Applications on Mac OS X |
|
45 \brief A overview of items to be aware of when developing Qt applications |
|
46 on Mac OS X |
|
47 \ingroup platform-specific |
|
48 |
|
49 \tableofcontents |
|
50 |
|
51 Mac OS X is a UNIX platform and behaves similar to other Unix-like |
|
52 platforms. The main difference is X11 is not used as the primary windowing |
|
53 system. Instead, Mac OS X uses its own native windowing system that is |
|
54 accessible through the Carbon and Cocoa APIs. Application development on |
|
55 Mac OS X is done using Xcode Tools, an optional install included on every |
|
56 Mac with updates available from \l {http://developer.apple.com}{Apple's |
|
57 developer website}. Xcode Tools includes Apple-modified versions of the GCC |
|
58 compiler. |
|
59 |
|
60 |
|
61 \section1 What Versions of Mac OS X are Supported? |
|
62 |
|
63 As of Qt 4.6, Qt supports Mac OS X versions 10.4 and up. It is usually in |
|
64 the best interest of the developer and user to be running the latest |
|
65 updates to any version. We test internally against Mac OS X 10.4.11 as well |
|
66 as the updated release of Mac OS X 10.5 and Mac OS X 10.6. |
|
67 |
|
68 \section2 Carbon or Cocoa? |
|
69 |
|
70 Historically, Qt has used the Carbon toolkit, which supports 32-bit |
|
71 applications on Mac OS X 10.4 and up. Qt 4.5 and up has support for the Cocoa |
|
72 toolkit, which requires 10.5 and provides 64-bit support. |
|
73 |
|
74 This detail is typically not important to Qt application developers. Qt is |
|
75 cross-platform across Carbon and Cocoa, and Qt applications behave |
|
76 the same way when configured for either one. Eventually, the Carbon |
|
77 version will be discontinued. This is something to keep in mind when you |
|
78 consider writing code directly against native APIs. |
|
79 |
|
80 The current binary for Qt is built in two flavors, 32-bit Carbon and full |
|
81 universal Cocoa (32-bit and 64-bit). If you want a different setup for |
|
82 Qt will use, you must build from scratch. Carbon or Cocoa is chosen when |
|
83 configuring the package for building. The configure process selects Carbon |
|
84 by default, to specify Cocoa use the \c{-cocoa} flag. configure for a |
|
85 64-bit architecture using one of the \c{-arch} flags (see \l{universal |
|
86 binaries}{Universal Binaries}). |
|
87 |
|
88 Currently, Apple's default GCC compiler is used by default (GCC 4.0.1 on |
|
89 10.4 and 10.5, GCC 4.2 on 10.6). You can specify alternate compilers |
|
90 though. For example, on Mac OS X 10.5, Apple's GCC 4.2 is also available |
|
91 and selectable with the configure flag: \c{-platform macx-g++42}. LLVM-GCC |
|
92 support is available by passing in the \c{-platform macx-llvm} flag. GCC |
|
93 3.x will \e not work. Though they may work, We do not support custom-built |
|
94 GCC's. |
|
95 |
|
96 The following table summarizes the different versions of Mac OS X and what |
|
97 capabilities are used by Qt. |
|
98 |
|
99 \table |
|
100 \header |
|
101 \o Mac OS X Version |
|
102 \o Cat Name |
|
103 \o Native API Used by Qt |
|
104 \o Bits available to address memory |
|
105 \o CPU Architecture Supported |
|
106 \o Development Platform |
|
107 \row |
|
108 \o 10.4 |
|
109 \o Tiger |
|
110 \o Carbon |
|
111 \o 32 |
|
112 \o PPC/Intel |
|
113 \o Yes |
|
114 \row |
|
115 \o 10.5 |
|
116 \o Leopard |
|
117 \o Carbon |
|
118 \o 32 |
|
119 \o PPC/Intel |
|
120 \o Yes |
|
121 \row |
|
122 \o 10.5 |
|
123 \o Leopard |
|
124 \o Cocoa |
|
125 \o 32/64 |
|
126 \o PPC/Intel |
|
127 \o Yes |
|
128 \row |
|
129 \o 10.6 |
|
130 \o Snow Leopard |
|
131 \o Cocoa/Carbon |
|
132 \o 32 |
|
133 \o PPC/Intel |
|
134 \o Yes |
|
135 \row |
|
136 \o 10.6 |
|
137 \o Snow Leopard |
|
138 \o Cocoa |
|
139 \o 64 |
|
140 \o Intel |
|
141 \o Yes |
|
142 \endtable |
|
143 |
|
144 Note that building for ppc-64 is not supported on 10.6. |
|
145 |
|
146 \section2 Which One Should I Use? |
|
147 |
|
148 Carbon and Cocoa both have their advantages and disadvantages. Probably the |
|
149 easiest way to determine is to look at the version of Mac OS X you are |
|
150 targetting. If you are starting a new application and can target 10.5 and |
|
151 up, then please consider Cocoa only. If you have an existing application or |
|
152 need to target earlier versions of the operating system and do not need |
|
153 access to 64-bit or newer Apple technologies, then Carbon is a good fit. If |
|
154 your needs fall in between, you can go with a 64-bit Cocoa and 32-bit |
|
155 Carbon universal application with the appropriate checks in your code to |
|
156 choose the right path based on where you are running the application. |
|
157 |
|
158 For Mac OS X 10.6, Apple has started recommending developers to build their |
|
159 applications 64-bit. The main reason is that there is a small speed |
|
160 increase due to the extra registers on Intel CPU's, all their machine |
|
161 offerings have been 64-bit since 2007, and there is a cost for reading all |
|
162 the 32-bit libraries into memory if everything else is 64-bit. If you want |
|
163 to follow this advice, there is only one choice, 64-bit Cocoa. |
|
164 |
|
165 \target universal binaries |
|
166 \section1 Universal Binaries |
|
167 |
|
168 In 2006, Apple begin transitioning from PowerPC (PPC) to Intel (x86) |
|
169 systems. Both architectures are supported by Qt. The release of Mac OS X |
|
170 10.5 in October 2007 added the possibility of writing and deploying 64-bit |
|
171 GUI applications. Qt 4.5 and up supports both the 32-bit (PPC and x86) and |
|
172 64-bit (PPC64 and x86-64) versions of PowerPC and Intel-based systems. |
|
173 |
|
174 Universal binaries are used to bundle binaries for more than one |
|
175 architecture into a single package, simplifying deployment and |
|
176 distribution. When running an application the operating system will select |
|
177 the most appropriate architecture. Universal binaries support the following |
|
178 architectures; they can be added to the build at configure time using the |
|
179 \c{-arch} arguments: |
|
180 |
|
181 \table |
|
182 \header |
|
183 \o Architecture |
|
184 \o Flag |
|
185 \row |
|
186 \o Intel, 32-bit |
|
187 \o \c{-arch x86} |
|
188 \row |
|
189 \o Intel, 64-bit |
|
190 \o \c{-arch x86_64} |
|
191 \row |
|
192 \o PPC, 32-bit |
|
193 \o \c{-arch ppc} |
|
194 \row |
|
195 \o PPC, 64-bit |
|
196 \o \c{-arch ppc64} |
|
197 \endtable |
|
198 |
|
199 If there are no \c{-arch} flags specified, configure builds for the 32-bit |
|
200 architecture, if you are currently on one. Universal binaries were initially |
|
201 used to simplify the PPC to Intel migration. You can use \c{-universal} to |
|
202 build for both the 32-bit Intel and PPC architectures. |
|
203 |
|
204 \note The \c{-arch} flags at configure time only affect how Qt is built. |
|
205 Applications are by default built for the 32-bit architecture you are |
|
206 currently on. To build a universal binary, add the architectures to the |
|
207 CONFIG variable in the .pro file: |
|
208 |
|
209 \code |
|
210 CONFIG += x86 ppc x86_64 ppc64 |
|
211 \endcode |
|
212 |
|
213 |
|
214 \section1 Day-to-Day Application Development on OS X |
|
215 |
|
216 On the command-line, applications can be built using \c qmake and \c make. |
|
217 Optionally, \c qmake can generate project files for Xcode with |
|
218 \c{-spec macx-xcode}. If you are using the binary package, \c qmake |
|
219 generates Xcode projects by default; use \c{-spec macx-gcc} to generate |
|
220 makefiles. |
|
221 |
|
222 The result of the build process is an application bundle, which is a |
|
223 directory structure that contains the actual application executable. The |
|
224 application can be launched by double-clicking it in Finder, or by |
|
225 referring directly to its executable from the command line, i. e. |
|
226 \c{myApp.app/Contents/MacOS/myApp}. |
|
227 |
|
228 If you wish to have a command-line tool that does not use the GUI (e.g., |
|
229 \c moc, \c uic or \c ls), you can tell \c qmake not to execute the bundle |
|
230 creating steps by removing it from the \c{CONFIG} in your \c{.pro} file: |
|
231 |
|
232 \code |
|
233 CONFIG -= app_bundle |
|
234 \endcode |
|
235 |
|
236 |
|
237 \section1 Deployment - "Compile once, deploy everywhere" |
|
238 |
|
239 In general, Qt supports building on one Mac OS X version and deploying on |
|
240 all others, both forward and backwards. You can build on 10.4 Tiger and run |
|
241 the same binary on 10.5 and up. |
|
242 |
|
243 Some restrictions apply: |
|
244 |
|
245 \list |
|
246 \o Some functions and optimization paths that exist in later versions |
|
247 of Mac OS X will not be available if you build on an earlier |
|
248 version of Mac OS X. |
|
249 \o The CPU architecture should match. |
|
250 \o Cocoa support is only available for Mac OS X 10.5 and up. |
|
251 \endlist |
|
252 |
|
253 Universal binaries can be used to provide a smorgasbord of configurations |
|
254 catering to all possible architectures. |
|
255 |
|
256 Mac applications are typically deployed as self-contained application |
|
257 bundles. The application bundle contains the application executable as well |
|
258 as dependencies such as the Qt libraries, plugins, translations and other |
|
259 resources you may need. Third party libraries like Qt are normally not |
|
260 installed system-wide; each application provides its own copy. |
|
261 |
|
262 The most common way to distribute applications is to provide a compressed |
|
263 disk image (.dmg file) that the user can mount in Finder. The Mac |
|
264 deployment tool (macdeployqt) can be used to create the self-contained bundles, and |
|
265 optionally also create a .dmg archive. See the |
|
266 \l{Deploying an Application on Mac OS X}{Mac deployment guide} for more |
|
267 information about deployment. It is also possible to use an installer |
|
268 wizard. More information on this option can be found in |
|
269 \l{http://developer.apple.com/mac/}{Apple's documentation}. |
|
270 */ |
|
271 |