forked from qt-creator/qt-creator
96e5eca1c3
Docs affected: * Connecting Android Devices * Deploying Applications to Android Devices * Specifying Run Settings for Android Devices Task-number: QTBUG-80390 Change-Id: I17fecd4d947644d8cc6071af68addbc2199ad82e Reviewed-by: Eike Ziller <eike.ziller@qt.io> Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
342 lines
15 KiB
Plaintext
342 lines
15 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2019 The Qt Company Ltd.
|
|
** Contact: https://www.qt.io/licensing/
|
|
**
|
|
** This file is part of the Qt Creator documentation.
|
|
**
|
|
** 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 https://www.qt.io/terms-conditions. For further
|
|
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
|
|
\contentspage index.html
|
|
\previouspage creator-deployment.html
|
|
\page creator-deploying-android.html
|
|
\nextpage creator-deployment-embedded-linux.html
|
|
|
|
\title Deploying Applications to Android Devices
|
|
|
|
On Android, applications are distributed in specially structured types of
|
|
ZIP packages called Application Packages (APK) or Android App Bundles (AAB).
|
|
APK files can be downloaded to and executed on a device, whereas AAB is
|
|
intended to be interpreted by the Google Play store and is used to generate
|
|
APK files.
|
|
|
|
\l{Qt for Android} has binaries for armv7a, arm64-v8a, x86, and x86-64.
|
|
To support several different ABIs in your application, build an AAB that
|
|
contains binaries for each of the ABIs. The Google Play store uses the
|
|
AAB to generate optimized APK packages for the devices issuing the download
|
|
request and automatically signs them with your publisher key.
|
|
|
|
\QC supports the following methods of deployment for Android applications:
|
|
|
|
\list
|
|
\li As a stand-alone, distributable application package (APK).
|
|
\li Since Qt 5.14.0, as an app bundle (AAB), intended for distribution
|
|
in the Google Play store.
|
|
\endlist
|
|
|
|
\note Since \QC 4.12, Ministro is not supported.
|
|
|
|
To specify settings for application packages, select \uicontrol Projects >
|
|
\uicontrol {Build Android APK} > \uicontrol Details.
|
|
|
|
\if defined(qtcreator)
|
|
For more information about options that you have for running applications,
|
|
see \l {Specifying Run Settings for Android Devices}.
|
|
\endif
|
|
|
|
\section1 Packaging 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 \uicontrol {Qt for Android Kit}, \QC uses
|
|
the \c androiddeployqt tool to create the necessary files and to bundle them
|
|
into an APK:
|
|
|
|
\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.
|
|
|
|
\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.
|
|
|
|
\endlist
|
|
|
|
The Gradle wrappers and scripts are bundled only if you use Gradle to build
|
|
the application packages. For more information, see
|
|
\l{Connecting Android Devices}.
|
|
|
|
To view the packages that the \c androiddeployqt tool created, select the
|
|
\uicontrol {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
|
|
\uicontrol Projects > \uicontrol Run > \uicontrol {Deploy to Android device}
|
|
> \uicontrol {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{Deploying an Application on Android}.
|
|
|
|
\section2 Specifying Settings for Packages
|
|
|
|
You can specify settings for the \c androiddeployqt tool in \QC and in the
|
|
project .pro file. To specify settings in \QC, select \uicontrol Projects >
|
|
\uicontrol Build > \uicontrol {Build Android APK} > \uicontrol 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{Deploying an Application on Android}.
|
|
|
|
You can view information about what the anddroiddeployqt tool is doing in
|
|
the \uicontrol {Compile Output} pane. To view additional information, select the
|
|
\uicontrol {Verbose output} check box.
|
|
|
|
\section3 Selecting API Level
|
|
|
|
In the \uicontrol {Android build SDK} field, you can select the API level to use
|
|
for building the application. Usually, you should select the newest API
|
|
level available.
|
|
|
|
\note For Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1, Android build SDK 28 should
|
|
be used. For recent versions than the latter, build SDK 29, or the most recent
|
|
should be used.
|
|
|
|
This field does not specify the minimum supported API level nor the target
|
|
API level, which you can specify in the Android manifest. See
|
|
\l{Editing Manifest Files}. 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 Building AABs
|
|
|
|
For testing the application locally, use the APK format, because
|
|
the package can be uploaded directly to the device and run. For
|
|
distribution to the Google Play store, create an AAB by selecting
|
|
the \uicontrol {Build .aab (Android App Bundle)} check box.
|
|
|
|
When building with CMake, you can select the ABIs to build the application
|
|
for in the \uicontrol CMake settings:
|
|
|
|
\image qtcreator-android-cmake-settings.png "CMake settings for building AABs"
|
|
|
|
When building with qmake, you can select the ABIs in the \uicontrol ABIs
|
|
field in the \uicontrol {Build Steps}:
|
|
|
|
\image qtcreator-android-build-steps.png "Android Build Steps"
|
|
|
|
\section3 Signing Android Packages
|
|
|
|
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
|
|
you.
|
|
|
|
\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
|
|
|
|
\li In the \uicontrol Keystore field, select \uicontrol Create to create
|
|
a new keystore that contains one key pair in the
|
|
\uicontrol {Create a Keystore and a Certificate} dialog:
|
|
|
|
\image qtcreator-android-certificate.png
|
|
|
|
\li In the \uicontrol Keystore group, enter a password to protect the
|
|
keystore.
|
|
|
|
\li In the \uicontrol Certificate group, specify the key size and validity
|
|
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
|
|
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
|
|
keystore and select a location for it.
|
|
|
|
\li In the \uicontrol Keystore dialog, enter the keystore password to create
|
|
the key pair in the keystore.
|
|
|
|
\endlist
|
|
|
|
To sign an Android package by using a key pair, set the \uicontrol {Sign package}
|
|
group settings described in \l{Specifying Settings for Packages}:
|
|
|
|
\list 1
|
|
|
|
\li In the \uicontrol Keystore field, select \uicontrol Choose to select an existing
|
|
keystore.
|
|
|
|
\li In the \uicontrol {Certificate alias} field, select an alias from the list
|
|
of key pairs that the keystore contains.
|
|
|
|
\li Select the \uicontrol {Sign package} check box to use the alias to
|
|
sign the Android package.
|
|
|
|
\endlist
|
|
|
|
\section3 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 \uicontrol Projects > \uicontrol Build > \uicontrol {Build Android APK}
|
|
> \uicontrol {Additional Libraries} field. The libraries are copied into
|
|
your application's library folder and loaded on startup.
|
|
|
|
To add OpenSSL libraries, select \uicontrol {Include prebuilt OpenSSL libraries}
|
|
in the \uicontrol {Additional Libraries} group. This will add the OpenSSL
|
|
include project defined in \l{Specifying Android Device Settings}{device settings}
|
|
in \uicontrol {Android OpenSSL} group. This can be used for QMake and CMake
|
|
projects.
|
|
|
|
Otherwise, you can manually add the paths to the required \c libssl.so and
|
|
\c libcrypto.so libraries to the \uicontrol {Additional Libraries} field.
|
|
|
|
\section1 Editing Manifest Files
|
|
|
|
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 unless you need to specify Android specific settings
|
|
like the application's icon. Also, the manifest file is needed if you want
|
|
to publish the package in the Play Store.
|
|
You can create an Android manifest file and edit it in \QC. Select
|
|
\uicontrol Projects > \uicontrol Build > \uicontrol {Build Android APK}
|
|
> \uicontrol {Create Templates} to create the file and to open it in the
|
|
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.
|
|
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}.
|
|
|
|
\li You can specify an internal version number for the package in the
|
|
\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}
|
|
field, specify the version number that is shown to users.
|
|
|
|
\li In the \uicontrol {Minimum required SDK} field, select the minimum API level
|
|
required to run the application. The minimum supported API level for \QC is
|
|
android-9. However, Qt versions might have different minimum API levels, and
|
|
therefore \QC does not allow you to select an API 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
|
|
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 set the application's name.
|
|
You can also give an activity a name and select the activity to run.
|
|
|
|
\li The \uicontrol {Style extraction} combo box sets the used method that Qt
|
|
uses to extract style information. It has the following values:
|
|
\list
|
|
\li \uicontrol Default or \uicontrol Full: Use this when working with
|
|
Qt Widgets or Qt Quick Controls 1.
|
|
|
|
\note This method uses some Android non-SDK interfaces,
|
|
that are being restricted by Google starting from Android 9.0
|
|
(API 28).
|
|
\li \uicontrol minimal: Use this when working with Qt Quick Controls 2
|
|
with no Qt Widgets or Qt Quick Controls 1. This is faster than
|
|
\uicontrol full or \uicontrol default.
|
|
\li \uicontrol none: Use this if you're not working with Qt Widgets,
|
|
or Qt Quick Controls 1 or 2 in your project.
|
|
\endlist
|
|
|
|
\li In \uicontrol {Application icon}, select an icon. Click the
|
|
\uicontrol {Master icon} button to select an icon with the highest resolution,
|
|
then, it will resize and set the three icon fields for low, medium, and high DPI icons
|
|
as needed.
|
|
|
|
\li In the \uicontrol Permissions field, you can specify the permissions that your
|
|
application needs. Starting from Android 6.0 (API 23), permissions have to be
|
|
requested at runtime (See \l{QtAndroidExtras}{requestPermissionsSync} or
|
|
\l{QtAndroidExtras}{requestPermissions}). For lower Android API levels,
|
|
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.
|
|
|
|
\li Select the \uicontrol {Include default permissions for Qt modules} and
|
|
\uicontrol {Include default features for Qt modules} check boxes to add the
|
|
permissions needed by Qt libraries. This can be
|
|
android.permission.WRITE_EXTERNAL_STORAGE for QtCore, or
|
|
android.permission.ACCESS_COARSE_LOCATION for QtLocation.
|
|
|
|
\li To add a permission, select it from the list, and then click \uicontrol Add.
|
|
|
|
\endlist
|
|
|
|
On the top header, select the \uicontrol {XML Source} tab to edit the file
|
|
in XML format.
|
|
|
|
*/
|
|
|