deploying-android.qdoc 14.1 KB
Newer Older
hjk's avatar
hjk committed
Leena Miettinen's avatar
Leena Miettinen committed
Eike Ziller's avatar
Eike Ziller committed
3 4
** Copyright (C) 2015 The Qt Company Ltd.
** Contact:
Leena Miettinen's avatar
Leena Miettinen committed
hjk's avatar
hjk committed
** This file is part of Qt Creator
Leena Miettinen's avatar
Leena Miettinen committed
7 8 9 10 11 12 13 14 15 16
** 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.
hjk's avatar
hjk committed
Leena Miettinen's avatar
Leena Miettinen committed
18 19 20


    \contentspage {Qt Creator Manual}
    \previouspage creator-deployment.html
Leena Miettinen's avatar
Leena Miettinen committed
    \page creator-deploying-android.html
    \nextpage creator-deployment-embedded-linux.html
Leena Miettinen's avatar
Leena Miettinen committed
25 26 27

    \title Deploying Applications to Android Devices

28 29 30
    On Android, applications are distributed in a specially structured type of
    ZIP package called an APK. \QC supports the following methods of deployment
    for Android applications:
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47


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


48 49
    To specify settings for application packages, select \uicontrol Projects >
    \uicontrol {Build Android APK} > \uicontrol Details.

    \section1 Creating Distributable APK Packages
Leena Miettinen's avatar
Leena Miettinen committed

    To copy Qt libraries and files to the project directory and to bundle them
    as part of the APK, select the \uicontrol {Bundle Qt libraries in APK} option.

56 57
    \note Android 5 devices support only this option.

58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
    \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
    \uicontrol {Use Ministro service to install Qt} option.

75 76 77 78 79 80 81 82 83 84 85 86
    \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 \uicontrol {Deploy local Qt libraries to temporary directory} option to
88 89
    deploy Qt libraries to the \c{/data/local/tmp/qt} folder on the device and
    to run the application against them.
Leena Miettinen's avatar
Leena Miettinen committed

    \section1 Packaging Applications

93 94
    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 \uicontrol {Qt for Android Kit}, \QC uses
96 97
    the \c androiddeployqt tool to create the necessary files and to bundle them
    into an APK:
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114


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

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

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

115 116 117 118 119 120 121
        \li Gradle wrappers that are needed to download and use Gradle.

        \li Gradle script that is needed by Java IDEs, such as Android Studio.
            It allows the user to extend the Java part without copying our Java
            sources. It also allows the IDEs to provide code completion, syntax
            highlighting, and so on.

122 123

    The Gradle wrappers and scripts are bundled only if you use Gradle, which is
    the default. To use Ant instead, deselect the \uicontrol {Use Gradle} check box.

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

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

    For more information about the \c androiddeployqt tool, see
    \l{Deploying an Application on Android}.

    \section2 Specifying Settings for Packages
140 141

    You can specify settings for the \c androiddeployqt tool in \QC and in the
142 143
    project .pro file. To specify settings in \QC, select \uicontrol Projects >
    \uicontrol {Build Android APK} > \uicontrol Details.
144 145 146 147 148 149

    \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{Deploying an Application on Android}.
151 152

    You can view information about what the anddroiddeployqt tool is doing in
153 154
    the \uicontrol {Compile Output} pane. To view additional information, select the
    \uicontrol {Verbose output} check box.
155 156 157

    \section3 Selecting API Level

    In the \uicontrol {Android build SDK} field, you can select the API level to use
