1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 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         \o

   114     \endtable

   115 

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

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

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

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

   120 

   121     In general, you should deploy all plugins that your build of Qt uses,

   122     excluding only those that you have identified as being unnecessary

   123     for your application and its users.

   124 

   125     For instance, you may need to deploy plugins for JPEG support and

   126     SQL drivers, but you should also deploy plugins that your users may

   127     require, including those for accessibility.

   128     For more information about plugins, see the

   129     \l{plugins-howto.html}{How to Create Qt Plugins} documentation.

   130 

   131     When deploying an application using the shared library approach

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

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

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

   135     qt.conf} documentation.

   136 

   137     Depending on configuration, compiler specific libraries must be

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

   139     specific Application Dependencies sections: \l

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

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

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

   143 

   144     \section1 Licensing

   145 

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

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

   148     care must be taken when deploying applications that use these

   149     libraries, particularly when the application is statically linked

   150     to them.

   151 

   152     The following table contains an inexhaustive summary of the issues

   153     you should be aware of.

   154 

   155     \table

   156     \header \o Qt Library \o Dependency

   157             \o Licensing Issue

   158     \row    \o QtHelp     \o CLucene

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

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

   161     developers of closed source applications. Please see

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

   163     for more information.

   164 

   165     \row    \o QtNetwork  \o OpenSSL

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

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

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

   169     documentation.

   170 

   171     \row    \o QtWebKit   \o WebKit

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

   173     This has implications for developers of closed source applications.

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

   175     documentation} for more information.

   176 

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

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

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

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

   181     for more information on licensing and the

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

   183     in use on different platforms.

   184     \endtable

   185 

   186     \section1 Platform-Specific Notes

   187 

   188     The procedure of deploying Qt applications is different for the

   189     various platforms:

   190 

   191     \list

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

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

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

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

   196         \o \l{Deploying an Application on the Symbian platform}{Qt for the Symbian platform}

   197     \endlist

   198 

   199     \sa Installation {Platform-Specific Documentation}

   200 */

   201 

   202 /*!

   203     \page deployment-x11.html

   204     \contentspage Deploying Qt Applications

   205 

   206     \title Deploying an Application on X11 Platforms

   207 

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

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

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

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

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

   213     application on Irix and distribute it on AIX.

   214 

   215     Contents:

   216 

   217     \tableofcontents

   218 

   219     This documentation will describe how to determine which files you

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

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

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

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

   224 

   225     \section1 Static Linking

   226 

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

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

   229     distributing the Qt libraries and ensuring that they are located

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

   231 

   232     \section2 Building Qt Statically

   233 

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

   235     of the Qt library:

   236 

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

   238 

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

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

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

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

   243     directory.

   244 

   245     When linking your application against static Qt libraries, note

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

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

   248     Dependencies} section.

   249 

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

   251 

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

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

   254     directory that contains the application:

   255 

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

   257 

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

   259     a clean build to create the statically linked executable:

   260 

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

   262 

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

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

   265     path to the static Qt that we just built.

   266 

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

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

   269 

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

   271 

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

   273 

   274     Now, provided that everything compiled and linked without any

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

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

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

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

   279 

   280     Remember that if your application depends on compiler specific

   281     libraries, these must still be redistributed along with your

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

   283     Dependencies} section.

   284 

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

   286     several components: The core application (\l

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

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

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

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

   291     approach, the executable we have prepared so far is

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

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

   294     applications we should use the shared library approach.

   295 

   296     \section1 Shared Libraries

   297 

   298     We have two challenges when deploying the \l

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

   300     libraries approach: The Qt runtime has to be correctly

   301     redistributed along with the application executable, and the

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

   303     system so that the application can find them.

   304 

   305     \section2 Building Qt as a Shared Library

   306 

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

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

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

   310     {Installation} documentation.

   311 

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

   313 

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

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

   316     must go into the directory that contains the application:

   317 

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

   319 

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

   321     a clean build to create the dynamically linked executable:

   322 

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

   324 

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

   326     plugins:

   327 

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

   329 

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

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

   332     \c libpnp_extrafilters.so plugin files.

   333 

   334     \section2 Creating the Application Package

   335 

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

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

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

   339 

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

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

   342     application) as well as the executable to the same

   343     directory. Remember that if your application depends on compiler

   344     specific libraries, these must also be redistributed along with

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

   346     Dependencies} section.

   347 

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

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

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

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

   352     are many ways to solve this:

   353 

   354     \list

   355     

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

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

   358 

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

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

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

   362 

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

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

   365        application's directory to the \c LD_LIBRARY_PATH environment

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

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

   368        LD_LIBRARY_PATH will be ignored on some platforms. In this

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

   370 

   371     \endlist

   372 

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

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

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

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

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

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

   379     plugandpaint.sh script will look like this:

   380 

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

   382 

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

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

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

   386     applications.

   387 

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

   389     subdirectory inside the directory of the application

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

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

   392     plugins' project files:

   393 

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

   395 

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

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

   398     application, would have to include the following files:

   399 

   400     \table 100%

   401     \header

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

   403     \row

   404         \o The executable

   405         \o {2, 1} \c plugandpaint

   406     \row

   407         \o The script to run the executable

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

   409     \row

   410         \o The Basic Tools plugin

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

   412     \row

   413         \o The ExtraFilters plugin

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

   415     \row

   416         \o The Qt Core module

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

   418     \row

   419         \o The Qt GUI module

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

   421     \endtable

   422 

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

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

   425 

   426     Remember that if your application depends on compiler specific

   427     libraries, these must still be redistributed along with your

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

   429     Dependencies} section.

   430 

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

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

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

   434     plugandpaint.sh script.

   435 

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

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

   438     application using QApplication::addLibraryPath() or

   439     QApplication::setLibraryPaths().

   440 

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

   442 

   443     \section1 Application Dependencies

   444 

   445     \section2 Additional Libraries

   446 

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

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

   449 

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

   451 

   452     This will list all the shared library dependencies for your

   453     application. Depending on configuration, these libraries must be

   454     redistributed along with your application. In particular, the

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

   456     your application with a compiler that is binary incompatible with

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

   458     against these libraries statically.

   459 

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

   461     libraries, since some implementations will try to open other

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

   463     library might cause your application to crash.

   464 

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

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

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

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

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

   470     -no-xrandr}).

   471 

   472     FontConfig and FreeType are other examples of libraries that

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

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

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

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

   477     on them.

   478 

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

   480     must explicitly link with the dependent libraries mentioned

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

   482     project file.

   483 

   484     \section2 Qt Plugins

   485 

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

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

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

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

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

   491     within your distribution directory, as described below.

   492 

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

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

   495     plugins to support as many HTML encodings possible. 

   496 

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

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

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

   500     mentioned above, using pre-determined paths has certain

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

   502     sure that the Qt plugins are found:

   503 

   504     \list

   505 

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

   507     approach since it provides the most flexibility.

   508 

   509     \o Using QApplication::addLibraryPath() or

   510     QApplication::setLibraryPaths().

   511 

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

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

   514     library.

   515 

   516     \endlist

   517 

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

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

   520     Qt applications.

   521 */

   522 

   523 /*!

   524     \page deployment-windows.html

   525     \contentspage Deploying Qt Applications

   526 

   527     \title Deploying an Application on Windows

   528 

   529     This documentation will describe how to determine which files you

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

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

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

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

   534 

   535     Contents:

   536 

   537     \tableofcontents

   538 

   539     \section1 Static Linking

   540 

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

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

   543     specific DLLs, then you must build everything statically.

   544 

   545     \section2 Building Qt Statically

   546 

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

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

   549     following:

   550 

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

   552 

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

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

   555     finished, type the following:

   556 

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

   558 

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

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

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

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

   563     \c mingw32-make instead.

   564 

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

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

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

   568     before running \c configure again.

   569 

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

   571 

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

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

   574     into the directory that contains the application:

   575 

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

   577 

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

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

   580     executable:

   581 

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

   583 

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

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

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

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

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

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

   590     applications installed, and run it on that machine.

   591 

   592     Remember that if your application depends on compiler specific

   593     libraries, these must still be redistributed along with your

   594     application. You can check which libraries your application is

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

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

   597 

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

   599     several components: The application itself (\l

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

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

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

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

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

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

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

   607     shared library approach.

   608 

   609     \section1 Shared Libraries

   610 

   611     We have two challenges when deploying the \l

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

   613     libraries approach: The Qt runtime has to be correctly

   614     redistributed along with the application executable, and the

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

   616     system so that the application can find them.

   617 

   618     \section2 Building Qt as a Shared Library

   619 

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

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

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

   623     {Installation} documentation.

   624 

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

   626 

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

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

   629     must go into the directory that contains the application:

   630 

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

   632 

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

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

   635 

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

   637 

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

   639     plugins:

   640 

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

   642 

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

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

   645     \c pnp_extrafilters.dll plugin files.

   646 

   647     \section2 Creating the Application Package

   648 

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

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

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

   652     in the \c release subdirectory.

   653 

   654     Remember that if your application depends on compiler specific

   655     libraries, these must be redistributed along with your

   656     application. You can check which libraries your application is

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

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

   659 

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

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

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

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

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

   665     environment.

   666 

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

   668     successfully made a dynamically linked version of the \l

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

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

   671     not yet deployed the associated plugins.

   672 

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

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

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

   676     application searches in a \c plugins subdirectory inside the

   677     directory of the application executable.

   678 

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

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

   681 

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

   683 

   684     An archive distributing all the Qt DLLs and application

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

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

   687 

   688     \table 100%

   689     \header

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

   691     \row

   692         \o The executable

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

   694     \row

   695         \o The Basic Tools plugin

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

   697     \row

   698         \o The ExtraFilters plugin

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

   700     \row

   701         \o The Qt Core module

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

   703     \row

   704         \o The Qt GUI module

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

   706     \endtable

   707 

   708     In addition, the archive must contain the following compiler

   709     specific libraries depending on your version of Visual Studio:

   710 

   711     \table 100%

   712     \header

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

   714     \row

   715         \o The C run-time

   716         \o \c msvcrt.dll

   717         \o \c msvcr71.dll

   718         \o \c msvcr80.dll

   719         \o \c msvcr90.dll

   720     \row

   721         \o The C++ run-time

   722         \o \c msvcp60.dll

   723         \o \c msvcp71.dll

   724         \o \c msvcp80.dll

   725         \o \c msvcp90.dll

   726     \endtable

   727 

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

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

   730     any compiler installed, and try to run it.

   731 

   732     An alternative to putting the plugins in the plugins subdirectory

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

   734     using QApplication::addLibraryPath() or

   735     QApplication::setLibraryPaths().

   736 

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

   738 

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

   740     available to a whole family of applications.

   741 

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

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

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

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

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

   747     can be added.

   748 

   749     \section2 Visual Studio 2005 Onwards

   750 

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

   752     there are some additional steps to be taken.

   753 

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

   755     application. This manifest file contains information about the

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

   757     libraries.

   758 

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

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

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

   762 

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

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

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

   766     embedding manifests:

   767 

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

   769 

   770     To use the options, add

   771 

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

   773 

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

   775 

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

   777     assemblies at the

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

   779 

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

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

   782     system.

   783 

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

   785 

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

   787 

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

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

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

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

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

   793 

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

   795 

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

   797     systems.

   798 

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

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

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

   802     user installs your application.

   803 

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

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

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

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

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

   809     architectures, respectively.

   810 

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

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

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

   814 

   815     \section2 Visual Studio 2008 And Manual Installs

   816 

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

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

   819     stick.

   820 

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

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

   823     for manually deploying private assemblies.

   824 

   825     In brief the steps are

   826 

   827     \list 1

   828     

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

   830         

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

   832         

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

   834     \endlist

   835 

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

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

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

   839 

   840     \section1 Application Dependencies

   841 

   842     \section2 Additional Libraries

   843 

   844     Depending on configuration, compiler specific libraries must be

   845     redistributed along with your application. You can check which

   846     libraries your application is linking against by using the

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

   848     this:

   849 

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

   851 

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

   853     depends on and other information.

   854 

   855     \image deployment-windows-depends.png

   856 

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

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

   859     following immediate dependencies to non-system libraries:

   860 

   861     \table 100%

   862         \header

   863             \o Qt

   864             \o VC++ 6.0

   865             \o VC++ 7.1 (2003)

   866             \o VC++ 8.0 (2005)

   867             \o MinGW

   868         \row

   869         \o \list

   870                \o QTCORE4.DLL - The QtCore runtime

   871                \o QTGUI4.DLL - The QtGui runtime

   872            \endlist

   873         \o \list

   874                \o MSVCRT.DLL - The C runtime

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

   876            \endlist

   877         \o \list

   878                \o MSVCR71.DLL - The C runtime

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

   880            \endlist

   881         \o \list

   882                \o MSVCR80.DLL - The C runtime

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

   884            \endlist

   885         \o \list

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

   887            \endlist

   888     \endtable

   889 

   890     When looking at the plugin DLLs the exact same dependencies

   891     are listed.

   892 

   893     \section2 Qt Plugins

   894 

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

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

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

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

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

   900     within your distribution directory, as described below.

   901 

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

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

   904     plugins to support as many HTML encodings possible. 

   905 

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

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

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

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

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

   911     sure that the Qt plugins are found:

   912 

   913     \list

   914 

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

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

   917 

   918     \o Using QApplication::addLibraryPath() or

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

   920     have one executable that will use the plugin. 

   921 

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

   923     hard-coded paths in the QtCore library.

   924 

   925     \endlist

   926 

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

   928     look like this:

   929 

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

   931 

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

   933 

   934     "C:/customPath/plugins " 

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

   936     "E:/myApplication/directory/"

   937 

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

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

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

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

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

   943     and in which order they will be searched.

   944 

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

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

   947     Qt applications.

   948 

   949     \section1 Related Third Party Resources

   950 

   951     \list

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

   953     process of cross-compiling Windows applications on Linux.

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

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

   956     cross-compilation guide.

   957     \endlist

   958 */

   959 

   960 /*!

   961     \page deployment-mac.html

   962     \contentspage Deploying Qt Applications

   963 

   964     \title Deploying an Application on Mac OS X

   965 

   966     Beginning with Qt 4.5, a \l {macdeploy}{deployment tool} is

   967     included that automates the prodecures described here.

   968 

   969     This document describes how to create a bundle and how to make

   970     sure that the application will find the resources it needs at

   971     run-time. We demonstrate the procedures in terms of deploying the

   972     \l {tools/plugandpaint}{Plug & Paint} application that is provided

   973     in Qt's examples directory.

   974     

   975     \tableofcontents

   976 

   977     \section1 The Bundle

   978 

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

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

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

   982     typcially contains the executable and all the resources it

   983     needs. See the image below:

   984 

   985     \image deployment-mac-bundlestructure.png

   986 

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

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

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

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

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

   992     is available on \l

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

   994 

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

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

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

   998 

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

  1000 

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

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

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

  1004     to deploy these "bundle-less" applications.

  1005 

  1006     \section1 Xcode

  1007 

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

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

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

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

  1012     include more information for using Xcode in the deployment

  1013     process.

  1014 

  1015     \section1 Static Linking

  1016 

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

  1018     deploy, then you must build everything statically.

  1019 

  1020     \section2 Building Qt Statically

  1021 

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

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

  1024     the image formats, SQL drivers, etc..

  1025 

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

  1027 

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

  1029     configure -help.

  1030 

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

  1032 

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

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

  1035     directory that contains the application:

  1036 

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

  1038 

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

  1040     a clean build to create the statically linked executable:

  1041 

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

  1043 

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

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

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

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

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

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

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

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

  1052     could make a difference.

  1053 

  1054     Now, provided that everything compiled and linked without any

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

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

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

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

  1059     application on that machine.

  1060 

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

  1062     the \c otool:

  1063 

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

  1065 

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

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

  1068 

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

  1070 

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

  1072     section.

  1073 

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

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

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

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

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

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

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

  1081     to the static libraries. For example, replace

  1082 

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

  1084 

  1085     with

  1086 

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

  1088 

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

  1090     several components: The core application (\l

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

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

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

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

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

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

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

  1098     should use the framework approach.

  1099 

  1100     \section1 Frameworks

  1101 

  1102     We have two challenges when deploying the \l

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

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

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

  1106     correct location so that the application can find them.

  1107 

  1108     When distributing Qt with your application using frameworks, you

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

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

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

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

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

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

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

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

  1117 

  1118     \section2 Building Qt as Frameworks

  1119 

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

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

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

  1123     Installation documentation.

  1124 

  1125     When installing, the identification name of the frameworks will

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

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

  1128 

  1129     \section2 Linking the Application to Qt as Frameworks

  1130 

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

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

  1133     into the directory that contains the application:

  1134 

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