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 deployment.html

    44     \title Deploying Qt Applications

    45 

    46     Deploying an Qt application does not require any C++

    47     programming. All you need to do is to build Qt and your

    48     application in release mode, following the procedures described in

    49     this documentation. We will demonstrate the procedures in terms of

    50     deploying the \l {tools/plugandpaint}{Plug & Paint} application

    51     that is provided in Qt's examples directory.

    52 

    53     \section1 Static vs. Shared Libraries

    54 

    55     There are two ways of deploying an application:

    56 

    57     \list

    58         \o Static Linking

    59         \o Shared Libraries (Frameworks on Mac)

    60     \endlist

    61 

    62     Static linking results in a stand-alone executable. The advantage

    63     is that you will only have a few files to deploy. The

    64     disadvantages are that the executables are large and with no

    65     flexibility (i.e a new version of the application, or of Qt, will

    66     require that the deployment process is repeated), and that you

    67     cannot deploy plugins.

    68 

    69     To deploy plugin-based applications, you can use the shared

    70     library approach. Shared libraries also provide smaller, more

    71     flexible executables. For example, using the shared library

    72     approach, the user is able to independently upgrade the Qt library

    73     used by the application.

    74 

    75     Another reason why you might want to use the shared library

    76     approach, is if you want to use the same Qt libraries for a family

    77     of applications. In fact, if you download the binary installation

    78     of Qt, you get Qt as a shared library.

    79 

    80     The disadvantage with the shared library approach is that you

    81     will get more files to deploy. For more information, see

    82     \l{sharedlibrary.html}{Creating Shared Libraries}.

    83 

    84     \section1 Deploying Qt's Libraries

    85 

    86     \table

    87     \header

    88         \o {4,1} Qt's Libraries

    89     \row

    90         \o \l {QtAssistant}

    91         \o \l {QAxContainer}

    92         \o \l {QAxServer}

    93         \o \l {QtCore}

    94     \row

    95         \o \l {QtDBus}

    96         \o \l {QtDesigner}

    97         \o \l {QtGui}

    98         \o \l {QtHelp}

    99     \row

   100         \o \l {QtNetwork}

   101         \o \l {QtOpenGL}

   102         \o \l {QtScript}

   103         \o \l {QtScriptTools}

   104     \row

   105         \o \l {QtSql}

   106         \o \l {QtSvg}

   107         \o \l {QtWebKit}

   108         \o \l {QtXml}

   109     \row

   110         \o \l {QtXmlPatterns}

   111         \o \l {Phonon Module}{Phonon}

   112         \o \l {Qt3Support}

   113     \endtable

   114 

   115     Since Qt is not a system library, it has to be redistributed along

   116     with your application; the minimum is to redistribute the run-time

   117     of the libraries used by the application.  Using static linking,

   118     however, the Qt run-time is compiled into the executable.

   119 

   120     In particular, you will need to deploy Qt plugins, such as

   121     JPEG support or SQL drivers. For more information about plugins,

   122     see the \l {plugins-howto.html}{How to Create Qt Plugins}

   123     documentation.

   124 

   125     When deploying an application using the shared library approach

   126     you must ensure that the Qt libraries will use the correct path to

   127     find the Qt plugins, documentation, translation etc. To do this you

   128     can use a \c qt.conf file. For more information, see the \l {Using

   129     qt.conf} documentation.

   130 

   131     Depending on configuration, compiler specific libraries must be

   132     redistributed as well. For more information, see the platform

   133     specific Application Dependencies sections: \l

   134     {deployment-x11.html#application-dependencies}{X11}, \l

   135     {deployment-windows.html#application-dependencies}{Windows}, \l

   136     {deployment-mac.html#application-dependencies}{Mac}.

   137 

   138     \section1 Licensing

   139 

   140     Some of Qt's libraries are based on third party libraries that are

   141     not licensed using the same dual-license model as Qt. As a result,

   142     care must be taken when deploying applications that use these

   143     libraries, particularly when the application is statically linked

   144     to them.

   145 

   146     The following table contains an inexhaustive summary of the issues

   147     you should be aware of.

   148 

   149     \table

   150     \header \o Qt Library \o Dependency

   151             \o Licensing Issue

   152     \row    \o QtHelp     \o CLucene

   153     \o The version of clucene distributed with Qt is licensed

   154     under the GNU LGPL version 2.1 or later. This has implications for

   155     developers of closed source applications. Please see

   156     \l{QtHelp Module#License Information}{the QtHelp module documentation}

   157     for more information.

   158 

   159     \row    \o QtNetwork  \o OpenSSL

   160     \o Some configurations of QtNetwork use OpenSSL at run-time. Deployment

   161     of OpenSSL libraries is subject to both licensing and export restrictions.

   162     More information can be found in the \l{Secure Sockets Layer (SSL) Classes}

   163     documentation.

   164 

   165     \row    \o QtWebKit   \o WebKit

   166     \o WebKit is licensed under the GNU LGPL version 2 or later.

   167     This has implications for developers of closed source applications.

   168     Please see \l{QtWebKit Module#License Information}{the QtWebKit module

   169     documentation} for more information.

   170 

   171     \row    \o \l{Phonon Module}{Phonon}     \o Phonon

   172     \o Phonon relies on the native multimedia engines on different platforms.

   173     Phonon itself is licensed under the GNU LGPL version 2. Please see

   174     \l{Phonon Module#License Information}{the Phonon module documentation}

   175     for more information on licensing and the

   176     \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends

   177     in use on different platforms.

   178     \endtable

   179 

   180     \section1 Platform-Specific Notes

   181 

   182     The procedure of deploying Qt applications is different for the

   183     various platforms:

   184 

   185     \list

   186         \o \l{Deploying an Application on X11 Platforms}{Qt for X11 Platforms}

   187         \o \l{Deploying an Application on Windows}{Qt for Windows}

   188         \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X}

   189         \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux}

   190     \endlist

   191 

   192     \sa Installation {Platform-Specific Documentation}

   193 */

   194 

   195 /*!

   196     \page deployment-x11.html

   197     \contentspage Deploying Qt Applications

   198 

   199     \title Deploying an Application on X11 Platforms

   200 

   201     Due to the proliferation of Unix systems (commercial Unices, Linux

   202     distributions, etc.), deployment on Unix is a complex

   203     topic. Before we start, be aware that programs compiled for one

   204     Unix flavor will probably not run on a different Unix system. For

   205     example, unless you use a cross-compiler, you cannot compile your

   206     application on Irix and distribute it on AIX.

   207 

   208     Contents:

   209 

   210     \tableofcontents

   211 

   212     This documentation will describe how to determine which files you

   213     should include in your distribution, and how to make sure that the

   214     application will find them at run-time. We will demonstrate the

   215     procedures in terms of deploying the \l {tools/plugandpaint}{Plug

   216     & Paint} application that is provided in Qt's examples directory.

   217 

   218     \section1 Static Linking

   219 

   220     Static linking is often the safest and easiest way to distribute

   221     an application on Unix since it relieves you from the task of

   222     distributing the Qt libraries and ensuring that they are located

   223     in the default search path for libraries on the target system.

   224 

   225     \section2 Building Qt Statically

   226 

   227     To use this approach, you must start by installing a static version

   228     of the Qt library:

   229 

   230     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 0

   231 

   232     We specify the prefix so that we do not overwrite the existing Qt

   233     installation. The example above only builds the Qt libraries,

   234     i.e. the examples and Qt Designer will not be built.  When \c make

   235     is done, you will find the Qt libraries in the \c /path/to/Qt/lib

   236     directory.

   237 

   238     When linking your application against static Qt libraries, note

   239     that you might need to add more libraries to the \c LIBS line in

   240     your project file. For more information, see the \l {Application

   241     Dependencies} section.

   242 

   243     \section2 Linking the Application to the Static Version of Qt

   244 

   245     Once Qt is built statically, the next step is to regenerate the

   246     makefile and rebuild the application. First, we must go into the

   247     directory that contains the application:

   248 

   249     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 1

   250 

   251     Now run qmake to create a new makefile for the application, and do

   252     a clean build to create the statically linked executable:

   253 

   254     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 2

   255 

   256     You probably want to link against the release libraries, and you

   257     can specify this when invoking \c qmake. Note that we must set the

   258     path to the static Qt that we just built.

   259 

   260     To check that the application really links statically with Qt, run

   261     the \c ldd tool (available on most Unices):

   262 

   263     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 3

   264 

   265     Verify that the Qt libraries are not mentioned in the output.

   266 

   267     Now, provided that everything compiled and linked without any

   268     errors, we should have a \c plugandpaint file that is ready for

   269     deployment. One easy way to check that the application really can

   270     be run stand-alone is to copy it to a machine that doesn't have Qt

   271     or any Qt applications installed, and run it on that machine.

   272 

   273     Remember that if your application depends on compiler specific

   274     libraries, these must still be redistributed along with your

   275     application. For more information, see the \l {Application

   276     Dependencies} section.

   277 

   278     The \l {tools/plugandpaint}{Plug & Paint} example consists of

   279     several components: The core application (\l

   280     {tools/plugandpaint}{Plug & Paint}), and the \l

   281     {tools/plugandpaintplugins/basictools}{Basic Tools} and \l

   282     {tools/plugandpaintplugins/extrafilters}{Extra Filters}

   283     plugins. Since we cannot deploy plugins using the static linking

   284     approach, the executable we have prepared so far is

   285     incomplete. The application will run, but the functionality will

   286     be disabled due to the missing plugins. To deploy plugin-based

   287     applications we should use the shared library approach.

   288 

   289     \section1 Shared Libraries

   290 

   291     We have two challenges when deploying the \l

   292     {tools/plugandpaint}{Plug & Paint} application using the shared

   293     libraries approach: The Qt runtime has to be correctly

   294     redistributed along with the application executable, and the

   295     plugins have to be installed in the correct location on the target

   296     system so that the application can find them.

   297 

   298     \section2 Building Qt as a Shared Library

   299 

   300     We assume that you already have installed Qt as a shared library,

   301     which is the default when installing Qt, in the \c /path/to/Qt

   302     directory. For more information on how to build Qt, see the \l

   303     {Installation} documentation.

   304 

   305     \section2 Linking the Application to Qt as a Shared Library

   306 

   307     After ensuring that Qt is built as a shared library, we can build

   308     the \l {tools/plugandpaint}{Plug & Paint} application. First, we

   309     must go into the directory that contains the application:

   310 

   311     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 4

   312 

   313     Now run qmake to create a new makefile for the application, and do

   314     a clean build to create the dynamically linked executable:

   315 

   316     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 5

   317 

   318     This builds the core application, the following will build the

   319     plugins:

   320 

   321     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 6

   322 

   323     If everything compiled and linked without any errors, we will get

   324     a \c plugandpaint executable and the \c libpnp_basictools.so and

   325     \c libpnp_extrafilters.so plugin files.

   326 

   327     \section2 Creating the Application Package

   328 

   329     There is no standard package management on Unix, so the method we

   330     present below is a generic solution. See the documentation for

   331     your target system for information on how to create a package.

   332 

   333     To deploy the application, we must make sure that we copy the

   334     relevant Qt libraries (corresponding to the Qt modules used in the

   335     application) as well as the executable to the same

   336     directory. Remember that if your application depends on compiler

   337     specific libraries, these must also be redistributed along with

   338     your application. For more information, see the \l {Application

   339     Dependencies} section.

   340 

   341     We'll cover the plugins shortly, but the main issue with shared

   342     libraries is that you must ensure that the dynamic linker will

   343     find the Qt libraries. Unless told otherwise, the dynamic linker

   344     doesn't search the directory where your application resides. There

   345     are many ways to solve this:

   346 

   347     \list

   348     

   349     \o You can install the Qt libraries in one of the system

   350        library paths (e.g. \c /usr/lib on most systems).

   351 

   352     \o You can pass a predetermined path to the \c -rpath command-line

   353        option when linking the application. This will tell the dynamic

   354        linker to look in this directory when starting your application.

   355 

   356     \o You can write a startup script for your application, where you

   357        modify the dynamic linker configuration (e.g.  adding your

   358        application's directory to the \c LD_LIBRARY_PATH environment

   359        variable. \note If your application will be running with "Set

   360        user ID on execution," and if it will be owned by root, then

   361        LD_LIBRARY_PATH will be ignored on some platforms. In this

   362        case, use of the LD_LIBRARY_PATH approach is not an option).

   363 

   364     \endlist

   365 

   366     The disadvantage of the first approach is that the user must have

   367     super user privileges. The disadvantage of the second approach is

   368     that the user may not have privileges to install into the

   369     predetemined path. In either case, the users don't have the option

   370     of installing to their home directory. We recommend using the

   371     third approach since it is the most flexible. For example, a \c

   372     plugandpaint.sh script will look like this:

   373 

   374     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 7

   375 

   376     By running this script instead of the executable, you are sure

   377     that the Qt libraries will be found by the dynamic linker. Note

   378     that you only have to rename the script to use it with other

   379     applications.

   380 

   381     When looking for plugins, the application searches in a plugins

   382     subdirectory inside the directory of the application

   383     executable. Either you have to manually copy the plugins into the

   384     \c plugins directory, or you can set the \c DESTDIR in the

   385     plugins' project files:

   386 

   387     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 8

   388 

   389     An archive distributing all the Qt libraries, and all the plugins,

   390     required to run the \l {tools/plugandpaint}{Plug & Paint}

   391     application, would have to include the following files:

   392 

   393     \table 100%

   394     \header

   395         \o Component \o {2, 1} File Name

   396     \row

   397         \o The executable

   398         \o {2, 1} \c plugandpaint

   399     \row

   400         \o The script to run the executable

   401         \o {2, 1} \c plugandpaint.sh

   402     \row

   403         \o The Basic Tools plugin

   404         \o {2, 1} \c plugins\libpnp_basictools.so

   405     \row

   406         \o The ExtraFilters plugin

   407         \o {2, 1} \c plugins\libpnp_extrafilters.so

   408     \row

   409         \o The Qt Core module

   410         \o {2, 1} \c libQtCore.so.4

   411     \row

   412         \o The Qt GUI module

   413         \o {2, 1} \c libQtGui.so.4

   414     \endtable

   415 

   416     On most systems, the extension for shared libraries is \c .so. A

   417     notable exception is HP-UX, which uses \c .sl.

   418 

   419     Remember that if your application depends on compiler specific

   420     libraries, these must still be redistributed along with your

   421     application. For more information, see the \l {Application

   422     Dependencies} section.

   423 

   424     To verify that the application now can be successfully deployed,

   425     you can extract this archive on a machine without Qt and without

   426     any compiler installed, and try to run it, i.e. run the \c

   427     plugandpaint.sh script.

   428 

   429     An alternative to putting the plugins in the \c plugins

   430     subdirectory is to add a custom search path when you start your

   431     application using QApplication::addLibraryPath() or

   432     QApplication::setLibraryPaths().

   433 

   434     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 9

   435 

   436     \section1 Application Dependencies

   437 

   438     \section2 Additional Libraries

   439 

   440     To find out which libraries your application depends on, run the

   441     \c ldd tool (available on most Unices):

   442 

   443     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 10

   444 

   445     This will list all the shared library dependencies for your

   446     application. Depending on configuration, these libraries must be

   447     redistributed along with your application. In particular, the

   448     standard C++ library must be redistributed if you're compiling

   449     your application with a compiler that is binary incompatible with

   450     the system compiler. When possible, the safest solution is to link

   451     against these libraries statically.

   452 

   453     You will probably want to link dynamically with the regular X11

   454     libraries, since some implementations will try to open other

   455     shared libraries with \c dlopen(), and if this fails, the X11

   456     library might cause your application to crash.

   457 

   458     It's also worth mentioning that Qt will look for certain X11

   459     extensions, such as Xinerama and Xrandr, and possibly pull them

   460     in, including all the libraries that they link against. If you

   461     can't guarantee the presence of a certain extension, the safest

   462     approach is to disable it when configuring Qt (e.g. \c {./configure

   463     -no-xrandr}).

   464 

   465     FontConfig and FreeType are other examples of libraries that

   466     aren't always available or that aren't always binary

   467     compatible. As strange as it may sound, some software vendors have

   468     had success by compiling their software on very old machines and

   469     have been very careful not to upgrade any of the software running

   470     on them.

   471 

   472     When linking your application against the static Qt libraries, you

   473     must explicitly link with the dependent libraries mentioned

   474     above. Do this by adding them to the \c LIBS variable in your

   475     project file.

   476 

   477     \section2 Qt Plugins

   478 

   479     Your application may also depend on one or more Qt plugins, such

   480     as the JPEG image format plugin or a SQL driver plugin. Be sure

   481     to distribute any Qt plugins that you need with your application,

   482     and note that each type of plugin should be located within a

   483     specific subdirectory (such as \c imageformats or \c sqldrivers)

   484     within your distribution directory, as described below.

   485 

   486     \note If you are deploying an application that uses QtWebKit to display

   487     HTML pages from the World Wide Web, you should include all text codec

   488     plugins to support as many HTML encodings possible. 

   489 

   490     The search path for Qt plugins (as well as a few other paths) is

   491     hard-coded into the QtCore library. By default, the first plugin

   492     search path will be hard-coded as \c /path/to/Qt/plugins. As

   493     mentioned above, using pre-determined paths has certain

   494     disadvantages, so you need to examine various alternatives to make

   495     sure that the Qt plugins are found:

   496 

   497     \list

   498 

   499     \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended

   500     approach since it provides the most flexibility.

   501 

   502     \o Using QApplication::addLibraryPath() or

   503     QApplication::setLibraryPaths().

   504 

   505     \o Using a third party installation utility or the target system's

   506     package manager to change the hard-coded paths in the QtCore

   507     library.

   508 

   509     \endlist

   510 

   511     The \l{How to Create Qt Plugins} document outlines the issues you

   512     need to pay attention to when building and deploying plugins for

   513     Qt applications.

   514 */

   515 

   516 /*!

   517     \page deployment-windows.html

   518     \contentspage Deploying Qt Applications

   519 

   520     \title Deploying an Application on Windows

   521 

   522     This documentation will describe how to determine which files you

   523     should include in your distribution, and how to make sure that the

   524     application will find them at run-time. We will demonstrate the

   525     procedures in terms of deploying the \l {tools/plugandpaint}{Plug

   526     & Paint} application that is provided in Qt's examples directory.

   527 

   528     Contents:

   529 

   530     \tableofcontents

   531 

   532     \section1 Static Linking

   533 

   534     If you want to keep things simple by only having a few files to

   535     deploy, i.e. a stand-alone executable with the associated compiler

   536     specific DLLs, then you must build everything statically.

   537 

   538     \section2 Building Qt Statically

   539 

   540     Before we can build our application we must make sure that Qt is

   541     built statically. To do this, go to a command prompt and type the

   542     following:

   543 

   544     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 11

   545 

   546     Remember to specify any other options you need, such as data base

   547     drivers, as arguments to \c configure. Once \c configure has

   548     finished, type the following:

   549 

   550     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 12

   551 

   552     This will build Qt statically. Note that unlike with a dynamic build,

   553     building Qt statically will result in libraries without version numbers;

   554     e.g. \c QtCore4.lib will be \c QtCore.lib. Also, we have used \c nmake

   555     in all the examples, but if you use MinGW you must use

   556     \c mingw32-make instead.

   557 

   558     \note If you later need to reconfigure and rebuild Qt from the

   559     same location, ensure that all traces of the previous configuration are

   560     removed by entering the build directory and typing \c{nmake distclean}

   561     before running \c configure again.

   562 

   563     \section2 Linking the Application to the Static Version of Qt

   564 

   565     Once Qt has finished building we can build the \l

   566     {tools/plugandpaint}{Plug & Paint} application. First we must go

   567     into the directory that contains the application:

   568 

   569     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 13

   570 

   571     We must then run \c qmake to create a new makefile for the

   572     application, and do a clean build to create the statically linked

   573     executable:

   574 

   575     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 14

   576 

   577     You probably want to link against the release libraries, and you

   578     can specify this when invoking \c qmake. Now, provided that

   579     everything compiled and linked without any errors, we should have

   580     a \c plugandpaint.exe file that is ready for deployment. One easy

   581     way to check that the application really can be run stand-alone is

   582     to copy it to a machine that doesn't have Qt or any Qt

   583     applications installed, and run it on that machine.

   584 

   585     Remember that if your application depends on compiler specific

   586     libraries, these must still be redistributed along with your

   587     application. You can check which libraries your application is

   588     linking against by using the \c depends tool. For more

   589     information, see the \l {Application Dependencies} section.

   590 

   591     The \l {tools/plugandpaint}{Plug & Paint} example consists of

   592     several components: The application itself (\l

   593     {tools/plugandpaint}{Plug & Paint}), and the \l

   594     {tools/plugandpaintplugins/basictools}{Basic Tools} and \l

   595     {tools/plugandpaintplugins/extrafilters}{Extra Filters}

   596     plugins. Since we cannot deploy plugins using the static linking

   597     approach, the application we have prepared is incomplete. It will

   598     run, but the functionality will be disabled due to the missing

   599     plugins. To deploy plugin-based applications we should use the

   600     shared library approach.

   601 

   602     \section1 Shared Libraries

   603 

   604     We have two challenges when deploying the \l

   605     {tools/plugandpaint}{Plug & Paint} application using the shared

   606     libraries approach: The Qt runtime has to be correctly

   607     redistributed along with the application executable, and the

   608     plugins have to be installed in the correct location on the target

   609     system so that the application can find them.

   610 

   611     \section2 Building Qt as a Shared Library

   612 

   613     We assume that you already have installed Qt as a shared library,

   614     which is the default when installing Qt, in the \c C:\path\to\Qt

   615     directory. For more information on how to build Qt, see the \l

   616     {Installation} documentation.

   617 

   618     \section2 Linking the Application to Qt as a Shared Library

   619 

   620     After ensuring that Qt is built as a shared library, we can build

   621     the \l {tools/plugandpaint}{Plug & Paint} application. First, we

   622     must go into the directory that contains the application:

   623 

   624     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 15

   625 

   626     Now run \c qmake to create a new makefile for the application, and

   627     do a clean build to create the dynamically linked executable:

   628 

   629     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 16

   630 

   631     This builds the core application, the following will build the

   632     plugins:

   633 

   634     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 17

   635 

   636     If everything compiled and linked without any errors, we will get

   637     a \c plugandpaint.exe executable and the \c pnp_basictools.dll and

   638     \c pnp_extrafilters.dll plugin files.

   639 

   640     \section2 Creating the Application Package

   641 

   642     To deploy the application, we must make sure that we copy the

   643     relevant Qt DLL (corresponding to the Qt modules used in

   644     the application) as well as the executable to the same directory

   645     in the \c release subdirectory.

   646 

   647     Remember that if your application depends on compiler specific

   648     libraries, these must be redistributed along with your

   649     application. You can check which libraries your application is

   650     linking against by using the \c depends tool. For more

   651     information, see the \l {Application Dependencies} section.

   652 

   653     We'll cover the plugins shortly, but first we'll check that the

   654     application will work in a deployed environment: Either copy the

   655     executable and the Qt DLLs to a machine that doesn't have Qt

   656     or any Qt applications installed, or if you want to test on the

   657     build machine, ensure that the machine doesn't have Qt in its

   658     environment.

   659 

   660     If the application starts without any problems, then we have

   661     successfully made a dynamically linked version of the \l

   662     {tools/plugandpaint}{Plug & Paint} application. But the

   663     application's functionality will still be missing since we have

   664     not yet deployed the associated plugins.

   665 

   666     Plugins work differently to normal DLLs, so we can't just

   667     copy them into the same directory as our application's executable

   668     as we did with the Qt DLLs.  When looking for plugins, the

   669     application searches in a \c plugins subdirectory inside the

   670     directory of the application executable.

   671 

   672     So to make the plugins available to our application, we have to

   673     create the \c plugins subdirectory and copy over the relevant DLLs:

   674 

   675     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 18

   676 

   677     An archive distributing all the Qt DLLs and application

   678     specific plugins required to run the \l {tools/plugandpaint}{Plug

   679     & Paint} application, would have to include the following files:

   680 

   681     \table 100%

   682     \header

   683         \o Component \o {2, 1} File Name

   684     \row

   685         \o The executable

   686         \o {2, 1} \c plugandpaint.exe

   687     \row

   688         \o The Basic Tools plugin

   689         \o {2, 1} \c plugins\pnp_basictools.dll

   690     \row

   691         \o The ExtraFilters plugin

   692         \o {2, 1} \c plugins\pnp_extrafilters.dll

   693     \row

   694         \o The Qt Core module

   695         \o {2, 1} \c qtcore4.dll

   696     \row

   697         \o The Qt GUI module

   698         \o {2, 1} \c qtgui4.dll

   699     \endtable

   700 

   701     In addition, the archive must contain the following compiler

   702     specific libraries depending on your version of Visual Studio:

   703 

   704     \table 100%

   705     \header

   706         \o \o VC++ 6.0 \o VC++ 7.1 (2003) \o VC++ 8.0 (2005) \o VC++ 9.0 (2008)

   707     \row

   708         \o The C run-time

   709         \o \c msvcrt.dll

   710         \o \c msvcr71.dll

   711         \o \c msvcr80.dll

   712         \o \c msvcr90.dll

   713     \row

   714         \o The C++ run-time

   715         \o \c msvcp60.dll

   716         \o \c msvcp71.dll

   717         \o \c msvcp80.dll

   718         \o \c msvcp90.dll

   719     \endtable

   720 

   721     To verify that the application now can be successfully deployed,

   722     you can extract this archive on a machine without Qt and without

   723     any compiler installed, and try to run it.

   724 

   725     An alternative to putting the plugins in the plugins subdirectory

   726     is to add a custom search path when you start your application

   727     using QApplication::addLibraryPath() or

   728     QApplication::setLibraryPaths().

   729 

   730     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 19

   731 

   732     One benefit of using plugins is that they can easily be made

   733     available to a whole family of applications.

   734 

   735     It's often most convenient to add the path in the application's \c

   736     main() function, right after the QApplication object is

   737     created. Once the path is added, the application will search it

   738     for plugins, in addition to looking in the \c plugins subdirectory

   739     in the application's own directory. Any number of additional paths

   740     can be added.

   741 

   742     \section2 Visual Studio 2005 Onwards

   743 

   744     When deploying an application compiled with Visual Studio 2005 onwards,

   745     there are some additional steps to be taken.

   746 

   747     First, we need to copy the manifest file created when linking the

   748     application. This manifest file contains information about the

   749     application's dependencies on side-by-side assemblies, such as the runtime

   750     libraries.

   751 

   752     The manifest file needs to be copied into the \bold same folder as the

   753     application executable. You do not need to copy the manifest files for

   754     shared libraries (DLLs), since they are not used.

   755 

   756     If the shared library has dependencies that are different from the

   757     application using it, the manifest file needs to be embedded into the DLL

   758     binary. Since Qt 4.1.3, the follwoing \c CONFIG options are available for

   759     embedding manifests:

   760 

   761     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 20

   762 

   763     To use the options, add

   764 

   765     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 21

   766 

   767     to your .pro file. The \c embed_manifest_dll option is enabled by default.

   768 

   769     You can find more information about manifest files and side-by-side

   770     assemblies at the

   771     \l {http://msdn.microsoft.com/en-us/library/aa376307.aspx}{MSDN website}.

   772 

   773     There are two ways to include the run time libraries: by bundling them

   774     directly with your application or by installing them on the end-user's

   775     system.

   776 

   777     To bundle the run time libraries with your application, copy the directory

   778 

   779     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 22

   780 

   781     into the folder where your executable is, so that you are including a

   782     \c Microsoft.VC80.CRT directory alongside your application's executable. If

   783     you are bundling the runtimes and need to deploy plugins as well, you have

   784     to remove the manifest from the plugins (embedded as a resource) by adding

   785     the following line to the \c{.pro} file of the plugins you are compiling:

   786 

   787     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 23

   788 

   789     \warning If you skip the step above, the plugins will not load on some

   790     systems.

   791 

   792     To install the runtime libraries on the end-user's system, you need to

   793     include the appropriate Visual C++ Redistributable Package (VCRedist)

   794     executable with your application and ensure that it is executed when the

   795     user installs your application.

   796 

   797     For example, on an 32-bit x86-based system, you would include the

   798     \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE}{vcredist_x86.exe}

   799     executable. The \l{http://www.microsoft.com/downloads/details.aspx?familyid=526BF4A7-44E6-4A91-B328-A4594ADB70E5}{vcredist_IA64.exe}

   800     and \l{http://www.microsoft.com/downloads/details.aspx?familyid=90548130-4468-4BBC-9673-D6ACABD5D13B}{vcredist_x64.exe}

   801     executables provide the appropriate libraries for the IA64 and 64-bit x86

   802     architectures, respectively.

   803 

   804     \note The application you ship must be compiled with exactly the same

   805     compiler version against the same C runtime version. This prevents

   806     deploying errors caused by different versions of the C runtime libraries.

   807 

   808     \section2 Visual Studio 2008 And Manual Installs

   809 

   810     As well as the above details for VS 2005 and onwards, Visual Studio 2008

   811     applications may have problems when deploying manually, say to a USB

   812     stick.

   813 

   814     The recommended procedure is to configure Qt with the \c -plugin-manifests

   815     option using the 'configure' tool. Then follow the \l {http://msdn.microsoft.com/en-us/library/ms235291(VS.80).aspx}{guidelines}

   816     for manually deploying private assemblies.

   817 

   818     In brief the steps are

   819 

   820     \list 1

   821     

   822         \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'.

   823         

   824         \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.

   825         

   826         \o xcopy the \\app folder to the target USB stick.

   827     \endlist

   828 

   829     Your application should now run. Also be aware that even with a service

   830     pack installed the Windows DLLs that are linked to will be the defaults. See

   831     the information on \l {http://msdn.microsoft.com/en-us/library/cc664727.aspx}{how to select the appropriate target DLLs}.

   832 

   833     \section1 Application Dependencies

   834 

   835     \section2 Additional Libraries

   836 

   837     Depending on configuration, compiler specific libraries must be

   838     redistributed along with your application. You can check which

   839     libraries your application is linking against by using the

   840     \l{Dependency Walker} tool. All you need to do is to run it like

   841     this:

   842 

   843     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 24

   844 

   845     This will provide a list of the libraries that your application

   846     depends on and other information.

   847 

   848     \image deployment-windows-depends.png

   849 

   850     When looking at the release build of the Plug & Paint executable

   851     (\c plugandpaint.exe) with the \c depends tool, the tool lists the

   852     following immediate dependencies to non-system libraries:

   853 

   854     \table 100%

   855         \header

   856             \o Qt

   857             \o VC++ 6.0

   858             \o VC++ 7.1 (2003)

   859             \o VC++ 8.0 (2005)

   860             \o MinGW

   861         \row

   862         \o \list

   863                \o QTCORE4.DLL - The QtCore runtime

   864                \o QTGUI4.DLL - The QtGui runtime

   865            \endlist

   866         \o \list

   867                \o MSVCRT.DLL - The C runtime

   868                \o MSVCP60.DLL - The C++ runtime (only when STL is installed)

   869            \endlist

   870         \o \list

   871                \o MSVCR71.DLL - The C runtime

   872                \o MSVCP71.DLL - The C++ runtime (only when STL is installed)

   873            \endlist

   874         \o \list

   875                \o MSVCR80.DLL - The C runtime

   876                \o MSVCP80.DLL - The C++ runtime (only when STL is installed)

   877            \endlist

   878         \o \list

   879                \o MINGWM10.DLL - The MinGW run-time

   880            \endlist

   881     \endtable

   882 

   883     When looking at the plugin DLLs the exact same dependencies

   884     are listed.

   885 

   886     \section2 Qt Plugins

   887 

   888     Your application may also depend on one or more Qt plugins, such

   889     as the JPEG image format plugin or a SQL driver plugin. Be sure

   890     to distribute any Qt plugins that you need with your application,

   891     and note that each type of plugin should be located within a

   892     specific subdirectory (such as \c imageformats or \c sqldrivers)

   893     within your distribution directory, as described below.

   894 

   895     \note If you are deploying an application that uses QtWebKit to display

   896     HTML pages from the World Wide Web, you should include all text codec

   897     plugins to support as many HTML encodings possible. 

   898 

   899     The search path for Qt plugins is hard-coded into the QtCore library. 

   900     By default, the plugins subdirectory of the Qt installation is the first 

   901     plugin search path. However, pre-determined paths like the default one 

   902     have certain disadvantages. For example, they may not exist on the target 

   903     machine. For that reason, you need to examine various alternatives to make 

   904     sure that the Qt plugins are found:

   905 

   906     \list

   907 

   908     \o \l{qt-conf.html}{Using \c qt.conf}. This approach is the recommended 

   909     if you have executables in different places sharing the same plugins.

   910 

   911     \o Using QApplication::addLibraryPath() or

   912     QApplication::setLibraryPaths(). This approach is recommended if you only 

   913     have one executable that will use the plugin. 

   914 

   915     \o Using a third party installation utility to change the

   916     hard-coded paths in the QtCore library.

   917 

   918     \endlist

   919 

   920     If you add a custom path using QApplication::addLibraryPath it could 

   921     look like this:

   922 

   923     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 54

   924 

   925     Then qApp->libraryPaths() would return something like this:

   926 

   927     "C:/customPath/plugins " 

   928     "C:/Qt/%VERSION%/plugins" 

   929     "E:/myApplication/directory/"

   930 

   931     The executable will look for the plugins in these directories and 

   932     the same order as the QStringList returned by qApp->libraryPaths(). 

   933     The newly added path is prepended to the qApp->libraryPaths() which 

   934     means that it will be searched through first. However, if you use 

   935     qApp->setLibraryPaths(), you will be able to determend which paths 

   936     and in which order they will be searched.

   937 

   938     The \l{How to Create Qt Plugins} document outlines the issues you

   939     need to pay attention to when building and deploying plugins for

   940     Qt applications.

   941 

   942     \section1 Related Third Party Resources

   943 

   944     \list

   945     \o \l{http://silmor.de/29}{Cross compiling Qt/Win Apps on Linux} covers the

   946     process of cross-compiling Windows applications on Linux.

   947     \o \l{http://divided-mind.blogspot.com/2007/09/cross-compiling-qt4win-on-linux.html}

   948     {Cross-compiling Qt4/Win on Linux} provides another Linux-to-Windows

   949     cross-compilation guide.

   950     \endlist

   951 */

   952 

   953 /*!

   954     \page deployment-mac.html

   955     \contentspage Deploying Qt Applications

   956 

   957     \title Deploying an Application on Mac OS X

   958 

   959     Starting with version 4.5, Qt now includes a \l {macdeploy}{deployment tool}

   960     that automates the prodecures described in this document.

   961 

   962     This documentation will describe how to create a bundle, and how

   963     to make sure that the application will find the resources it needs

   964     at run-time. We will demonstrate the procedures in terms of

   965     deploying the \l {tools/plugandpaint}{Plug & Paint} application

   966     that is provided in Qt's examples directory.

   967     

   968     \tableofcontents

   969 

   970     \section1 The Bundle

   971 

   972     On the Mac, a GUI application must be built and run from a

   973     bundle. A bundle is a directory structure that appears as a single

   974     entity when viewed in the Finder. A bundle for an application

   975     typcially contains the executable and all the resources it

   976     needs. See the image below:

   977 

   978     \image deployment-mac-bundlestructure.png

   979 

   980     The bundle provides many advantages to the user. One primary

   981     advantage is that, since it is a single entity, it allows for

   982     drag-and-drop installation. As a programmer you can access bundle

   983     information in your own code. This is specific to Mac OS X and

   984     beyond the scope of this document. More information about bundles

   985     is available on \l

   986     {http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html}{Apple's Developer Website}.

   987 

   988     A Qt command line application on Mac OS X works similar to a

   989     command line application on Unix and Windows. You probably don't

   990     want to run it in a bundle: Add this to your application's .pro:

   991 

   992     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 26

   993 

   994     This will tell \c qmake not to put the executable inside a

   995     bundle. Please refer to the \l{Deploying an Application on

   996     X11 Platforms}{X11 deployment documentation} for information about how

   997     to deploy these "bundle-less" applications.

   998 

   999     \section1 Xcode

  1000 

  1001     We will only concern ourselves with command-line tools here. While

  1002     it is possible to use Xcode for this, Xcode has changed enough

  1003     between each version that it makes it difficult to document it

  1004     perfectly for each version. A future version of this document may

  1005     include more information for using Xcode in the deployment

  1006     process.

  1007 

  1008     \section1 Static Linking

  1009 

  1010     If you want to keep things simple by only having a few files to

  1011     deploy, then you must build everything statically.

  1012 

  1013     \section2 Building Qt Statically

  1014 

  1015     Start by installing a static version of the Qt library. Remember

  1016     that you will not be able to use plugins and you must build in all

  1017     the image formats, SQL drivers, etc..

  1018 

  1019     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 27

  1020 

  1021     You can check the various options that are available by running \c

  1022     configure -help.

  1023 

  1024     \section2 Linking the Application to the Static Version of Qt

  1025 

  1026     Once Qt is built statically, the next step is to regenerate the

  1027     makefile and rebuild the application. First, we must go into the

  1028     directory that contains the application:

  1029 

  1030     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 28

  1031 

  1032     Now run \c qmake to create a new makefile for the application, and do

  1033     a clean build to create the statically linked executable:

  1034 

  1035     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 29

  1036 

  1037     You probably want to link against the release libraries, and you

  1038     can specify this when invoking \c qmake. If you have Xcode Tools

  1039     1.5 or higher installed, you may want to take advantage of "dead

  1040     code stripping" to reduce the size of your binary even more. You

  1041     can do this by passing \c {LIBS+= -dead_strip} to \c qmake in

  1042     addition to the \c {-config release} parameter. This doesn't have

  1043     as large an effect if you are using GCC 4, since Qt will then have

  1044     function visibility hints built-in, but if you use GCC 3.3, it

  1045     could make a difference.

  1046 

  1047     Now, provided that everything compiled and linked without any

  1048     errors, we should have a \c plugandpaint.app bundle that is ready

  1049     for deployment. One easy way to check that the application really

  1050     can be run stand-alone is to copy the bundle to a machine that

  1051     doesn't have Qt or any Qt applications installed, and run the

  1052     application on that machine.

  1053 

  1054     You can check what other libraries your application links to using

  1055     the \c otool:

  1056 

  1057     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 30

  1058 

  1059     Here is what the output looks like for the static \l

  1060     {tools/plugandpaint}{Plug & Paint}:

  1061 

  1062     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 31

  1063 

  1064     For more information, see the \l {Application Dependencies}

  1065     section.

  1066 

  1067     If you see \e Qt libraries in the output, it probably

  1068     means that you have both dynamic and static Qt libraries installed

  1069     on your machine. The linker will always choose dynamic over

  1070     static. There are two solutions: Either move your Qt dynamic

  1071     libraries (\c .dylibs) away to another directory while you link

  1072     the application and then move them back, or edit the \c Makefile

  1073     and replace link lines for the Qt libraries with the absolute path

  1074     to the static libraries. For example, replace

  1075 

  1076     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 32

  1077 

  1078     with

  1079 

  1080     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 33

  1081 

  1082     The \l {tools/plugandpaint}{Plug & Paint} example consists of

  1083     several components: The core application (\l

  1084     {tools/plugandpaint}{Plug & Paint}), and the \l

  1085     {tools/plugandpaintplugins/basictools}{Basic Tools} and \l

  1086     {tools/plugandpaintplugins/extrafilters}{Extra Filters}

  1087     plugins. Since we cannot deploy plugins using the static linking

  1088     approach, the bundle we have prepared so far is incomplete. The

  1089     application will run, but the functionality will be disabled due

  1090     to the missing plugins. To deploy plugin-based applications we

  1091     should use the framework approach.

  1092 

  1093     \section1 Frameworks

  1094 

  1095     We have two challenges when deploying the \l

  1096     {tools/plugandpaint}{Plug & Paint} application using frameworks:

  1097     The Qt runtime has to be correctly redistributed along with the

  1098     application bundle, and the plugins have to be installed in the

  1099     correct location so that the application can find them.

  1100 

  1101     When distributing Qt with your application using frameworks, you

  1102     have two options: You can either distribute Qt as a private

  1103     framework within your application bundle, or you can distribute Qt

  1104     as a standard framework (alternatively use the Qt frameworks in

  1105     the installed binary). These two approaches are essentially the

  1106     same. The latter option is good if you have many Qt applications

  1107     and you would prefer to save memory. The former is good if you

  1108     have Qt built in a special way, or want to make sure the framework

  1109     is there. It just comes down to where you place the Qt frameworks.

  1110 

  1111     \section2 Building Qt as Frameworks

  1112 

  1113     We assume that you already have installed Qt as frameworks, which

  1114     is the default when installing Qt, in the /path/to/Qt

  1115     directory. For more information on how to build Qt, see the \l

  1116     Installation documentation.

  1117 

  1118     When installing, the identification name of the frameworks will

  1119     also be set. The identification name is what the dynamic linker

  1120     (\c dyld) uses to find the libraries for your application.

  1121 

  1122     \section2 Linking the Application to Qt as Frameworks

  1123 

  1124     After ensuring that Qt is built as frameworks, we can build the \l

  1125     {tools/plugandpaint}{Plug & Paint} application. First, we must go

  1126     into the directory that contains the application:

  1127 

  1128     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 34

  1129 

  1130     Now run qmake to create a new makefile for the application, and do

  1131     a clean build to create the dynamically linked executable:

  1132 

  1133     \snippet doc/src/snippets/code/doc_src_deployment.qdoc 35

  1134 

  1135     This builds the core application, the following will build the