/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page deployment.html

    \title Deploying Qt Applications

    Deploying an Qt application does not require any C++

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

    application in release mode, following the procedures described in

    this documentation. We will demonstrate the procedures in terms of

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

    that is provided in Qt's examples directory.

    \section1 Static vs. Shared Libraries

    There are two ways of deploying an application:

    \list

        \o Static Linking

        \o Shared Libraries (Frameworks on Mac)

    \endlist

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

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

    disadvantages are that the executables are large and with no

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

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

    cannot deploy plugins.

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

    library approach. Shared libraries also provide smaller, more

    flexible executables. For example, using the shared library

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

    used by the application.

    Another reason why you might want to use the shared library

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

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

    of Qt, you get Qt as a shared library.

    The disadvantage with the shared library approach is that you

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

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

    \section1 Deploying Qt's Libraries

    \table

    \header

        \o {4,1} Qt's Libraries

    \row

        \o \l {QtAssistant}

        \o \l {QAxContainer}

        \o \l {QAxServer}

        \o \l {QtCore}

    \row

        \o \l {QtDBus}

        \o \l {QtDesigner}

        \o \l {QtGui}

        \o \l {QtHelp}

    \row

        \o \l {QtNetwork}

        \o \l {QtOpenGL}

        \o \l {QtScript}

        \o \l {QtScriptTools}

    \row

        \o \l {QtSql}

        \o \l {QtSvg}

        \o \l {QtWebKit}

        \o \l {QtXml}

    \row

        \o \l {QtXmlPatterns}

        \o \l {Phonon Module}{Phonon}

        \o \l {Qt3Support}

    \endtable

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

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

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

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

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

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

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

    documentation.

    When deploying an application using the shared library approach

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

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

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

    qt.conf} documentation.

    Depending on configuration, compiler specific libraries must be

    redistributed as well. For more information, see the platform

    specific Application Dependencies sections: \l

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

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

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

    \section1 Licensing

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

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

    care must be taken when deploying applications that use these

    libraries, particularly when the application is statically linked

    to them.

    The following table contains an inexhaustive summary of the issues

    you should be aware of.

    \table

    \header \o Qt Library \o Dependency

            \o Licensing Issue

    \row    \o QtHelp     \o CLucene

    \o The version of clucene distributed with Qt is licensed

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

    developers of closed source applications. Please see

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

    for more information.

    \row    \o QtNetwork  \o OpenSSL

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

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

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

    documentation.

    \row    \o QtWebKit   \o WebKit

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

    This has implications for developers of closed source applications.

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

    documentation} for more information.

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

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

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

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

    for more information on licensing and the

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

    in use on different platforms.

    \endtable

    \section1 Platform-Specific Notes

    The procedure of deploying Qt applications is different for the

    various platforms:

    \list

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

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

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

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

    \endlist

    \sa Installation {Platform-Specific Documentation}

*/

