--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/deployment/deployment.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,1583 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** 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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page deployment.html
+ \title Deploying Qt Applications
+
+ Deploying an Qt application does not require any C++
+ programming. All you need to do is to build Qt and your
+ application in release mode, following the procedures described in
+ this documentation. We will demonstrate the procedures in terms of
+ deploying the \l {tools/plugandpaint}{Plug & Paint} application
+ that is provided in Qt's examples directory.
+
+ \section1 Static vs. Shared Libraries
+
+ There are two ways of deploying an application:
+
+ \list
+ \o Static Linking
+ \o Shared Libraries (Frameworks on Mac)
+ \endlist
+
+ Static linking results in a stand-alone executable. The advantage
+ is that you will only have a few files to deploy. The
+ disadvantages are that the executables are large and with no
+ flexibility (i.e a new version of the application, or of Qt, will
+ require that the deployment process is repeated), and that you
+ cannot deploy plugins.
+
+ To deploy plugin-based applications, you can use the shared
+ library approach. Shared libraries also provide smaller, more
+ flexible executables. For example, using the shared library
+ approach, the user is able to independently upgrade the Qt library
+ used by the application.
+
+ Another reason why you might want to use the shared library
+ approach, is if you want to use the same Qt libraries for a family
+ of applications. In fact, if you download the binary installation
+ of Qt, you get Qt as a shared library.
+
+ The disadvantage with the shared library approach is that you
+ will get more files to deploy. For more information, see
+ \l{sharedlibrary.html}{Creating Shared Libraries}.
+
+ \section1 Deploying Qt's Libraries
+
+ \table
+ \header
+ \o {4,1} Qt's Libraries
+ \row
+ \o \l {QtAssistant}
+ \o \l {QAxContainer}
+ \o \l {QAxServer}
+ \o \l {QtCore}
+ \row
+ \o \l {QtDBus}
+ \o \l {QtDesigner}
+ \o \l {QtGui}
+ \o \l {QtHelp}
+ \row
+ \o \l {QtNetwork}
+ \o \l {QtOpenGL}
+ \o \l {QtScript}
+ \o \l {QtScriptTools}
+ \row
+ \o \l {QtSql}
+ \o \l {QtSvg}
+ \o \l {QtWebKit}
+ \o \l {QtXml}
+ \row
+ \o \l {QtXmlPatterns}
+ \o \l {Phonon Module}{Phonon}
+ \o \l {Qt3Support}
+ \o
+ \endtable
+
+ Since Qt is not a system library, it has to be redistributed along
+ with your application; the minimum is to redistribute the run-time
+ of the libraries used by the application. Using static linking,
+ however, the Qt run-time is compiled into the executable.
+
+ In general, you should deploy all plugins that your build of Qt uses,
+ excluding only those that you have identified as being unnecessary
+ for your application and its users.
+
+ For instance, you may need to deploy plugins for JPEG support and
+ SQL drivers, but you should also deploy plugins that your users may
+ require, including those for accessibility.
+ For more information about plugins, see the
+ \l{plugins-howto.html}{How to Create Qt Plugins} documentation.
+
+ When deploying an application using the shared library approach
+ you must ensure that the Qt libraries will use the correct path to
+ find the Qt plugins, documentation, translation etc. To do this you
+ can use a \c qt.conf file. For more information, see the \l {Using
+ qt.conf} documentation.
+
+ Depending on configuration, compiler specific libraries must be
+ redistributed as well. For more information, see the platform
+ specific Application Dependencies sections: \l
+ {deployment-x11.html#application-dependencies}{X11}, \l
+ {deployment-windows.html#application-dependencies}{Windows}, \l
+ {deployment-mac.html#application-dependencies}{Mac}.
+
+ \section1 Licensing
+
+ Some of Qt's libraries are based on third party libraries that are
+ not licensed using the same dual-license model as Qt. As a result,
+ care must be taken when deploying applications that use these
+ libraries, particularly when the application is statically linked
+ to them.
+
+ The following table contains an inexhaustive summary of the issues
+ you should be aware of.
+
+ \table
+ \header \o Qt Library \o Dependency
+ \o Licensing Issue
+ \row \o QtHelp \o CLucene
+ \o The version of clucene distributed with Qt is licensed
+ under the GNU LGPL version 2.1 or later. This has implications for
+ developers of closed source applications. Please see
+ \l{QtHelp Module#License Information}{the QtHelp module documentation}
+ for more information.
+
+ \row \o QtNetwork \o OpenSSL
+ \o Some configurations of QtNetwork use OpenSSL at run-time. Deployment
+ of OpenSSL libraries is subject to both licensing and export restrictions.
+ More information can be found in the \l{Secure Sockets Layer (SSL) Classes}
+ documentation.
+
+ \row \o QtWebKit \o WebKit
+ \o WebKit is licensed under the GNU LGPL version 2 or later.
+ This has implications for developers of closed source applications.
+ Please see \l{QtWebKit Module#License Information}{the QtWebKit module
+ documentation} for more information.
+
+ \row \o \l{Phonon Module}{Phonon} \o Phonon
+ \o Phonon relies on the native multimedia engines on different platforms.
+ Phonon itself is licensed under the GNU LGPL version 2. Please see
+ \l{Phonon Module#License Information}{the Phonon module documentation}
+ for more information on licensing and the
+ \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends
+ in use on different platforms.
+ \endtable
+
+ \section1 Platform-Specific Notes
+
+ The procedure of deploying Qt applications is different for the
+ various platforms:
+
+ \list
+ \o \l{Deploying an Application on X11 Platforms}{Qt for X11 Platforms}
+ \o \l{Deploying an Application on Windows}{Qt for Windows}
+ \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X}
+ \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux}
+ \o \l{Deploying an Application on the Symbian platform}{Qt for the Symbian platform}
+ \endlist
+
+ \sa Installation {Platform-Specific Documentation}
+*/
+
+/*!
+ \page deployment-x11.html
+ \contentspage Deploying Qt Applications
+
+ \title Deploying an Application on X11 Platforms
+
+ Due to the proliferation of Unix systems (commercial Unices, Linux
+ distributions, etc.), deployment on Unix is a complex
+ topic. Before we start, be aware that programs compiled for one
+ Unix flavor will probably not run on a different Unix system. For
+ example, unless you use a cross-compiler, you cannot compile your
+ application on Irix and distribute it on AIX.
+
+ Contents:
+
+ \tableofcontents
+
+ This documentation will describe how to determine which files you
+ should include in your distribution, and how to make sure that the
+ application will find them at run-time. We will demonstrate the
+ procedures in terms of deploying the \l {tools/plugandpaint}{Plug
+ & Paint} application that is provided in Qt's examples directory.
+
+ \section1 Static Linking
+
+ Static linking is often the safest and easiest way to distribute
+ an application on Unix since it relieves you from the task of
+ distributing the Qt libraries and ensuring that they are located
+ in the default search path for libraries on the target system.
+
+ \section2 Building Qt Statically
+
+ To use this approach, you must start by installing a static version
+ of the Qt library:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 0
+
+ We specify the prefix so that we do not overwrite the existing Qt
+ installation. The example above only builds the Qt libraries,
+ i.e. the examples and Qt Designer will not be built. When \c make
+ is done, you will find the Qt libraries in the \c /path/to/Qt/lib
+ directory.
+
+ When linking your application against static Qt libraries, note
+ that you might need to add more libraries to the \c LIBS line in
+ your project file. For more information, see the \l {Application
+ Dependencies} section.
+
+ \section2 Linking the Application to the Static Version of Qt
+
+ Once Qt is built statically, the next step is to regenerate the
+ makefile and rebuild the application. First, we must go into the
+ directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 1
+
+ Now run qmake to create a new makefile for the application, and do
+ a clean build to create the statically linked executable:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 2
+
+ You probably want to link against the release libraries, and you
+ can specify this when invoking \c qmake. Note that we must set the
+ path to the static Qt that we just built.
+
+ To check that the application really links statically with Qt, run
+ the \c ldd tool (available on most Unices):
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 3
+
+ Verify that the Qt libraries are not mentioned in the output.
+
+ Now, provided that everything compiled and linked without any
+ errors, we should have a \c plugandpaint file that is ready for
+ deployment. One easy way to check that the application really can
+ be run stand-alone is to copy it to a machine that doesn't have Qt
+ or any Qt applications installed, and run it on that machine.
+
+ Remember that if your application depends on compiler specific
+ libraries, these must still be redistributed along with your
+ application. For more information, see the \l {Application
+ Dependencies} section.
+
+ The \l {tools/plugandpaint}{Plug & Paint} example consists of
+ several components: The core application (\l
+ {tools/plugandpaint}{Plug & Paint}), and the \l
+ {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
+ {tools/plugandpaintplugins/extrafilters}{Extra Filters}
+ plugins. Since we cannot deploy plugins using the static linking
+ approach, the executable we have prepared so far is
+ incomplete. The application will run, but the functionality will
+ be disabled due to the missing plugins. To deploy plugin-based
+ applications we should use the shared library approach.
+
+ \section1 Shared Libraries
+
+ We have two challenges when deploying the \l
+ {tools/plugandpaint}{Plug & Paint} application using the shared
+ libraries approach: The Qt runtime has to be correctly
+ redistributed along with the application executable, and the
+ plugins have to be installed in the correct location on the target
+ system so that the application can find them.
+
+ \section2 Building Qt as a Shared Library
+
+ We assume that you already have installed Qt as a shared library,
+ which is the default when installing Qt, in the \c /path/to/Qt
+ directory. For more information on how to build Qt, see the \l
+ {Installation} documentation.
+
+ \section2 Linking the Application to Qt as a Shared Library
+
+ After ensuring that Qt is built as a shared library, we can build
+ the \l {tools/plugandpaint}{Plug & Paint} application. First, we
+ must go into the directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 4
+
+ Now run qmake to create a new makefile for the application, and do
+ a clean build to create the dynamically linked executable:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 5
+
+ This builds the core application, the following will build the
+ plugins:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 6
+
+ If everything compiled and linked without any errors, we will get
+ a \c plugandpaint executable and the \c libpnp_basictools.so and
+ \c libpnp_extrafilters.so plugin files.
+
+ \section2 Creating the Application Package
+
+ There is no standard package management on Unix, so the method we
+ present below is a generic solution. See the documentation for
+ your target system for information on how to create a package.
+
+ To deploy the application, we must make sure that we copy the
+ relevant Qt libraries (corresponding to the Qt modules used in the
+ application) as well as the executable to the same
+ directory. Remember that if your application depends on compiler
+ specific libraries, these must also be redistributed along with
+ your application. For more information, see the \l {Application
+ Dependencies} section.
+
+ We'll cover the plugins shortly, but the main issue with shared
+ libraries is that you must ensure that the dynamic linker will
+ find the Qt libraries. Unless told otherwise, the dynamic linker
+ doesn't search the directory where your application resides. There
+ are many ways to solve this:
+
+ \list
+
+ \o You can install the Qt libraries in one of the system
+ library paths (e.g. \c /usr/lib on most systems).
+
+ \o You can pass a predetermined path to the \c -rpath command-line
+ option when linking the application. This will tell the dynamic
+ linker to look in this directory when starting your application.
+
+ \o You can write a startup script for your application, where you
+ modify the dynamic linker configuration (e.g. adding your
+ application's directory to the \c LD_LIBRARY_PATH environment
+ variable. \note If your application will be running with "Set
+ user ID on execution," and if it will be owned by root, then
+ LD_LIBRARY_PATH will be ignored on some platforms. In this
+ case, use of the LD_LIBRARY_PATH approach is not an option).
+
+ \endlist
+
+ The disadvantage of the first approach is that the user must have
+ super user privileges. The disadvantage of the second approach is
+ that the user may not have privileges to install into the
+ predetemined path. In either case, the users don't have the option
+ of installing to their home directory. We recommend using the
+ third approach since it is the most flexible. For example, a \c
+ plugandpaint.sh script will look like this:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 7
+
+ By running this script instead of the executable, you are sure
+ that the Qt libraries will be found by the dynamic linker. Note
+ that you only have to rename the script to use it with other
+ applications.
+
+ When looking for plugins, the application searches in a plugins
+ subdirectory inside the directory of the application
+ executable. Either you have to manually copy the plugins into the
+ \c plugins directory, or you can set the \c DESTDIR in the
+ plugins' project files:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 8
+
+ An archive distributing all the Qt libraries, and all the plugins,
+ required to run the \l {tools/plugandpaint}{Plug & Paint}
+ application, would have to include the following files:
+
+ \table 100%
+ \header
+ \o Component \o {2, 1} File Name
+ \row
+ \o The executable
+ \o {2, 1} \c plugandpaint
+ \row
+ \o The script to run the executable
+ \o {2, 1} \c plugandpaint.sh
+ \row
+ \o The Basic Tools plugin
+ \o {2, 1} \c plugins\libpnp_basictools.so
+ \row
+ \o The ExtraFilters plugin
+ \o {2, 1} \c plugins\libpnp_extrafilters.so
+ \row
+ \o The Qt Core module
+ \o {2, 1} \c libQtCore.so.4
+ \row
+ \o The Qt GUI module
+ \o {2, 1} \c libQtGui.so.4
+ \endtable
+
+ On most systems, the extension for shared libraries is \c .so. A
+ notable exception is HP-UX, which uses \c .sl.
+
+ Remember that if your application depends on compiler specific
+ libraries, these must still be redistributed along with your
+ application. For more information, see the \l {Application
+ Dependencies} section.
+
+ To verify that the application now can be successfully deployed,
+ you can extract this archive on a machine without Qt and without
+ any compiler installed, and try to run it, i.e. run the \c
+ plugandpaint.sh script.
+
+ An alternative to putting the plugins in the \c plugins
+ subdirectory is to add a custom search path when you start your
+ application using QApplication::addLibraryPath() or
+ QApplication::setLibraryPaths().
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 9
+
+ \section1 Application Dependencies
+
+ \section2 Additional Libraries
+
+ To find out which libraries your application depends on, run the
+ \c ldd tool (available on most Unices):
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 10
+
+ This will list all the shared library dependencies for your
+ application. Depending on configuration, these libraries must be
+ redistributed along with your application. In particular, the
+ standard C++ library must be redistributed if you're compiling
+ your application with a compiler that is binary incompatible with
+ the system compiler. When possible, the safest solution is to link
+ against these libraries statically.
+
+ You will probably want to link dynamically with the regular X11
+ libraries, since some implementations will try to open other
+ shared libraries with \c dlopen(), and if this fails, the X11
+ library might cause your application to crash.
+
+ It's also worth mentioning that Qt will look for certain X11
+ extensions, such as Xinerama and Xrandr, and possibly pull them
+ in, including all the libraries that they link against. If you
+ can't guarantee the presence of a certain extension, the safest
+ approach is to disable it when configuring Qt (e.g. \c {./configure
+ -no-xrandr}).
+
+ FontConfig and FreeType are other examples of libraries that
+ aren't always available or that aren't always binary
+ compatible. As strange as it may sound, some software vendors have
+ had success by compiling their software on very old machines and
+ have been very careful not to upgrade any of the software running
+ on them.
+
+ When linking your application against the static Qt libraries, you
+ must explicitly link with the dependent libraries mentioned
+ above. Do this by adding them to the \c LIBS variable in your
+ project file.
+
+ \section2 Qt Plugins
+
+ Your application may also depend on one or more Qt plugins, such
+ as the JPEG image format plugin or a SQL driver plugin. Be sure
+ to distribute any Qt plugins that you need with your application,
+ and note that each type of plugin should be located within a
+ specific subdirectory (such as \c imageformats or \c sqldrivers)
+ within your distribution directory, as described below.
+
+ \note If you are deploying an application that uses QtWebKit to display
+ HTML pages from the World Wide Web, you should include all text codec
+ plugins to support as many HTML encodings possible.
+
+ The search path for Qt plugins (as well as a few other paths) is
+ hard-coded into the QtCore library. By default, the first plugin
+ search path will be hard-coded as \c /path/to/Qt/plugins. As
+ mentioned above, using pre-determined paths has certain
+ disadvantages, so you need to examine various alternatives to make
+ sure that the Qt plugins are found:
+
+ \list
+
+ \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended
+ approach since it provides the most flexibility.
+
+ \o Using QApplication::addLibraryPath() or
+ QApplication::setLibraryPaths().
+
+ \o Using a third party installation utility or the target system's
+ package manager to change the hard-coded paths in the QtCore
+ library.
+
+ \endlist
+
+ The \l{How to Create Qt Plugins} document outlines the issues you
+ need to pay attention to when building and deploying plugins for
+ Qt applications.
+*/
+
+/*!
+ \page deployment-windows.html
+ \contentspage Deploying Qt Applications
+
+ \title Deploying an Application on Windows
+
+ This documentation will describe how to determine which files you
+ should include in your distribution, and how to make sure that the
+ application will find them at run-time. We will demonstrate the
+ procedures in terms of deploying the \l {tools/plugandpaint}{Plug
+ & Paint} application that is provided in Qt's examples directory.
+
+ Contents:
+
+ \tableofcontents
+
+ \section1 Static Linking
+
+ If you want to keep things simple by only having a few files to
+ deploy, i.e. a stand-alone executable with the associated compiler
+ specific DLLs, then you must build everything statically.
+
+ \section2 Building Qt Statically
+
+ Before we can build our application we must make sure that Qt is
+ built statically. To do this, go to a command prompt and type the
+ following:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 11
+
+ Remember to specify any other options you need, such as data base
+ drivers, as arguments to \c configure. Once \c configure has
+ finished, type the following:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 12
+
+ This will build Qt statically. Note that unlike with a dynamic build,
+ building Qt statically will result in libraries without version numbers;
+ e.g. \c QtCore4.lib will be \c QtCore.lib. Also, we have used \c nmake
+ in all the examples, but if you use MinGW you must use
+ \c mingw32-make instead.
+
+ \note If you later need to reconfigure and rebuild Qt from the
+ same location, ensure that all traces of the previous configuration are
+ removed by entering the build directory and typing \c{nmake distclean}
+ before running \c configure again.
+
+ \section2 Linking the Application to the Static Version of Qt
+
+ Once Qt has finished building we can build the \l
+ {tools/plugandpaint}{Plug & Paint} application. First we must go
+ into the directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 13
+
+ We must then run \c qmake to create a new makefile for the
+ application, and do a clean build to create the statically linked
+ executable:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 14
+
+ You probably want to link against the release libraries, and you
+ can specify this when invoking \c qmake. Now, provided that
+ everything compiled and linked without any errors, we should have
+ a \c plugandpaint.exe file that is ready for deployment. One easy
+ way to check that the application really can be run stand-alone is
+ to copy it to a machine that doesn't have Qt or any Qt
+ applications installed, and run it on that machine.
+
+ Remember that if your application depends on compiler specific
+ libraries, these must still be redistributed along with your
+ application. You can check which libraries your application is
+ linking against by using the \c depends tool. For more
+ information, see the \l {Application Dependencies} section.
+
+ The \l {tools/plugandpaint}{Plug & Paint} example consists of
+ several components: The application itself (\l
+ {tools/plugandpaint}{Plug & Paint}), and the \l
+ {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
+ {tools/plugandpaintplugins/extrafilters}{Extra Filters}
+ plugins. Since we cannot deploy plugins using the static linking
+ approach, the application we have prepared is incomplete. It will
+ run, but the functionality will be disabled due to the missing
+ plugins. To deploy plugin-based applications we should use the
+ shared library approach.
+
+ \section1 Shared Libraries
+
+ We have two challenges when deploying the \l
+ {tools/plugandpaint}{Plug & Paint} application using the shared
+ libraries approach: The Qt runtime has to be correctly
+ redistributed along with the application executable, and the
+ plugins have to be installed in the correct location on the target
+ system so that the application can find them.
+
+ \section2 Building Qt as a Shared Library
+
+ We assume that you already have installed Qt as a shared library,
+ which is the default when installing Qt, in the \c C:\path\to\Qt
+ directory. For more information on how to build Qt, see the \l
+ {Installation} documentation.
+
+ \section2 Linking the Application to Qt as a Shared Library
+
+ After ensuring that Qt is built as a shared library, we can build
+ the \l {tools/plugandpaint}{Plug & Paint} application. First, we
+ must go into the directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 15
+
+ Now run \c qmake to create a new makefile for the application, and
+ do a clean build to create the dynamically linked executable:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 16
+
+ This builds the core application, the following will build the
+ plugins:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 17
+
+ If everything compiled and linked without any errors, we will get
+ a \c plugandpaint.exe executable and the \c pnp_basictools.dll and
+ \c pnp_extrafilters.dll plugin files.
+
+ \section2 Creating the Application Package
+
+ To deploy the application, we must make sure that we copy the
+ relevant Qt DLL (corresponding to the Qt modules used in
+ the application) as well as the executable to the same directory
+ in the \c release subdirectory.
+
+ Remember that if your application depends on compiler specific
+ libraries, these must be redistributed along with your
+ application. You can check which libraries your application is
+ linking against by using the \c depends tool. For more
+ information, see the \l {Application Dependencies} section.
+
+ We'll cover the plugins shortly, but first we'll check that the
+ application will work in a deployed environment: Either copy the
+ executable and the Qt DLLs to a machine that doesn't have Qt
+ or any Qt applications installed, or if you want to test on the
+ build machine, ensure that the machine doesn't have Qt in its
+ environment.
+
+ If the application starts without any problems, then we have
+ successfully made a dynamically linked version of the \l
+ {tools/plugandpaint}{Plug & Paint} application. But the
+ application's functionality will still be missing since we have
+ not yet deployed the associated plugins.
+
+ Plugins work differently to normal DLLs, so we can't just
+ copy them into the same directory as our application's executable
+ as we did with the Qt DLLs. When looking for plugins, the
+ application searches in a \c plugins subdirectory inside the
+ directory of the application executable.
+
+ So to make the plugins available to our application, we have to
+ create the \c plugins subdirectory and copy over the relevant DLLs:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 18
+
+ An archive distributing all the Qt DLLs and application
+ specific plugins required to run the \l {tools/plugandpaint}{Plug
+ & Paint} application, would have to include the following files:
+
+ \table 100%
+ \header
+ \o Component \o {2, 1} File Name
+ \row
+ \o The executable
+ \o {2, 1} \c plugandpaint.exe
+ \row
+ \o The Basic Tools plugin
+ \o {2, 1} \c plugins\pnp_basictools.dll
+ \row
+ \o The ExtraFilters plugin
+ \o {2, 1} \c plugins\pnp_extrafilters.dll
+ \row
+ \o The Qt Core module
+ \o {2, 1} \c qtcore4.dll
+ \row
+ \o The Qt GUI module
+ \o {2, 1} \c qtgui4.dll
+ \endtable
+
+ In addition, the archive must contain the following compiler
+ specific libraries depending on your version of Visual Studio:
+
+ \table 100%
+ \header
+ \o \o VC++ 6.0 \o VC++ 7.1 (2003) \o VC++ 8.0 (2005) \o VC++ 9.0 (2008)
+ \row
+ \o The C run-time
+ \o \c msvcrt.dll
+ \o \c msvcr71.dll
+ \o \c msvcr80.dll
+ \o \c msvcr90.dll
+ \row
+ \o The C++ run-time
+ \o \c msvcp60.dll
+ \o \c msvcp71.dll
+ \o \c msvcp80.dll
+ \o \c msvcp90.dll
+ \endtable
+
+ To verify that the application now can be successfully deployed,
+ you can extract this archive on a machine without Qt and without
+ any compiler installed, and try to run it.
+
+ An alternative to putting the plugins in the plugins subdirectory
+ is to add a custom search path when you start your application
+ using QApplication::addLibraryPath() or
+ QApplication::setLibraryPaths().
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 19
+
+ One benefit of using plugins is that they can easily be made
+ available to a whole family of applications.
+
+ It's often most convenient to add the path in the application's \c
+ main() function, right after the QApplication object is
+ created. Once the path is added, the application will search it
+ for plugins, in addition to looking in the \c plugins subdirectory
+ in the application's own directory. Any number of additional paths
+ can be added.
+
+ \section2 Visual Studio 2005 Onwards
+
+ When deploying an application compiled with Visual Studio 2005 onwards,
+ there are some additional steps to be taken.
+
+ First, we need to copy the manifest file created when linking the
+ application. This manifest file contains information about the
+ application's dependencies on side-by-side assemblies, such as the runtime
+ libraries.
+
+ The manifest file needs to be copied into the \bold same folder as the
+ application executable. You do not need to copy the manifest files for
+ shared libraries (DLLs), since they are not used.
+
+ If the shared library has dependencies that are different from the
+ application using it, the manifest file needs to be embedded into the DLL
+ binary. Since Qt 4.1.3, the follwoing \c CONFIG options are available for
+ embedding manifests:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 20
+
+ To use the options, add
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 21
+
+ to your .pro file. The \c embed_manifest_dll option is enabled by default.
+
+ You can find more information about manifest files and side-by-side
+ assemblies at the
+ \l {http://msdn.microsoft.com/en-us/library/aa376307.aspx}{MSDN website}.
+
+ There are two ways to include the run time libraries: by bundling them
+ directly with your application or by installing them on the end-user's
+ system.
+
+ To bundle the run time libraries with your application, copy the directory
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 22
+
+ into the folder where your executable is, so that you are including a
+ \c Microsoft.VC80.CRT directory alongside your application's executable. If
+ you are bundling the runtimes and need to deploy plugins as well, you have
+ to remove the manifest from the plugins (embedded as a resource) by adding
+ the following line to the \c{.pro} file of the plugins you are compiling:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 23
+
+ \warning If you skip the step above, the plugins will not load on some
+ systems.
+
+ To install the runtime libraries on the end-user's system, you need to
+ include the appropriate Visual C++ Redistributable Package (VCRedist)
+ executable with your application and ensure that it is executed when the
+ user installs your application.
+
+ For example, on an 32-bit x86-based system, you would include the
+ \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE}{vcredist_x86.exe}
+ executable. The \l{http://www.microsoft.com/downloads/details.aspx?familyid=526BF4A7-44E6-4A91-B328-A4594ADB70E5}{vcredist_IA64.exe}
+ and \l{http://www.microsoft.com/downloads/details.aspx?familyid=90548130-4468-4BBC-9673-D6ACABD5D13B}{vcredist_x64.exe}
+ executables provide the appropriate libraries for the IA64 and 64-bit x86
+ architectures, respectively.
+
+ \note The application you ship must be compiled with exactly the same
+ compiler version against the same C runtime version. This prevents
+ deploying errors caused by different versions of the C runtime libraries.
+
+ \section2 Visual Studio 2008 And Manual Installs
+
+ As well as the above details for VS 2005 and onwards, Visual Studio 2008
+ applications may have problems when deploying manually, say to a USB
+ stick.
+
+ The recommended procedure is to configure Qt with the \c -plugin-manifests
+ option using the 'configure' tool. Then follow the \l {http://msdn.microsoft.com/en-us/library/ms235291(VS.80).aspx}{guidelines}
+ for manually deploying private assemblies.
+
+ In brief the steps are
+
+ \list 1
+
+ \o create a folder structure on the development computer that will match the target USB stick directory structure, for example '\\app' and for your dlls, '\\app\\lib'.
+
+ \o on the development computer, from the appropriate 'redist' folder copy over Microsoft.VC80.CRT and Microsoft.VC80.MFC to the directories '\\app' and '\\app\\lib' on the development PC.
+
+ \o xcopy the \\app folder to the target USB stick.
+ \endlist
+
+ Your application should now run. Also be aware that even with a service
+ pack installed the Windows DLLs that are linked to will be the defaults. See
+ the information on \l {http://msdn.microsoft.com/en-us/library/cc664727.aspx}{how to select the appropriate target DLLs}.
+
+ \section1 Application Dependencies
+
+ \section2 Additional Libraries
+
+ Depending on configuration, compiler specific libraries must be
+ redistributed along with your application. You can check which
+ libraries your application is linking against by using the
+ \l{Dependency Walker} tool. All you need to do is to run it like
+ this:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 24
+
+ This will provide a list of the libraries that your application
+ depends on and other information.
+
+ \image deployment-windows-depends.png
+
+ When looking at the release build of the Plug & Paint executable
+ (\c plugandpaint.exe) with the \c depends tool, the tool lists the
+ following immediate dependencies to non-system libraries:
+
+ \table 100%
+ \header
+ \o Qt
+ \o VC++ 6.0
+ \o VC++ 7.1 (2003)
+ \o VC++ 8.0 (2005)
+ \o MinGW
+ \row
+ \o \list
+ \o QTCORE4.DLL - The QtCore runtime
+ \o QTGUI4.DLL - The QtGui runtime
+ \endlist
+ \o \list
+ \o MSVCRT.DLL - The C runtime
+ \o MSVCP60.DLL - The C++ runtime (only when STL is installed)
+ \endlist
+ \o \list
+ \o MSVCR71.DLL - The C runtime
+ \o MSVCP71.DLL - The C++ runtime (only when STL is installed)
+ \endlist
+ \o \list
+ \o MSVCR80.DLL - The C runtime
+ \o MSVCP80.DLL - The C++ runtime (only when STL is installed)
+ \endlist
+ \o \list
+ \o MINGWM10.DLL - The MinGW run-time
+ \endlist
+ \endtable
+
+ When looking at the plugin DLLs the exact same dependencies
+ are listed.
+
+ \section2 Qt Plugins
+
+ Your application may also depend on one or more Qt plugins, such
+ as the JPEG image format plugin or a SQL driver plugin. Be sure
+ to distribute any Qt plugins that you need with your application,
+ and note that each type of plugin should be located within a
+ specific subdirectory (such as \c imageformats or \c sqldrivers)
+ within your distribution directory, as described below.
+
+ \note If you are deploying an application that uses QtWebKit to display
+ HTML pages from the World Wide Web, you should include all text codec
+ plugins to support as many HTML encodings possible.
+
+ The search path for Qt plugins is hard-coded into the QtCore library.
+ By default, the plugins subdirectory of the Qt installation is the first
+ plugin search path. However, pre-determined paths like the default one
+ have certain disadvantages. For example, they may not exist on the target
+ machine. For that reason, you need to examine various alternatives to make
+ sure that the Qt plugins are found:
+
+ \list
+
+ \o \l{qt-conf.html}{Using \c qt.conf}. This approach is the recommended
+ if you have executables in different places sharing the same plugins.
+
+ \o Using QApplication::addLibraryPath() or
+ QApplication::setLibraryPaths(). This approach is recommended if you only
+ have one executable that will use the plugin.
+
+ \o Using a third party installation utility to change the
+ hard-coded paths in the QtCore library.
+
+ \endlist
+
+ If you add a custom path using QApplication::addLibraryPath it could
+ look like this:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 54
+
+ Then qApp->libraryPaths() would return something like this:
+
+ "C:/customPath/plugins "
+ "C:/Qt/%VERSION%/plugins"
+ "E:/myApplication/directory/"
+
+ The executable will look for the plugins in these directories and
+ the same order as the QStringList returned by qApp->libraryPaths().
+ The newly added path is prepended to the qApp->libraryPaths() which
+ means that it will be searched through first. However, if you use
+ qApp->setLibraryPaths(), you will be able to determend which paths
+ and in which order they will be searched.
+
+ The \l{How to Create Qt Plugins} document outlines the issues you
+ need to pay attention to when building and deploying plugins for
+ Qt applications.
+
+ \section1 Related Third Party Resources
+
+ \list
+ \o \l{http://silmor.de/29}{Cross compiling Qt/Win Apps on Linux} covers the
+ process of cross-compiling Windows applications on Linux.
+ \o \l{http://divided-mind.blogspot.com/2007/09/cross-compiling-qt4win-on-linux.html}
+ {Cross-compiling Qt4/Win on Linux} provides another Linux-to-Windows
+ cross-compilation guide.
+ \endlist
+*/
+
+/*!
+ \page deployment-mac.html
+ \contentspage Deploying Qt Applications
+
+ \title Deploying an Application on Mac OS X
+
+ Beginning with Qt 4.5, a \l {macdeploy}{deployment tool} is
+ included that automates the prodecures described here.
+
+ This document describes how to create a bundle and how to make
+ sure that the application will find the resources it needs at
+ run-time. We demonstrate the procedures in terms of deploying the
+ \l {tools/plugandpaint}{Plug & Paint} application that is provided
+ in Qt's examples directory.
+
+ \tableofcontents
+
+ \section1 The Bundle
+
+ On the Mac, a GUI application must be built and run from a
+ bundle. A bundle is a directory structure that appears as a single
+ entity when viewed in the Finder. A bundle for an application
+ typcially contains the executable and all the resources it
+ needs. See the image below:
+
+ \image deployment-mac-bundlestructure.png
+
+ The bundle provides many advantages to the user. One primary
+ advantage is that, since it is a single entity, it allows for
+ drag-and-drop installation. As a programmer you can access bundle
+ information in your own code. This is specific to Mac OS X and
+ beyond the scope of this document. More information about bundles
+ is available on \l
+ {http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html}{Apple's Developer Website}.
+
+ A Qt command line application on Mac OS X works similar to a
+ command line application on Unix and Windows. You probably don't
+ want to run it in a bundle: Add this to your application's .pro:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 26
+
+ This will tell \c qmake not to put the executable inside a
+ bundle. Please refer to the \l{Deploying an Application on
+ X11 Platforms}{X11 deployment documentation} for information about how
+ to deploy these "bundle-less" applications.
+
+ \section1 Xcode
+
+ We will only concern ourselves with command-line tools here. While
+ it is possible to use Xcode for this, Xcode has changed enough
+ between each version that it makes it difficult to document it
+ perfectly for each version. A future version of this document may
+ include more information for using Xcode in the deployment
+ process.
+
+ \section1 Static Linking
+
+ If you want to keep things simple by only having a few files to
+ deploy, then you must build everything statically.
+
+ \section2 Building Qt Statically
+
+ Start by installing a static version of the Qt library. Remember
+ that you will not be able to use plugins and you must build in all
+ the image formats, SQL drivers, etc..
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 27
+
+ You can check the various options that are available by running \c
+ configure -help.
+
+ \section2 Linking the Application to the Static Version of Qt
+
+ Once Qt is built statically, the next step is to regenerate the
+ makefile and rebuild the application. First, we must go into the
+ directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 28
+
+ Now run \c qmake to create a new makefile for the application, and do
+ a clean build to create the statically linked executable:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 29
+
+ You probably want to link against the release libraries, and you
+ can specify this when invoking \c qmake. If you have Xcode Tools
+ 1.5 or higher installed, you may want to take advantage of "dead
+ code stripping" to reduce the size of your binary even more. You
+ can do this by passing \c {LIBS+= -dead_strip} to \c qmake in
+ addition to the \c {-config release} parameter. This doesn't have
+ as large an effect if you are using GCC 4, since Qt will then have
+ function visibility hints built-in, but if you use GCC 3.3, it
+ could make a difference.
+
+ Now, provided that everything compiled and linked without any
+ errors, we should have a \c plugandpaint.app bundle that is ready
+ for deployment. One easy way to check that the application really
+ can be run stand-alone is to copy the bundle to a machine that
+ doesn't have Qt or any Qt applications installed, and run the
+ application on that machine.
+
+ You can check what other libraries your application links to using
+ the \c otool:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 30
+
+ Here is what the output looks like for the static \l
+ {tools/plugandpaint}{Plug & Paint}:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 31
+
+ For more information, see the \l {Application Dependencies}
+ section.
+
+ If you see \e Qt libraries in the output, it probably
+ means that you have both dynamic and static Qt libraries installed
+ on your machine. The linker will always choose dynamic over
+ static. There are two solutions: Either move your Qt dynamic
+ libraries (\c .dylibs) away to another directory while you link
+ the application and then move them back, or edit the \c Makefile
+ and replace link lines for the Qt libraries with the absolute path
+ to the static libraries. For example, replace
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 32
+
+ with
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 33
+
+ The \l {tools/plugandpaint}{Plug & Paint} example consists of
+ several components: The core application (\l
+ {tools/plugandpaint}{Plug & Paint}), and the \l
+ {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
+ {tools/plugandpaintplugins/extrafilters}{Extra Filters}
+ plugins. Since we cannot deploy plugins using the static linking
+ approach, the bundle we have prepared so far is incomplete. The
+ application will run, but the functionality will be disabled due
+ to the missing plugins. To deploy plugin-based applications we
+ should use the framework approach.
+
+ \section1 Frameworks
+
+ We have two challenges when deploying the \l
+ {tools/plugandpaint}{Plug & Paint} application using frameworks:
+ The Qt runtime has to be correctly redistributed along with the
+ application bundle, and the plugins have to be installed in the
+ correct location so that the application can find them.
+
+ When distributing Qt with your application using frameworks, you
+ have two options: You can either distribute Qt as a private
+ framework within your application bundle, or you can distribute Qt
+ as a standard framework (alternatively use the Qt frameworks in
+ the installed binary). These two approaches are essentially the
+ same. The latter option is good if you have many Qt applications
+ and you would prefer to save memory. The former is good if you
+ have Qt built in a special way, or want to make sure the framework
+ is there. It just comes down to where you place the Qt frameworks.
+
+ \section2 Building Qt as Frameworks
+
+ We assume that you already have installed Qt as frameworks, which
+ is the default when installing Qt, in the /path/to/Qt
+ directory. For more information on how to build Qt, see the \l
+ Installation documentation.
+
+ When installing, the identification name of the frameworks will
+ also be set. The identification name is what the dynamic linker
+ (\c dyld) uses to find the libraries for your application.
+
+ \section2 Linking the Application to Qt as Frameworks
+
+ After ensuring that Qt is built as frameworks, we can build the \l
+ {tools/plugandpaint}{Plug & Paint} application. First, we must go
+ into the directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 34
+
+ Now run qmake to create a new makefile for the application, and do
+ a clean build to create the dynamically linked executable:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 35
+
+ This builds the core application, the following will build the
+ plugins:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 36
+
+ Now run the \c otool for the Qt frameworks, for example Qt Gui:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 37
+
+ You will get the following output:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 38
+
+ For the Qt frameworks, the first line (i.e. \c
+ {path/to/Qt/lib/QtGui.framework/Versions/4/QtGui (compatibility
+ version 4.0.0, current version 4.0.1)}) becomes the framework's
+ identification name which is used by the dynamic linker (\c dyld).
+
+ But when you are deploying the application, your users may not
+ have the Qt frameworks installed in the specified location. For
+ that reason, you must either provide the frameworks in an agreed
+ upon location, or store the frameworks in the bundle itself.
+ Regardless of which solution you choose, you must make sure that
+ the frameworks return the proper identification name for
+ themselves, and that the application will look for these
+ names. Luckily we can control this with the \c install_name_tool
+ command-line tool.
+
+ The \c install_name_tool works in two modes, \c -id and \c
+ -change. The \c -id mode is for libraries and frameworks, and
+ allows us to specify a new identification name. We use the \c
+ -change mode to change the paths in the application.
+
+ Let's test this out by copying the Qt frameworks into the Plug &
+ Paint bundle. Looking at \c otool's output for the bundle, we can
+ see that we must copy both the QtCore and QtGui frameworks into
+ the bundle. We will assume that we are in the directory where we
+ built the bundle.
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 39
+
+ First we create a \c Frameworks directory inside the bundle. This
+ follows the Mac OS X application convention. We then copy the
+ frameworks into the new directory. Since frameworks contain
+ symbolic links, and we want to preserve them, we use the \c -R
+ option.
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 40
+
+ Then we run \c install_name_tool to set the identification names
+ for the frameworks. The first argument after \c -id is the new
+ name, and the second argument is the framework which
+ identification we wish to change. The text \c @executable_path is
+ a special \c dyld variable telling \c dyld to start looking where
+ the executable is located. The new names specifies that these
+ frameworks will be located "one directory up and over" in the \c
+ Frameworks directory.
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 41
+
+ Now, the dynamic linker knows where to look for QtCore and
+ QtGui. Then we must make the application aware of the library
+ locations as well using \c install_name_tool's \c -change mode.
+ This basically comes down to string replacement, to match the
+ identification names that we set for the frameworks.
+
+ Finally, since the QtGui framework depends on QtCore, we must
+ remember to change the reference for QtGui:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 42
+
+ After all this we can run \c otool again and see that the
+ application will look in the right locations.
+
+ Of course, the thing that makes the \l {tools/plugandpaint}{Plug &
+ Paint} example interesting are its plugins. The basic steps we
+ need to follow with plugins are:
+
+ \list
+ \o Put the plugins inside the bundle
+ \o Make sure that the plugins use the correct library using the
+ \c install_name_tool
+ \o Make sure that the application knows where to get the plugins
+ \endlist
+
+ While we can put the plugins anywhere we want in the bundle, the
+ best location to put them is under Contents/Plugins. When we built
+ the Plug & Paint plugins, the \c DESTDIR variable in their \c .pro
+ file put the plugins' \c .dylib files in a \c plugins subdirectory
+ in the \c plugandpaint directory. So, in this example, all we need
+ to do is move this directory:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 43
+
+ If we run \c otool on for example the \l
+ {tools/plugandpaintplugins/basictools}{Basic Tools} plugin's \c
+ .dylib file we get the following information.
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 44
+
+ Then we can see that the plugin links to the Qt frameworks it was
+ built against. Since we want the plugins to use the framework in
+ the application bundle we change them the same way as we did for
+ the application. For example for the Basic Tools plugin:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 45
+
+
+ We must also modify the code in \c
+ tools/plugandpaint/mainwindow.cpp to \l {QDir::cdUp()}{cdUp()} one
+ directory since the plugins live in the bundle. Add the following
+ code to the \c mainwindow.cpp file:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 46
+
+ \table
+ \row
+ \o \inlineimage deployment-mac-application.png
+ \o
+ The additional code in \c tools/plugandpaint/mainwindow.cpp also
+ enables us to view the plugins in the Finder, as shown to the left.
+
+ We can also add plugins extending Qt, for example adding SQL
+ drivers or image formats. We just need to follow the directory
+ structure outlined in plugin documentation, and make sure they are
+ included in the QCoreApplication::libraryPaths(). Let's quickly do
+ this with the image formats, following the approach from above.
+
+ Copy Qt's image format plugins into the bundle:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 47
+
+ Use \c install_name_tool to link the plugins to the frameworks in
+ the bundle:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 48
+
+ Then we update the source code in \c tools/plugandpaint/main.cpp
+ to look for the new plugins. After constructing the
+ QApplication, we add the following code:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 49
+
+ First, we tell the application to only look for plugins in this
+ directory. In our case, this is what we want since we only want to
+ look for the plugins that we distribute with the bundle. If we
+ were part of a bigger Qt installation we could have used
+ QCoreApplication::addLibraryPath() instead.
+
+ \endtable
+
+ \warning When deploying plugins, and thus make changes to the
+ source code, the default identification names are reset when
+ rebuilding the application, and you must repeat the process of
+ making your application link to the Qt frameworks in the bundle
+ using \c install_name_tool.
+
+ Now you should be able to move the application to another Mac OS X
+ machine and run it without Qt installed. Alternatively, you can
+ move your frameworks that live outside of the bundle to another
+ directory and see if the application still runs.
+
+ If you store the frameworks in another location than in the
+ bundle, the technique of linking your application is similar; you
+ must make sure that the application and the frameworks agree where
+ to be looking for the Qt libraries as well as the plugins.
+
+ \section2 Creating the Application Package
+
+ When you are done linking your application to Qt, either
+ statically or as frameworks, the application is ready to be
+ distributed. Apple provides a fair bit of information about how to
+ do this and instead of repeating it here, we recommend that you
+ consult their \l
+ {http://developer.apple.com/documentation/DeveloperTools/Conceptual/SoftwareDistribution/index.html}{software delivery}
+ documentation.
+
+ Although the process of deploying an application do have some
+ pitfalls, once you know the various issues you can easily create
+ packages that all your Mac OS X users will enjoy.
+
+ \section1 Application Dependencies
+
+ \section2 Qt Plugins
+
+ Your application may also depend on one or more Qt plugins, such
+ as the JPEG image format plugin or a SQL driver plugin. Be sure
+ to distribute any Qt plugins that you need with your application,
+ and note that each type of plugin should be located within a
+ specific subdirectory (such as \c imageformats or \c sqldrivers)
+ within your distribution directory, as described below.
+
+ \note If you are deploying an application that uses QtWebKit to display
+ HTML pages from the World Wide Web, you should include all text codec
+ plugins to support as many HTML encodings possible.
+
+ The search path for Qt plugins (as well as a few other paths) is
+ hard-coded into the QtCore library. By default, the first plugin
+ search path will be hard-coded as \c /path/to/Qt/plugins. But
+ using pre-determined paths has certain disadvantages. For example,
+ they may not exist on the target machine. For that reason you need
+ to examine various alternatives to make sure that the Qt plugins
+ are found:
+
+ \list
+
+ \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended
+ approach since it provides the most flexibility.
+
+ \o Using QApplication::addLibraryPath() or
+ QApplication::setLibraryPaths().
+
+ \o Using a third party installation utility to change the
+ hard-coded paths in the QtCore library.
+
+ \endlist
+
+ The \l{How to Create Qt Plugins} document outlines the issues you
+ need to pay attention to when building and deploying plugins for
+ Qt applications.
+
+ \section2 Additional Libraries
+
+ You can check which libraries your application is linking against
+ by using the \c otool tool. To use \c otool, all you need to do is
+ to run it like this:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 50
+
+ Unlike the deployment processes on \l {Deploying an Application on
+ X11 Platforms}{X11} and \l {Deploying an Application on
+ Windows}{Windows}, compiler specific libraries rarely have to
+ be redistributed along with your application. But since Qt can be
+ configured, built, and installed in several ways on Mac OS X,
+ there are also several ways to deploy applications. Typically your
+ goals help determine how you are going to deploy the
+ application. The last sections describe a couple of things to keep
+ in mind when you are deploying your application.
+
+ \section2 Mac OS X Version Dependencies
+
+ From Qt 4.6, Mac OS X 10.3 (Panther) is no longer supported. Qt
+ 4.6 applications can be built and deployed on Mac OS X 10.4
+ (Tiger) and higher. This is achieved using \e{weak linking}. In
+ \e{weak linking}, Qt tests whether a function added in a newer
+ version of Mac OS X is available on the computer it is running
+ on. This allows Qt to use newer features, when it runs on a newer
+ version of OS X, while remaining compatible on the older versions.
+
+ For more information about cross development issues on Mac OS X,
+ see \l
+ {http://developer.apple.com/documentation/DeveloperTools/Conceptual/cross_development/index.html}{Apple's Developer Website}.
+
+ Since the linker is set to be compatible with all OS X versions,
+ you must change the \c MACOSX_DEPLOYMENT_TARGET environment
+ variable to get \e{weak linking} to work for your application. You
+ can add:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51
+
+ to your .pro file, and qmake will take care of this for you.
+
+ For more information about C++ runtime environment, see \l
+ {http://developer.apple.com/documentation/DeveloperTools/Conceptual/CppRuntimeEnv/index.html}{Apple's Developer Website}
+
+ \section3 Deploying Phonon Applications on Mac OS X
+
+ \list
+
+ \o If you build your Qt 4.6 Phonon application on OS X 10.4
+ (Tiger), it will run on OS X 10.4 and higher.
+
+ \o If you are using Leopard but would like to build your application
+ against Tiger, you can use:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51b
+ \endlist
+
+ \section2 Architecture Dependencies
+
+ The Qt for Mac OS X libraries, tools, and examples can be built
+ "universal" (i.e. they run natively on both Intel and PowerPC
+ machines). This is accomplished by passing \c -universal on the
+ \c configure line of the source package, and requires that you use
+ GCC 4.0.x. On PowerPC hardware you will need to pass the universal
+ SDK as a command line argument to the Qt configure command. For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 52
+
+ From 4.1.1 the Qt binary package is already universal.
+
+ If you want to create a binary that runs on older versions of
+ PowerPC and x86, it is possible to build Qt for the PowerPC using
+ GCC 3.3, and for x86 one using GCC 4.0, and use Apple's \c lipo(1)
+ tool to stitch them together. This is beyond the scope of this
+ document and is not something we have tried, but Apple documents
+ it on their \l
+ {http://developer.apple.com/documentation/}{developer website}.
+
+ Once you have a universal Qt, \a qmake will generate makefiles
+ that will build for its host architecture by default. If you want
+ to build for a specific architecture, you can control this with
+ the \c CONFIG line in your \c .pro file. Use \c CONFIG+=ppc for
+ PowerPC, and \c CONFIG+=x86 for x86. If you desire both, simply
+ add both to the \c CONFIG line. PowerPC users also need an
+ SDK. For example:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 53
+
+ Besides \c lipo, you can also check your binaries with the \c file(1)
+ command line tool or the Finder.
+
+ \section1 The Mac Deployment Tool
+ \target macdeploy
+ The Mac deployment tool can be found in QTDIR/bin/macdeployqt. It is
+ designed to automate the process of creating a deployable
+ application bundle that contains the Qt libraries as private
+ frameworks.
+
+ The mac deployment tool also deploys the Qt plugins, according
+ to the following rules:
+ \list
+ \o Debug versions of the plugins are not deployed.
+ \o The designer plugins are not deployed.
+ \o The Image format plugins are always deployed.
+ \o SQL driver plugins are deployed if the application uses the QtSql module.
+ \o Script plugins are deployed if the application uses the QtScript module.
+ \o The Phonon backend plugin is deployed if the application uses the \l{Phonon Module} {Phonon} module.
+ \o The svg icon plugin is deployed if the application uses the QtSvg module.
+ \o The accessibility plugin is always deployed.
+ \o Accessibility for Qt3Support is deployed if the application uses the Qt3Support module.
+ \endlist
+
+ \note If you want a 3rd party library to be included in your
+ application bundle, then you must add an excplicit lib entry for
+ that library to your application's .pro file. Otherwise, the
+ \c macdeployqt tool will not copy the 3rd party .dylib into the
+ bundle.
+
+ \c macdeployqt supports the following options:
+ \list
+ \o -no-plugins: Skip plugin deployment
+ \o -dmg : Create a .dmg disk image
+ \o -no-strip : Don't run 'strip' on the binaries
+ \endlist
+*/
+
+/*!
+ \page deployment-symbian.html
+ \contentspage Deploying Qt Applications
+
+ \title Deploying an Application on the Symbian platform
+
+ Applications are deployed to Symbian devices in signed \c .sis package files.
+ The \c .sis file content is controlled with \c .pkg files. The \c .pkg file contains a set
+ of instructions used by tools to produce a \c .sis file. \c qmake generates a
+ default \c .pkg file for your project. The \c .pkg file generated by \c qmake is typically
+ fully functional for testing purposes but when planning to deliver your application
+ to end-users some changes are needed. This document describes what changes are
+ typically needed and how to implement them.
+
+ \section1 Static Linking
+
+ Qt for the Symbian platform does currently not support static linking of
+ Qt libraries.
+
+ \section1 Shared Libraries
+
+ When deploying the application using the shared libraries approach we must ensure that the
+ Qt runtime is correctly redistributed along with the application executable,
+ and also that all Qt dependencies are redistributed along with the application.
+
+ We will demonstrate these procedures in terms of deploying the \l {widgets/wiggly}{Wiggly}
+ application that is provided in Qt's examples directory.
+
+ \section2 Building Qt as a Shared Library
+
+ We assume that you already have installed Qt as a shared library,
+ in the \c C:\path\to\Qt directory which is the default when installing Qt for Symbian.
+ For more information on how to build Qt, see the \l {Installation} documentation.
+
+ \section1 Shared Libraries
+
+ After ensuring that Qt is built as a shared library, we can build
+ the \l {widgets/wiggly}{Wiggly} application. First, we
+ must go into the directory that contains the application:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 55
+
+ To prepare the application for deployment we must ensure that the \c .pkg file generated by
+ \c qmake contains the relevant vendor information and embeds the necessary
+ dependencies to the application deployment file (\c .sis). The content of the generated \c .pkg
+ file can be controlled with the Symbian specific \c qmake \l DEPLOYMENT keyword extensions.
+
+ First, we will change the vendor statement to something more meaningful. The application
+ vendor is visible to end-user during the installation.
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 56
+
+ Second we will tell the Symbian application installer that this application supports
+ only S60 5.0 based devices:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 57
+
+ You can find a list of platform and device indentification codes from
+ \l {http://wiki.forum.nokia.com/index.php/S60_Platform_and_device_identification_codes}{Forum Nokia Wiki}.
+ By default \c .pkg file generated by \c qmake adds support for all
+ S60 3rd edition FP1, S60 3rd edition FP2 and S60 5th edition devices.
+
+ Now we are ready to compile the application and create the application
+ deployment file. Run \c qmake to create Symbian specific makefiles, resources (\.rss)
+ and deployment packaging files (\c .pkg). And do build to create the
+ application binaries and resources.
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 58
+
+ If everything compiled and linked without any errors, we are now ready to create
+ an application installation package (\c wiggly_installer.sis).
+
+ If you haven't done so already, download the latest release of the Smart Installer
+ from \l{http://get.qt.nokia.com/nokiasmartinstaller/}, and install it on top of the Qt package
+
+ Then use this command to create the installer sis package:
+
+ \snippet doc/src/snippets/code/doc_src_deployment.qdoc 59
+
+ If all binaries and dependencies were found, you should now have a self signed
+ \c wiggly_installer.sis ready to be installed on a device. The smart installer
+ contained in the in the installer package will download the necessary dependencies
+ such as Qt libraries to the device.
+
+ \note If you want to have your application properly Symbian Signed for distribution,
+ you will have to properly sign both the application and the application installer packages.
+ Please see
+ \l{http://developer.symbian.org/wiki/index.php/Category:Symbian_Signed}
+ {Symbian Signed wiki} for more information about Symbian Signed.
+
+ For more information about creating a \c .sis file and installing it to device see also
+ \l {The Symbian platform - Introduction to Qt#Installing your own applications}{here}.
+
+*/