path: root/doc/src/deployment/deployment.qdoc

/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $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.

    \section1 Static vs. Shared Libraries

    There are two ways of deploying an application:

    \list
        \li Static Linking
        \li 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{Creating Shared Libraries}.

    \section1 Deploying Qt's Libraries

    Unless Qt is part of the system libraries it must be redistributed
    with your application. The minimum is to redistribute the run-time
    of the libraries used by the application.  However, with static linking,
    the Qt run-times can be compiled into the executable.

    In general, you should deploy all plugins that your Qt build uses,
    excluding those that you have identified as 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 \l{How to Create Qt Plugins}.

    Applications using \l{Qt QML} also need to ship the
    \l{All QML Modules}{QML modules} they use.

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

    Depending on configuration, compiler-specific libraries must be
    redistributed as well. For more information, see the
    platform-specific application dependencies for
    \l{Qt for Linux/X11 - Deployment#Application Dependencies}{X11},
    \l{Qt for Windows - Deployment#Application Dependencies}{Windows},
    and \l{Qt for OS X}{OS X}.

    \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 summarizes a few issues that
    you should be aware of.

    \table
    \header \li Qt Library \li Dependency
            \li Licensing Issue
    \row    \li \l{QtHelp} \li CLucene
    \li 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 the
    \l{Qt Help#License Information}{Qt Help} documentation for more information.

    \row    \li \l{QtNetwork}  \li OpenSSL
    \li 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.

    \endtable

    For more information, see \l{Third-Party Licenses Used in Qt}.

    \section1 Platform-Specific Notes

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

    \list
        \li \l{Qt for Linux/X11 - Deployment}{Qt for X11 Platforms}
        \li \l{Qt for Windows - Deployment}{Qt for Windows}
        \li \l{Qt for OS X#Deploying Applications on OS X}{Qt for OS X}
        \li \l{Deploying an Application on Android}{Qt for Android}
    \endlist

    \sa {Deploying Translations}
*/

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

    \title Deploying an Application on Android

    This article gives a technical description of the steps required to take
    any given Qt application and deploy it to an Android device (or market place).

    It is recommended that you use the \l {androiddeployqt}{androiddeployqt deployment tool} or
    Qt Creator to automate this work rather than perform the steps manually. The following
    information will give you a technical insight into the structure of the resulting Android
    application which is not normally required just to write an application.

    \tableofcontents

    \section1 The APK Package

    Applications on Android are packaged in a specially structured type of ZIP file called \c APK.
    When you build a Qt application using \c qmake and \c make, the result will be a binary file
    which is built with the correct compiler and flags to be usable on an Android device with the
    target architecture.

    In order to turn this into a runnable application, it has to be put into a special directory
    structure with some other files and packaged into an APK package.

    \section1 Package Template

    A template for the other sources of an APK package is contained in \c{$QTDIR/src/android/java}.
    The first step of making an APK is to copy these files into an empty directory. In this
    guide, we'll refer to this build directory as \c{$BUILD_TARGET}.

    We also need to make sure the application binary is copied into the package. This can be
    achieved by using the following command after running qmake on your application's project file:

    \code
    make install INSTALL_ROOT=$BUILD_TARGET
    \endcode

    It will copy the application binary and any other installation requirements into the packaging
    directory.

    The packaging directory will now consist of the following parts:

    \section2 AndroidManifest.xml

    The \c{AndroidManifest.xml} file gives detailed meta-information about your application. This
    information is used for several things. It is used by the target device to decide which features
    to enable, the default orientation of the application, and so on. In addition, it's used by the
    market place for information on the version code, device support, package name, and lots more.

    For more information about general capabilities of and requirements for the
    \c{AndroidManifest.xml} file, please refer to the
    \l{http://developer.android.com/guide/topics/manifest/manifest-intro.html}{Android documentation on this topic}.

    There are some special variables recognized by Qt which can be placed inside the manifest:

    \list
    \li \c{android.app.use_local_qt_libs}: If this is set to \c 1, Qt libraries are expected to be
    found on the target device. If it is \c 0, then libraries must be requested from the \b Ministro
    service.
    \li \c{android.app.bundle_local_qt_libs}: If set to \c 1, the Qt libraries are expected to be
    bundled as part of the \c APK. If set to \c 0, they are expected to be found in the
    \c{/data/local/tmp/qt} folder on the target device.

    \note If \c{use_local_qt_libs} is 0, then this variable has no effect, since libraries
    are then requested through Ministro instead.
    \endlist

    Other variables in the manifest refer to resources, and more information about these can
    be found in the \l{Resources}{documentation for the resources} below.

    \section2 Java Code

    Under \c{$BUILD_TARGET/src} are the files comprising the Java code of the Android application.
    The regular Android application launcher is a Java process, so Qt applications have a
    Java-based entry point. The code in here will load the required Qt libraries, based on the
    meta-information given in other files in the template. The code supports all the
    three deployment mechanisms which are supported in Qt Creator and \c{androiddeployqt}: \e Bundled,
    \e Ministro and \e Debug.

    After loading the libraries, the Java code will call into the application's native \c{main()}
    function on a new thread and the application will launch. At this point, the Java code in
    the template is used to delegate events from Android into Qt.

    One thing to note about the files in this directory is that they can contain code specific
    to certain Android versions. Based on the minimum required Android API level of your
    application it might be necessary to remove some of this code. This is done automatically
    by \c androiddeployqt and Qt Creator during packaging.

    For example, lets say the code contains the following:

    \code
//@ANDROID-12
    @Override
    public boolean dispatchGenericMotionEvent(MotionEvent ev)
    {
        if (QtApplication.m_delegateObject != null  && QtApplication.dispatchGenericMotionEvent != null)
            return (Boolean) QtApplication.invokeDelegateMethod(QtApplication.dispatchGenericMotionEvent, ev);
        else
            return super.dispatchGenericMotionEvent(ev);
    }
//@ANDROID-12
    \endcode

    If your minimum Android API level is 11 or lower, then the code should be removed before
    building, since it's not a supported API on Android API level 11. However, if your minimum API
    level is 12 or higher, it should be left in.

    \section2 Resources

    Under the \c{res/} folder in the \c{$BUILD_TARGET} are Android resources that can be accessed
    from the \c{AndroidManifest.xml} and Java code of your application. A typical example of
    resources which should be placed here are the icon files used by the application launcher to
    represent your application.

    In Qt, some translations used for the Ministro service and some files with meta-information
    are in the default resources of the application.

    \section3 res/values/libs.xml

    One of the files containing meta information about the deployment of the application is
    \c{libs.xml}. It consists of the following values:

    \list
    \li \c{qt_sources}: The URL of one or more Ministro repositories that contain the
    necessary Qt libraries. This is used when the Ministro deployment mechanism is active. Read the
    \l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro documentation} for more
    information about such repositories.
    \li \c{repository}: The Ministro repository to use at the given URL. This is used when the
    Ministro deployment mechanism is active.
    \li \c{bundled_libs}: Libraries in the APK's library folder which should be loaded on start-up.
    Library names should be specified without the \c lib prefix and \c{.so} suffix.
    \li \c{qt_libs}: Qt libraries which should be loaded on start-up. When bundled deployment is
    used, these are expected to be found inside the \c{APK}'s library folder. When Ministro
    deployment is in use, they are requested from the Ministro service on the device. And when
    debugging deployment is in use, they are loaded from the \c{/data/local/tmp/qt} directory on the
    target device.
    \li \c{bundled_in_lib}: List of plugins which are bundled in the \c{APK}'s library folder. This
    is only used when the bundling deployment mechanism is active. Qt's plugin system requires
    plugins to be placed in a special directory structure which contains information about the
    plugin category. The library folder in the APK does not support such a directory
    structure, so the bundled_in_lib array contains the information lost when the directory
    structure is flattened. Each item is a pair of paths, separated by a colon. The first of the
    pair is the file name of the file bundled inside the \c{APK}'s library folder. The second of the
    pair is the original path of the file, relative to the Qt installation.
    \li \c{bundled_in_assets}: List of other types of Qt files which are bundled inside the
    \c{APK}'s asset folder. This value is only used when the bundling deployment mechanism is active. The
    format of the items is the same as for the \c{bundled_in_lib array}. The difference is that the
    first of the pairs refers to the path of a file inside the \c{assets} directory of the
    application instead of the library directory. This array is typically used for bundling QML
    imports, which also require a special directory structure to be used inside Qt.
    \endlist

    \section3 res/values/strings.xml

    The \c{strings.xml} file contains some strings used by the \c{AndroidManifest.xml} and by the
    deployment mechanisms, as well as some strings used when loading the Ministro service.

    In particular, the application name and the name of the application binary can be specified
    here. There are also strings that contain additional libraries that should be loaded and
    \c JAR files which should be included in the class path. The latter is only used for deployment
    with Ministro or debug deployment.

    \section2 Libraries

    Under \c libs in the package directory, it's possible to place libraries that should be included
    in the application bundle. \c JAR libraries should be placed directly under \c{libs/}, while
    shared libraries should be put in a subdirectory suitably named after the target architecture
    of the libraries.

    For deployment that bundles Qt in the \c APK, the Qt \c JAR files that are suffixed with
    \c{"bundled"} should be put into the libs directory. It is also required that the necessary
    shared libraries and plugins are placed in the appropriate subdirectory of libs.

    \section1 Building the Android Application Package

    Once all the pieces are in place, a few steps are required to build the application package.
    First, a build script needs to be generated. This is done using the \c android tool which is
    part of the Google Android SDK.

    Example:
    \code
    % android update project --path $BUILD_TARGET --target android-9 --name QtApp
    \endcode

    This example will create build files in \c{$BUILD_TARGET} for an \c APK named \c QtApp. The Java
    code will be compiled against the \c{android-9} platform.

    The project can then be built using the ant tool. If a release package is built it can
    be signed and aligned using \c jarsigner and \c zipalign.

    \section1 androiddeployqt

    Building an application package is complex, so Qt comes with a tool which handles the work for
    you. The steps described in this document so far are handled automatically by the tool.

    \section2 Required Steps Before Running androiddeployqt

    Before running the tool, you need run \c qmake and \c make your project. Running \c qmake
    creates the \c Makefile, and it will also generate a \c JSON file containing important settings
    used by \c androiddeployqt.

    You should then install the application binary (and any other requirements) into the library
    folder of the \c APK. If \c{$BUILD_TARGET} is your build directory (the first time you do this,
    the directory should be empty at this point), then you can install the binary with the following
    command:

    \code
    % make install INSTALL_ROOT=$BUILD_TARGET
    \endcode

    \section2 Command Line Arguments

    The only required command line argument when running the tool is \c{--output}. This should
    be set to \c{$BUILD_TARGET}, that is: the build directory where you installed your application
    binary.

    Other command line arguments are optional but useful. Here's a quick overview. More information
    is available by passing the \c{--help} argument to androiddeployqt.

    \list
    \li \c{--input <file name>}: This allows you to specify the \c JSON file generated by \c qmake.
    By default, \c androiddeployqt will try to guess the file name based on the current working
    directory.
    \li \c{--deployment <mechanism>}: Specify this to pick a different deployment mechanism than the
    default.
    \li \c{--install}: Specify this to install the finished package on the target device or
    emulator. Note that if a previous version of the package is already installed, it will be
    uninstalled first, removing any data it might have stored locally.
    \li \c{--device <ID>}: Specify the ID of the target device or emulator as reported by the \c adb
    tool. If an ID is specified, it will be passed to all calls to \c adb. If it is unspecified, no
    particular device or emulator will be requested by \c adb, causing it to pick a default instead.
    \li \c{--android-platform <platform>}: The SDK platform used for building the Java code of the
    application. By default, the latest available platform is used.
    \li \c{--ant <path>}: Specify the path to the \c ant executable. If this is unspecified,
    \c androiddeployqt will attempt to detect it on the \c PATH.
    \li \c{--release}: Specify this to create a release package instead of a debug package. With no
    other arguments, release packages are unsigned and cannot be installed to any device before
    they have been signed by a private key.
    \li \c{--sign <url> <alias>}: Sign the resulting package. Specifying this also implies
    \c{--release}. The URL of the keystore file and the alias of the key have to be specified. In
    addition, there are a number of options that can be specified which are passed through to the
    \c jarsigner tool. Pass \c{--help} to \c androiddeployqt for more information about these.
    \li \c{--jdk <path>}: Specify the path to the Java Development Kit. This is only required for
    signing packages, as it is only used for finding the \c jarsigner tool. If it is unspecified,
    then \c androiddeployqt will attempt to detect \c jarsigner, either using the \c{JAVA_HOME}
    environment variable, or on the \c PATH.
    \li \c{--verbose}: Specify this to output more information about what \c androiddeployqt is
    doing.
    \endlist

    \section1 Dependencies Detection

    Qt comes with a number of plugins which are loaded at run-time when they are needed. These
    can handle anything from connecting to SQL databases to loading specific image formats.
    Detecting plugin dependencies is impossible as the plugins are loaded at run-time, but
    androiddeployqt tries to guess such dependencies based on the Qt dependencies
    of your application. If the plugin has any Qt dependencies which are not also dependencies of
    your application, it will not be included by default. For instance, in order to ensure that
    the SVG image format plugin is included, you will need to add \c{QT += svg} to your \c .pro file
    so that the \l{Qt SVG} module becomes a dependency of your application.

    If you are wondering why a particular plugin is not included automatically, you can run androiddeployqt
    with the \c --verbose option to get the list of missing dependencies for each excluded plugin. You
    can achieve the same in Qt Creator by ticking the \gui{Verbose output} check box in the
    \gui{Deployment configurations}. This is located in the \gui{Run} tab of your \gui{Projects}
    settings.

    It's also possible to manually specify the dependencies of your application. See the documentation
    for the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable below.

    \section1 Android-specific qmake Variables

    Unless the project has special requirements such as third party libraries, it should be
    possible to run \c androiddeployqt on it with no modifications and get a working Qt for Android
    application as a result.

    However, there are a set of \c qmake variables that can be used to tailor your package. At some
    point during development, you will most likely want to look into these variables, as they will
    e.g. allow you to set the name of your application as it appears in the application menu on
    devices.

    Here is a list of some variables that are particularly interesting when making Android
    applications:

    \list
    \li \c{ANDROID_DEPLOYMENT_DEPENDENCIES}: By default, \c androiddeployqt will detect the
    dependencies of your application. But since run-time usage of plugins cannot be detected, there
    could be false positives, as your application will depend on any plugins that are \e potential
    dependencies. If you want to minimize the size of your \c APK, it's possible to override the
    automatic detection using the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} variable. This should contain
    a list of all Qt files which need to be included, with paths relative to the Qt install root.
    Note that only the Qt files specified here will be included. Failing to include the correct
    files can result in crashes. It's also important to make sure the files are listed in the
    correct loading order. This variable provides a way to override the automatic detection
    entirely, so if a library is listed before its dependencies, it will fail to load on
    some devices.
    \li \c{ANDROID_PACKAGE_SOURCE_DIR}: This variable can be used to specify a directory where
    additions and modifications can be made to the default Android package template. The
    \c androiddeployqt tool will copy the application template from Qt into the build directory, and
    then it will copy the contents of the \c{ANDROID_PACKAGE_SOURCE_DIR} on top of this, overwriting
    any existing files. The update step where parts of the source files are modified automatically
    to reflect your other settings is then run on the resulting merged package. If you, for
    instance, want to make a custom \c{AndroidManifest.xml} for your application, then place this
    directly into the folder specified in this variable. You can also add custom Java files in
    \c{ANDROID_PACKAGE_SOURCE_DIR/src}.
    \note When adding custom versions of the build files (like strings.xml, libs.xml,
     AndroidManifest.xml, etc.) to your project, make sure you copy them from the package template,
     which is located in \c{$QT/src/android/java}. You should never copy any files from the build
     directory, as these files have been altered to match the current build settings.
    \li \c{ANDROID_EXTRA_LIBS}: A list of external libraries that will be copied into your application's
    library folder and loaded on start-up. This can be used, for instance, to enable OpenSSL
    in your application. Simply set the paths to the required \c{libssl.so} and \c{libcrypto.so}
    libraries here and OpenSSL should be enabled automatically.
    \li \c{ANDROID_EXTRA_PLUGINS}: This variable can be used to specify different resources that your
    project has to bundle but cannot be delivered through the assets system, such as qml plugins. When
    using this variable, \c androiddeployqt will make sure everything is packaged and deployed properly.
    \endlist

    \section1 Deployment in Qt Creator

    Qt Creator will run the \c androiddeployqt tool for you, and provides easy and intuitive user
    interfaces to specify many of the options. For more information, see
    \l{Qt Creator: Deploying Applications to Android Devices}{the Qt Creator documentation}.
*/