qt-creator/doc/src/android/deploying-android.qdoc

/**************************************************************************
**
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** 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.
**
**
**************************************************************************/

    /*!

    \contentspage index.html
    \previouspage creator-deployment.html
    \page creator-deploying-android.html
    \nextpage creator-deployment-bb10.html

    \title Deploying Applications to Android Devices

    On Android, applications are distributed in specially structured type of ZIP
    packages called APK. \QC supports the following methods of deployment for
    Android applications:

     \list

        \li As a stand-alone, distributable application package (APK).

        \li As a minimal APK that contains a dependency to the Ministro tool.
            The Ministro tool downloads the necessary Qt libraries from a
            repository of your choice.

        \li As an incomplete APK that is suitable for testing and debugging
            applications on a device connected to the development host. The APK
            relies on the device containing the Qt libraries in the correct
            location. \QC copies the libraries to that location the first time
            you deploy the application.

    \endlist

    The default option depends on whether you are developing with Qt 4 or Qt 5.
    The Necessitas SDK does not support bundling Qt libraries with applications,
    so you must use Ministro when developing with Qt 4. To specify the
    deployment method, select \gui Projects > \gui Run >
    \gui {Deploy configurations} > \gui Details

    \section1 Creating Distributable APK Packages

    To copy Qt libraries and files to the project directory and to bundle them
    as part of the APK, select the \gui {Bundle Qt libraries in APK} option.
    This is the default option when developing with Qt 5. It is not supported
    when developing with Qt 4.

    \section1 Using Ministro to Install Qt Libraries

    To minimize the size of your APK, you can package the application with an
    external dependency called Ministro. If a user downloads your application,
    and it is the first application on their device to depend on Ministro, they
    are asked to install Ministro before they can run your application.

    Ministro serves as a central repository for Qt libraries. This enables
    several applications to share the libraries, which only need to be installed
    once. To use this deployment method, you must set up a repository for the
    libraries that you want to distribute. To specify the
    repository URL, edit the file \c {android/res/values/libs.xml}, which is
    created by \QC.

    To use Ministro to install the Qt libraries, select the
    \gui {Use Ministro service to install Qt} option.

    This is the default option when developing with Qt 4.

    \section1 Deploying Qt Libraries for Debugging

    To test your application on a device that is physically connected to the
    development host (or on an emulator), you can copy the Qt libraries into a
    temporary directory on your device and run the application against them.

    An APK built in this way is not distributable, since it relies on the device
    containing the Qt libraries in the correct location. However, as the Qt
    libraries are only copied into the device once, this method provides a fast
    turn-around time, and is therefore convenient for testing the application
    during development.

    Select the \gui {Deploy local Qt libraries to temporary directory} option to
    deploy Qt libraries to the \c{/data/local/tmp/qt} folder on the device and
    to run the application against them.

    To deploy new Qt libraries to the device, select
    \gui {Clean Temporary Libraries Directory on Device}. The next time you
    deploy the application, Qt libraries are copied to the device again.

    \section1 Packaging Qt 4 Applications

    When you select a \gui {Qt for Android Kit} that specifies Qt 4 for a
    project, \QC creates and maintains a set of files that are required to make
    your application run on Android devices.

    \QC adds the following files to your project:

    \list

        \li Java files, which serve as the entry point into your application and
            that automatically load Qt and execute the native code in your
            application.

        \li AndroidManifest.xml, which provides meta-information about your
            application.

        \li Other XML files, which specify the dependencies of your application.

        \li Resource files.

        \li Libraries and QML files, which can be included in the project
            depending on the deployment method that you select.

    \endlist

    \QC adds the files to the project to a subdirectory called \c android. The
    contents of the \c android folder are used to create a distributable
    application package.

    To view the packages that \QC created, select the
    \gui {Open package location after is complete} check box.

    To specify information for the Android manifest file, open it in \QC. For
    more information, see \l{Editing Manifest Files}.

    \section2 Specifying Settings for Qt 4 Packages

    \include creator-projects-settings-run-android.qdocinc

    \section1 Packaging Qt 5 Applications

    Because bundling applications as APK packages is not
    trivial, Qt 5 provides a deployment tool called \c androiddeployqt.
    When you deploy an application using a \gui {Qt for Android Kit}, \QC uses
    the \c androiddeployqt tool to create the necessary files and to bundle them
    into an APK.

    To view the packages that the \c androiddeployqt tool created, select the
    \gui {Open package location after build} check box.

    The packages are deployed on the connected Android devices. To switch the
    device used as a default device for the selected kit, select
    \gui {Reset Default Devices}. The setting applies until you restart \QC.
    For more information, see \l{Selecting Android Devices}.

    For more information about the \c androiddeployqt tool, see
    \l{http://qt-project.org/doc/qt-5/deployment-android.html}
    {Deploying an Application on Android}.

    \section2 Specifying Settings for Qt 5 Packages

    You can specify settings for the \c androiddeployqt tool in \QC and in the
    project .pro file. To specify settings in \QC, select
    \gui Projects > \gui Run > \gui {Deploy configurations} > \gui Details.

    \image qtcreator-android-deploy-configurations.png "Deploy configurations"

    The anddroiddeployqt tool uses the information in the project .pro file to
    create APKs. For more information about the qmake variables
    that you can set in the .pro file to tailor the APK, see
     \l{http://qt-project.org/doc/qt-5/deployment-android.html#qmake-variables}
    {qmake Variables}.

    You can view information about what the anddroiddeployqt tool is doing in
    the \gui {Compile Output} pane. To view additional information, select the
    \gui {Verbose output} check box.

    \section3 Selecting API Level

    In the \gui {Android target SDK} field, you can select the API level to use
    for building the application. Usually, you should select the newest API
    level available.

    This field does not specify the minimum supported API level nor the target
    API level, which you can specify in the Android manifest file.
    For more information about Android API levels, see
    \l{http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels}
    {What is API Level?}.

    \section3 Signing Android Packages

    In the \gui {Sign Package} group you can sign the Android package by using
    a private key from the keystore. To create new keys, select \gui Create.

    \section2 Adding External Libraries

    \QC automatically detects which Qt libraries the application uses and adds
    them as dependencies. If the application needs external libraries, specify
    them in the \gui {Additional Libraries} field. The libraries are copied into
    your application's library folder and loaded on startup.

    For example, to enable OpenSSL in your application, add the paths to the
    required \c libssl.so and \c libcrypto.so libraries to the
    \gui {Additional Libraries} field.

    \section1 Installing Ministro

    The easiest way to install Ministro is to do it on the device via Google
    Play. When you run the application for the first time, a dialog pops up and
    guides you through the installation.

    To use \QC to install Ministro, you must first download the Ministro .apk
    from the Google Market or from the
    \l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro} home page.

    Then select \gui {Install Ministro from APK}.

    You can use this option also to install any Android package (.apk).

    You can use this option to install applications on an Android Virtual
    Device (AVD).

    \section1 Editing Manifest Files

    When you develop with Qt 4, \QC creates the Android manifest file for you,
    and you can open it for editing in the Android Manifest Editor.

    When you develop with Qt 5, you can use the qmake variables to specify all
    the settings you need for the \c androiddeployqt tool and you do not need an
    Android manifest file until you want to publish the package in an
    application store. To specify additional settings for APK packages, you can
    create an Android manifest file and edit it in \QC. Select
    \gui {Create AndroidManifest.xml} to create the file and to open it in the
    Android Manifest Editor.

    \image qtcreator-android-manifest-editor.png "Android Manifest Editor"

    Select the \gui {XML Source} tab to edit the file in XML format.

    In the \gui {Package name} field, enter a package name for the application.
    The application is launched by an automatically generated Java launcher that
    is packaged with the application into an Android package (.apk). For more
    information, see
    \l{http://developer.android.com/guide/components/fundamentals.html}
    {Android Application Fundamentals}.

    You can specify an internal version number for the package in the
    \gui {Version code} field. It is used to determine whether one version of
    the application is more recent than another. In the \gui {Version name}
    field, specify the version number that is shown to users.

    In the \gui {Minimum required SDK} field, select the minimum API level
    required to run the application. The minimum API level is android-4 for
    Necessitas and android-9 for Qt 5. \QC does not allow you to select an API
    level that the Qt version specified for the kit does not support.

    \note The android-4 API level does not support multitouch. If your
    application needs multitouch, select a higher API level.

    In the \gui {Target SDK} field, select the targeted API level of the
    application. This affects the activation of some compatibility features in
    the OS. The value used by the \c androiddeployqt tool by default is 14, which
    means that the overflow button in the system navigation bar will not be
    enabled by default.

    In the \gui Application group, you can give the application a name and
    select an icon for it. The three icon fields can contain different versions
    of the icon with low, medium, and high DPI values, from left to right.

    In the \gui Permissions field, you can specify the permissions that your
    application needs. Users are asked to grant the permissions when they
    install the application. Android OS then grants the application access to
    the appropriate data and features.

    To add permissions, select \gui Add and select permissions from the list.
*/