diff options
Diffstat (limited to 'doc/src/development/developing-on-mac.qdoc')
| -rw-r--r-- | doc/src/development/developing-on-mac.qdoc | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/doc/src/development/developing-on-mac.qdoc b/doc/src/development/developing-on-mac.qdoc new file mode 100644 index 0000000000..dee6d4d3de --- /dev/null +++ b/doc/src/development/developing-on-mac.qdoc @@ -0,0 +1,269 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page developing-on-mac.html + \title Developing Qt Applications on Mac OS X + \brief A overview of items to be aware of when developing Qt applications + on Mac OS X + \ingroup platform-specific + + \tableofcontents + + Mac OS X is a UNIX platform and behaves similar to other Unix-like + platforms. The main difference is X11 is not used as the primary windowing + system. Instead, Mac OS X uses its own native windowing system that is + accessible through the Carbon and Cocoa APIs. Application development on + Mac OS X is done using Xcode Tools, an optional install included on every + Mac with updates available from \l {http://developer.apple.com}{Apple's + developer website}. Xcode Tools includes Apple-modified versions of the GCC + compiler. + + + \section1 What Versions of Mac OS X are Supported? + + As of Qt 4.6, Qt supports Mac OS X versions 10.4 and up. It is usually in + the best interest of the developer and user to be running the latest + updates to any version. We test internally against Mac OS X 10.4.11 as well + as the updated release of Mac OS X 10.5 and Mac OS X 10.6. + + \section2 Carbon or Cocoa? + + Historically, Qt has used the Carbon toolkit, which supports 32-bit + applications on Mac OS X 10.4 and up. Qt 4.5 and up has support for the Cocoa + toolkit, which requires 10.5 and provides 64-bit support. + + This detail is typically not important to Qt application developers. Qt is + cross-platform across Carbon and Cocoa, and Qt applications behave + the same way when configured for either one. Eventually, the Carbon + version will be discontinued. This is something to keep in mind when you + consider writing code directly against native APIs. + + The current binary for Qt is built in two flavors, 32-bit Carbon and full + universal Cocoa (32-bit and 64-bit). If you want a different setup for + Qt will use, you must build from scratch. Carbon or Cocoa is chosen when + configuring the package for building. The configure process selects Carbon + by default, to specify Cocoa use the \c{-cocoa} flag. configure for a + 64-bit architecture using one of the \c{-arch} flags (see \l{universal + binaries}{Universal Binaries}). + + Currently, Apple's default GCC compiler is used by default (GCC 4.0.1 on + 10.4 and 10.5, GCC 4.2 on 10.6). You can specify alternate compilers + though. For example, on Mac OS X 10.5, Apple's GCC 4.2 is also available + and selectable with the configure flag: \c{-platform macx-g++42}. LLVM-GCC + support is available by passing in the \c{-platform macx-llvm} flag. GCC + 3.x will \e not work. Though they may work, We do not support custom-built + GCC's. + + The following table summarizes the different versions of Mac OS X and what + capabilities are used by Qt. + + \table + \header + \o Mac OS X Version + \o Cat Name + \o Native API Used by Qt + \o Bits available to address memory + \o CPU Architecture Supported + \o Development Platform + \row + \o 10.4 + \o Tiger + \o Carbon + \o 32 + \o PPC/Intel + \o Yes + \row + \o 10.5 + \o Leopard + \o Carbon + \o 32 + \o PPC/Intel + \o Yes + \row + \o 10.5 + \o Leopard + \o Cocoa + \o 32/64 + \o PPC/Intel + \o Yes + \row + \o 10.6 + \o Snow Leopard + \o Carbon + \o 32 + \o PPC/Intel + \o Yes + \row + \o 10.6 + \o Snow Leopard + \o Cocoa + \o 32/64 + \o PPC/Intel + \o Yes + \endtable + + \section2 Which One Should I Use? + + Carbon and Cocoa both have their advantages and disadvantages. Probably the + easiest way to determine is to look at the version of Mac OS X you are + targetting. If you are starting a new application and can target 10.5 and + up, then please consider Cocoa only. If you have an existing application or + need to target earlier versions of the operating system and do not need + access to 64-bit or newer Apple technologies, then Carbon is a good fit. If + your needs fall in between, you can go with a 64-bit Cocoa and 32-bit + Carbon universal application with the appropriate checks in your code to + choose the right path based on where you are running the application. + + For Mac OS X 10.6, Apple has started recommending developers to build their + applications 64-bit. The main reason is that there is a small speed + increase due to the extra registers on Intel CPU's, all their machine + offerings have been 64-bit since 2007, and there is a cost for reading all + the 32-bit libraries into memory if everything else is 64-bit. If you want + to follow this advice, there is only one choice, 64-bit Cocoa. + + \target universal binaries + \section1 Universal Binaries + + In 2006, Apple begin transitioning from PowerPC (PPC) to Intel (x86) + systems. Both architectures are supported by Qt. The release of Mac OS X + 10.5 in October 2007 added the possibility of writing and deploying 64-bit + GUI applications. Qt 4.5 and up supports both the 32-bit (PPC and x86) and + 64-bit (PPC64 and x86-64) versions of PowerPC and Intel-based systems. + + Universal binaries are used to bundle binaries for more than one + architecture into a single package, simplifying deployment and + distribution. When running an application the operating system will select + the most appropriate architecture. Universal binaries support the following + architectures; they can be added to the build at configure time using the + \c{-arch} arguments: + + \table + \header + \o Architecture + \o Flag + \row + \o Intel, 32-bit + \o \c{-arch x86} + \row + \o Intel, 64-bit + \o \c{-arch x86_64} + \row + \o PPC, 32-bit + \o \c{-arch ppc} + \row + \o PPC, 64-bit + \o \c{-arch ppc64} + \endtable + + If there are no \c{-arch} flags specified, configure builds for the 32-bit + architecture, if you are currently on one. Universal binaries were initially + used to simplify the PPC to Intel migration. You can use \c{-universal} to + build for both the 32-bit Intel and PPC architectures. + + \note The \c{-arch} flags at configure time only affect how Qt is built. + Applications are by default built for the 32-bit architecture you are + currently on. To build a universal binary, add the architectures to the + CONFIG variable in the .pro file: + + \code + CONFIG += x86 ppc x86_64 ppc64 + \endcode + + + \section1 Day-to-Day Application Development on OS X + + On the command-line, applications can be built using \c qmake and \c make. + Optionally, \c qmake can generate project files for Xcode with + \c{-spec macx-xcode}. If you are using the binary package, \c qmake + generates Xcode projects by default; use \c{-spec macx-gcc} to generate + makefiles. + + The result of the build process is an application bundle, which is a + directory structure that contains the actual application executable. The + application can be launched by double-clicking it in Finder, or by + referring directly to its executable from the command line, i. e. + \c{myApp.app/Contents/MacOS/myApp}. + + If you wish to have a command-line tool that does not use the GUI (e.g., + \c moc, \c uic or \c ls), you can tell \c qmake not to execute the bundle + creating steps by removing it from the \c{CONFIG} in your \c{.pro} file: + + \code + CONFIG -= app_bundle + \endcode + + + \section1 Deployment - "Compile once, deploy everywhere" + + In general, Qt supports building on one Mac OS X version and deploying on + all others, both forward and backwards. You can build on 10.4 Tiger and run + the same binary on 10.5 and up. + + Some restrictions apply: + + \list + \o Some functions and optimization paths that exist in later versions + of Mac OS X will not be available if you build on an earlier + version of Mac OS X. + \o The CPU architecture should match. + \o Cocoa support is only available for Mac OS X 10.5 and up. + \endlist + + Universal binaries can be used to provide a smorgasbord of configurations + catering to all possible architectures. + + Mac applications are typically deployed as self-contained application + bundles. The application bundle contains the application executable as well + as dependencies such as the Qt libraries, plugins, translations and other + resources you may need. Third party libraries like Qt are normally not + installed system-wide; each application provides its own copy. + + The most common way to distribute applications is to provide a compressed + disk image (.dmg file) that the user can mount in Finder. The Mac + deployment tool (macdeployqt) can be used to create the self-contained bundles, and + optionally also create a .dmg archive. See the + \l{Deploying an Application on Mac OS X}{Mac deployment guide} for more + information about deployment. It is also possible to use an installer + wizard. More information on this option can be found in + \l{http://developer.apple.com/mac/}{Apple's documentation}. +*/ + |