159 160 161 162 163 164 165 166 167 168 169
    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
    {What is API Level?}.

    \section3 Signing Android Packages

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
    To publish your application, you must sign it by using a \e {public-private
    key pair} that consists of a \e certificate and a corresponding
    \e {private key} and is identified by an \e alias. The key pair is used to
    verify that the future versions of your application are actually created by

    \warning Keep the key pair in a safe place and take back up copies, because
    you cannot update the application if you lose the key pair.

    You can use \QC to generate a keystore and a \e {self-signed} certificate.
    The generated certificate has the structure of an X.509 v3 digital
    certificate. It contains information about the version, serial number, and
    validity period of the certificate, the ID of the algorithm that is used to
    encrypt the data, the organization that issued the certificate, and the
    \e subject (owner) of the certificate. In case of a self-signed certificate,
    the issuer and owner of the certificate are the same. In addition, the
    certificate contains information about the algorithm that is used to sign
    the certificate, as well as the signature of the certificate.

    The keystore is protected by a password. In addition, you can protect each
    alias with its individual password.

    When you sign an Android application, you must select a keystore that
    contains certificates and a certificate alias from the keystore. The public
    key (certificate) for the alias is embedded into the APK during signing.

    To create a keystore and a self-signed certificate:

    \list 1

200 201
        \li In the \uicontrol Keystore field, select \uicontrol Create to create a new
            keystore that contains one key pair in the \uicontrol {Create Keystore and
202 203 204 205
            a Certificate} dialog:

            \image qtcreator-android-certificate.png

        \li In the \uicontrol Keystore group, enter a password to protect the
207 208

        \li In the \uicontrol Certificate group, specify the key size and validity
210 211 212
            period of the certificate. You can specify a separate password to
            protect the key pair or use the keystore password.

        \li In the \uicontrol {Certificate Distinguished Names} group, enter
214 215 216
            information about yourself and your company or organization that
            identifies the issuer and the owner of the key pair.

        \li Select \uicontrol Save.

        \li In the \uicontrol {Keystore File Name} dialog, enter a name for the
220 221
            keystore and select a location for it.

        \li In the \uicontrol Keystore dialog, enter the keystore password to create
223 224 225 226 227
            the key pair in the keystore.


    To sign an Android package by using a key pair, specify settings in the
    \uicontrol {Sign package} group:
229 230 231

    \list 1

        \li In the \uicontrol Keystore field, select \uicontrol Choose to select an existing
233 234

        \li In the \uicontrol {Certificate alias} field, select an alias from the list
236 237
            of key pairs that the keystore contains.

        \li Select the \uicontrol {Sign package} check box to use the alias to
239 240 241
            sign the Android package.


    \section3 Adding External Libraries
244 245 246

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

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

    \section3 Editing Manifest Files

    You can use the qmake variables to specify all
257 258 259 260
    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
    \uicontrol {Create Templates} to create the file and to open it in the
262 263 264 265
    Android Manifest Editor.

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

    \list 1

    \li In the \uicontrol {Package name} field, enter a package name for the application.
269 270 271 272 273 274
    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
    {Android Application Fundamentals}.

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

    \li In the \uicontrol {Minimum required SDK} field, select the minimum API level
281 282
    required to run the application. The minimum supported API level is
    android-9. \QC does not allow you to select an API
283 284
    level that the Qt version specified for the kit does not support.

    \li In the \uicontrol {Target SDK} field, select the targeted API level of the
286 287 288 289 290
    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.

    \li In the \uicontrol Application group, you can give the application a name and
292 293
    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.
    You can also give an activity a name and select the activity to run.

    \li In the \uicontrol Permissions field, you can specify the permissions that your
297 298 299 300
    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.

301 302
    \li Select the \uicontrol {Include default permissions for Qt modules} and
    \uicontrol {Include default features for Qt modules} check boxes to add the
303 304
    permissions needed by Qt libraries.

    \li To add permissions, select them in the list, and then select \uicontrol Add.
306 307 308


    Select the \uicontrol {XML Source} tab to edit the file in XML format.
310 311 312 313 314 315 316 317 318 319 320

    \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{}{Ministro} home page.

    Then select \uicontrol Projects > \uicontrol Run > \uicontrol {Install Ministro from APK}.
322 323 324 325 326

    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).

Leena Miettinen's avatar
Leena Miettinen committed
328 329