source: trunk/doc/src/deployment/deployment.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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 {QAxContainer}
        \o \l {QAxServer}
        \o \l {QtCore}
        \o \l {QtDBus}
    \row
        \o \l {QtDesigner}
        \o \l {QtGui}
        \o \l {QtHelp}
        \o \l {QtNetwork}
    \row
        \o \l {QtOpenGL}
        \o \l {QtScript}
        \o \l {QtScriptTools}
        \o \l {QtSql}
    \row
        \o \l {QtSvg}
        \o \l {QtWebKit}
        \o \l {QtXml}
        \o \l {QtXmlPatterns}
    \row
        \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 general, you should deploy all plugins that your build of Qt uses,
    excluding only those that you have identified as being unnecessary
    for your application and its users.

    For instance, you may need to deploy plugins for JPEG support and
    SQL drivers, but you should also deploy plugins that your users may
    require, including those for accessibility.
    For more information about plugins, see the
    \l{plugins-howto.html}{How to Create Qt Plugins} documentation.

    When deploying an application using the shared library approach
    you must ensure that the Qt libraries will use the correct path to
    find the Qt plugins, documentation, translation etc. To do this you
    can use a \c qt.conf file. For more information, see the \l {Using
    qt.conf} documentation.

    Depending on configuration, compiler specific libraries must be
    redistributed as well. For more information, see the platform
    specific Application Dependencies sections: \l
    {deployment-x11.html#application-dependencies}{X11}, \l
    {deployment-windows.html#application-dependencies}{Windows}, \l
    {deployment-mac.html#application-dependencies}{Mac}.

    \section1 Licensing

    Some of Qt's libraries are based on third party libraries that are
    not licensed using the same dual-license model as Qt. As a result,
    care must be taken when deploying applications that use these
    libraries, particularly when the application is statically linked
    to them.

    The following table contains an inexhaustive summary of the issues
    you should be aware of.

    \table
    \header \o Qt Library \o Dependency
            \o Licensing Issue
    \row    \o QtHelp     \o CLucene
    \o The version of clucene distributed with Qt is licensed
    under the GNU LGPL version 2.1 or later. This has implications for
    developers of closed source applications. Please see
    \l{QtHelp Module#License Information}{the QtHelp module documentation}
    for more information.

    \row    \o QtNetwork  \o OpenSSL
    \o Some configurations of QtNetwork use OpenSSL at run-time. Deployment
    of OpenSSL libraries is subject to both licensing and export restrictions.
    More information can be found in the \l{Secure Sockets Layer (SSL) Classes}
    documentation.

    \row    \o QtWebKit   \o WebKit
    \o WebKit is licensed under the GNU LGPL version 2 or later.
    This has implications for developers of closed source applications.
    Please see \l{WebKit in Qt#License Information}{the QtWebKit module
    documentation} for more information.

    \row    \o \l{Phonon Module}{Phonon}     \o Phonon
    \o Phonon relies on the native multimedia engines on different platforms.
    Phonon itself is licensed under the GNU LGPL version 2. Please see
    \l{Phonon Module#License Information}{the Phonon module documentation}
    for more information on licensing and the
    \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends
    in use on different platforms.
    \endtable

    \section1 Platform-Specific Notes

    The procedure of deploying Qt applications is different for the
    various platforms:

    \list
        \o \l{Deploying an Application on X11 Platforms}{Qt for X11 Platforms}
        \o \l{Deploying an Application on Windows}{Qt for Windows}
        \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X}
        \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux}
        \o \l{Deploying an Application on the Symbian platform}{Qt for the Symbian platform}
    \endlist

    \sa Installation {Platform-Specific Documentation}
*/

/*!
    \page deployment-x11.html
    \contentspage Deploying Qt Applications

    \title Deploying an Application on X11 Platforms

    Due to the proliferation of Unix systems (commercial Unices, Linux
    distributions, etc.), deployment on Unix is a complex
    topic. Before we start, be aware that programs compiled for one
    Unix flavor will probably not run on a different Unix system. For
    example, unless you use a cross-compiler, you cannot compile your
    application on Irix and distribute it on AIX.

    Contents:

    \tableofcontents

    This documentation will describe how to determine which files you
    should include in your distribution, and how to make sure that the
    application will find them at run-time. We will demonstrate the
    procedures in terms of deploying the \l {tools/plugandpaint}{Plug
    & Paint} application that is provided in Qt's examples directory.

    \section1 Static Linking

    Static linking is often the safest and easiest way to distribute
    an application on Unix since it relieves you from the task of
    distributing the Qt libraries and ensuring that they are located
    in the default search path for libraries on the target system.

    \section2 Building Qt Statically

    To use this approach, you must start by installing a static version
    of the Qt library:

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

    We specify the prefix so that we do not overwrite the existing Qt
    installation. The example above only builds the Qt libraries,
    i.e. the examples and Qt Designer will not be built.  When \c make
    is done, you will find the Qt libraries in the \c /path/to/Qt/lib
    directory.

    When linking your application against static Qt libraries, note
    that you might need to add more libraries to the \c LIBS line in
    your project file. For more information, see the \l {Application
    Dependencies} section.

    \section2 Linking the Application to the Static Version of Qt

    Once Qt is built statically, the next step is to regenerate the
    makefile and rebuild the application. First, we must go into the
    directory that contains the application:

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

    Now run qmake to create a new makefile for the application, and do
    a clean build to create the statically linked executable:

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

    You probably want to link against the release libraries, and you
    can specify this when invoking \c qmake. Note that we must set the
    path to the static Qt that we just built.

    To check that the application really links statically with Qt, run
    the \c ldd tool (available on most Unices):

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

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

    Now, provided that everything compiled and linked without any
    errors, we should have a \c plugandpaint file that is ready for
    deployment. One easy way to check that the application really can
    be run stand-alone is to copy it to a machine that doesn't have Qt
    or any Qt applications installed, and run it on that machine.

    Remember that if your application depends on compiler specific
    libraries, these must still be redistributed along with your
    application. For more information, see the \l {Application
    Dependencies} section.

    The \l {tools/plugandpaint}{Plug & Paint} example consists of
    several components: The core application (\l
    {tools/plugandpaint}{Plug & Paint}), and the \l
    {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
    {tools/plugandpaintplugins/extrafilters}{Extra Filters}
    plugins. Since we cannot deploy plugins using the static linking
    approach, the executable we have prepared so far is
    incomplete. The application will run, but the functionality will
    be disabled due to the missing plugins. To deploy plugin-based
    applications we should use the shared library approach.

    \section1 Shared Libraries

    We have two challenges when deploying the \l
    {tools/plugandpaint}{Plug & Paint} application using the shared
    libraries approach: The Qt runtime has to be correctly
    redistributed along with the application executable, and the
    plugins have to be installed in the correct location on the target
    system so that the application can find them.

    \section2 Building Qt as a Shared Library

    We assume that you already have installed Qt as a shared library,
    which is the default when installing Qt, in the \c /path/to/Qt
    directory. For more information on how to build Qt, see the \l
    {Installation} documentation.

    \section2 Linking the Application to Qt as a Shared Library

    After ensuring that Qt is built as a shared library, we can build
    the \l {tools/plugandpaint}{Plug & Paint} application. First, we
    must go into the directory that contains the application:

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

    Now run qmake to create a new makefile for the application, and do
    a clean build to create the dynamically linked executable:

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

    This builds the core application, the following will build the
    plugins:

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

    If everything compiled and linked without any errors, we will get
    a \c plugandpaint executable and the \c libpnp_basictools.so and
    \c libpnp_extrafilters.so plugin files.

    \section2 Creating the Application Package

    There is no standard package management on Unix, so the method we
    present below is a generic solution. See the documentation for
    your target system for information on how to create a package.

    To deploy the application, we must make sure that we copy the
    relevant Qt libraries (corresponding to the Qt modules used in the
    application) as well as the executable to the same
    directory. Remember that if your application depends on compiler
    specific libraries, these must also be redistributed along with
    your application. For more information, see the \l {Application
    Dependencies} section.

    We'll cover the plugins shortly, but the main issue with shared
    libraries is that you must ensure that the dynamic linker will
    find the Qt libraries. Unless told otherwise, the dynamic linker
    doesn't search the directory where your application resides. There
    are many ways to solve this:

    \list
    
    \o You can install the Qt libraries in one of the system
       library paths (e.g. \c /usr/lib on most systems).

    \o You can pass a predetermined path to the \c -rpath command-line
       option when linking the application. This will tell the dynamic
       linker to look in this directory when starting your application.

    \o You can write a startup script for your application, where you
       modify the dynamic linker configuration (e.g.  adding your
       application's directory to the \c LD_LIBRARY_PATH environment
       variable. \note If your application will be running with "Set
       user ID on execution," and if it will be owned by root, then
       LD_LIBRARY_PATH will be ignored on some platforms. In this
       case, use of the LD_LIBRARY_PATH approach is not an option).

    \endlist

    The disadvantage of the first approach is that the user must have
    super user privileges. The disadvantage of the second approach is
    that the user may not have privileges to install into the
    predetemined path. In either case, the users don't have the option
    of installing to their home directory. We recommend using the
    third approach since it is the most flexible. For example, a \c
    plugandpaint.sh script will look like this:

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

    By running this script instead of the executable, you are sure
    that the Qt libraries will be found by the dynamic linker. Note
    that you only have to rename the script to use it with other
    applications.

    When looking for plugins, the application searches in a plugins
    subdirectory inside the directory of the application
    executable. Either you have to manually copy the plugins into the
    \c plugins directory, or you can set the \c DESTDIR in the
    plugins' project files:

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

    An archive distributing all the Qt libraries, and all the plugins,
    required to run the \l {tools/plugandpaint}{Plug & Paint}
    application, would have to include the following files:

    \table 100%
    \header
        \o Component \o {2, 1} File Name
    \row
        \o The executable
        \o {2, 1} \c plugandpaint
    \row
        \o The script to run the executable
        \o {2, 1} \c plugandpaint.sh
    \row
        \o The Basic Tools plugin
        \o {2, 1} \c plugins\libpnp_basictools.so
    \row
        \o The ExtraFilters plugin
        \o {2, 1} \c plugins\libpnp_extrafilters.so
    \row
        \o The Qt Core module
        \o {2, 1} \c libQtCore.so.4
    \row
        \o The Qt GUI module
        \o {2, 1} \c libQtGui.so.4
    \endtable

    On most systems, the extension for shared libraries is \c .so. A
    notable exception is HP-UX, which uses \c .sl.

    Remember that if your application depends on compiler specific
    libraries, these must still be redistributed along with your
    application. For more information, see the \l {Application
    Dependencies} section.

    To verify that the application now can be successfully deployed,
    you can extract this archive on a machine without Qt and without
    any compiler installed, and try to run it, i.e. run the \c
    plugandpaint.sh script.

    An alternative to putting the plugins in the \c plugins
    subdirectory is to add a custom search path when you start your
    application using QApplication::addLibraryPath() or
    QApplication::setLibraryPaths().

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

    \section1 Application Dependencies

    \section2 Additional Libraries

    To find out which libraries your application depends on, run the
    \c ldd tool (available on most Unices):

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

    This will list all the shared library dependencies for your
    application. Depending on configuration, these libraries must be
    redistributed along with your application. In particular, the
    standard C++ library must be redistributed if you're compiling
    your application with a compiler that is binary incompatible with
    the system compiler. When possible, the safest solution is to link
    against these libraries statically.

    You will probably want to link dynamically with the regular X11
    libraries, since some implementations will try to open other
    shared libraries with \c dlopen(), and if this fails, the X11
    library might cause your application to crash.

    It's also worth mentioning that Qt will look for certain X11
    extensions, such as Xinerama and Xrandr, and possibly pull them
    in, including all the libraries that they link against. If you
    can't guarantee the presence of a certain extension, the safest