/*!

    \page deployment-x11.html

    \contentspage Deploying Qt Applications

    \title Deploying an Application on X11 Platforms

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

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

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

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

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

    application on Irix and distribute it on AIX.

    Contents:

    \tableofcontents

    This documentation will describe how to determine which files you

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

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

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

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

    \section1 Static Linking

    Static linking is often the safest and easiest way to distribute

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

    distributing the Qt libraries and ensuring that they are located

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

    \section2 Building Qt Statically

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

    of the Qt library:

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

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

    installation. The example above only builds the Qt libraries,

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

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

    directory.

    When linking your application against static Qt libraries, note

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

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

    Dependencies} section.

    \section2 Linking the Application to the Static Version of Qt

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

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

    directory that contains the application:

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

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

    a clean build to create the statically linked executable:

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

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

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

    path to the static Qt that we just built.

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

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

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

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

    Now, provided that everything compiled and linked without any

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

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

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

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

    Remember that if your application depends on compiler specific

    libraries, these must still be redistributed along with your

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

    Dependencies} section.

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

    several components: The core application (\l

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

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

    {tools/plugandpaintplugins/extrafilters}{Extra Filters}

    plugins. Since we cannot deploy plugins using the static linking

    approach, the executable we have prepared so far is

    incomplete. The application will run, but the functionality will

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

    applications we should use the shared library approach.

    \section1 Shared Libraries

    We have two challenges when deploying the \l

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

    libraries approach: The Qt runtime has to be correctly

    redistributed along with the application executable, and the

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

    system so that the application can find them.

    \section2 Building Qt as a Shared Library

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

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

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

    {Installation} documentation.

    \section2 Linking the Application to Qt as a Shared Library

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

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

    must go into the directory that contains the application:

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

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

    a clean build to create the dynamically linked executable:

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

    This builds the core application, the following will build the

    plugins:

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

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

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

    \c libpnp_extrafilters.so plugin files.

    \section2 Creating the Application Package

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

    present below is a generic solution. See the documentation for

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

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

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

    application) as well as the executable to the same

    directory. Remember that if your application depends on compiler

    specific libraries, these must also be redistributed along with

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

    Dependencies} section.

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

    libraries is that you must ensure that the dynamic linker will

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

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

    are many ways to solve this:

    \list

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

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

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

       option when linking the application. This will tell the dynamic

       linker to look in this directory when starting your application.

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

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

       application's directory to the \c LD_LIBRARY_PATH environment

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

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

       LD_LIBRARY_PATH will be ignored on some platforms. In this

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

    \endlist

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

    super user privileges. The disadvantage of the second approach is

    that the user may not have privileges to install into the

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

    of installing to their home directory. We recommend using the

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

    plugandpaint.sh script will look like this:

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

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

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

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

    applications.

    When looking for plugins, the application searches in a plugins

    subdirectory inside the directory of the application

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

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

    plugins' project files:

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

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

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

    application, would have to include the following files:

    \table 100%

    \header

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

    \row

        \o The executable

        \o {2, 1} \c plugandpaint

    \row

        \o The script to run the executable

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

    \row

        \o The Basic Tools plugin

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

    \row

        \o The ExtraFilters plugin

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

    \row

        \o The Qt Core module

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

    \row

        \o The Qt GUI module

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

    \endtable

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

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

    Remember that if your application depends on compiler specific

    libraries, these must still be redistributed along with your

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

    Dependencies} section.

    To verify that the application now can be successfully deployed,

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

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

    plugandpaint.sh script.

    An alternative to putting the plugins in the \c plugins

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

    application using QApplication::addLibraryPath() or

    QApplication::setLibraryPaths().

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

    \section1 Application Dependencies

    \section2 Additional Libraries

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

    \c ldd tool (available on most Unices):

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

    This will list all the shared library dependencies for your

    application. Depending on configuration, these libraries must be

    redistributed along with your application. In particular, the

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

    your application with a compiler that is binary incompatible with

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

    against these libraries statically.

    You will probably want to link dynamically with the regular X11

    libraries, since some implementations will try to open other

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

    library might cause your application to crash.

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

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

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

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

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

    -no-xrandr}).

    FontConfig and FreeType are other examples of libraries that

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

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

    had success by compiling their software on very old machines and

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

    on them.

    When linking your application against the static Qt libraries, you

    must explicitly link with the dependent libraries mentioned

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

    project file.

    \section2 Qt Plugins

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

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

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

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

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

    within your distribution directory, as described below.

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

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

    plugins to support as many HTML encodings possible. 

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

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

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

    mentioned above, using pre-determined paths has certain

    disadvantages, so you need to examine various alternatives to make

    sure that the Qt plugins are found:

    \list

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

    approach since it provides the most flexibility.

    \o Using QApplication::addLibraryPath() or

    QApplication::setLibraryPaths().

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

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

    library.

    \endlist

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

    need to pay attention to when building and deploying plugins for

    Qt applications.

*/

/*!

    \page deployment-windows.html

    \contentspage Deploying Qt Applications

    \title Deploying an Application on Windows

    This documentation will describe how to determine which files you

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

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

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

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

    Contents: