feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity
Files
f708e200f9e3bcc9fe8842135b19cf16274c2219
qt-creator/doc/qtcreator/src/android/deploying-android.qdoc
Leena Miettinen f708e200f9 Doc: Restructure info about build and run configurations 
Task-number: QTCREATORBUG-29361
Change-Id: I9e9d3a3448c327938e4f647b37a88857db5b16c4
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
Reviewed-by: Alessandro Portale <alessandro.portale@qt.io>
2023-12-05 12:30:54 +00:00

497 lines
21 KiB
Plaintext
Raw Blame History

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\previouspage creator-deployment.html
\page creator-deploying-android.html
\nextpage creator-deployment-b2qt.html
\title Deploying to Android
Android applications are packaged as ZIP files called Application Packages
(APK) or Android App Bundles (AAB). You can install and run APK files on a
device. You can upload AAB files to the Google Play store.
\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
has binaries for each of the ABIs. The Google Play store uses the AAB
to generate optimized APK packages for the devices that request download
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 As an app bundle (AAB) for distribution in the Google Play store.
All Qt versions do not support AABs. Qt 6.3.0 and later support
multi-abi builds for applications that you build with CMake. For
more information, see \l{Qt for Android - Building User Projects}.
\endlist
\note Since \QC 4.12, Ministro is not supported.
To \l{Specifying Settings for Packages}{specify settings} for application
packages, select \uicontrol Projects > \uicontrol Build >
\uicontrol {Build Android APK} > \uicontrol Details.
For more information about options that you have for running applications,
see \l {Android Run Settings}.
\section1 Packaging Applications
Because bundling applications as APK packages is not trivial, Qt has the
\l {The androiddeployqt Tool}{androiddeployqt} tool. When you deploy an
application using a \e {Qt for Android kit}, \QC runs the tool to
create the necessary files and to bundle them into an APK. For more
information, see \l{Android Package Templates}.
To view the packages that the \c androiddeployqt tool created, select the
\uicontrol {Open package location after build} check box.
\section2 Specifying Deployment Settings
The \uicontrol Method field lists deployment settings.
To add deployment methods for a project, select \uicontrol Add.
\image qtcreator-android-deployment-settings.png {Deployment settings}
To rename the current deployment method, select \uicontrol Rename.
To remove the current deployment method, select \uicontrol Remove.
\QC deploys the packages on the Android device that you select in the
\l{Building for Multiple Platforms}{kit selector}. To add devices, select
\uicontrol Manage.
For more information about specifying additional start options for
applications, see \l{Android Run Settings}.
To remove previously installed files from the device, select
\uicontrol {Uninstall the existing app before deployment}.
To install a pre-built APK, such as a 3rd-party application to a device,
select \uicontrol {Install an APK File}.
\section2 Specifying Settings for Packages
To specify settings for the \c androiddeployqt tool, select
\uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build >
\uicontrol {Build Android APK} > \uicontrol Details.
\image qtcreator-build-settings-android-apk.webp {Build Android APK step}
The \c androiddeployqt tool create APKs based on the settings. For more
information about the available options, see \l{androiddeployqt}.
You can view information about what the \c androiddeployqt tool is doing in
\l {Compile Output}. To view more information, select the
\uicontrol {Verbose output} check box.
Select \uicontrol {Add debug server} to include the debug server binary
into a package.
\section3 Selecting API Level
In the \uicontrol {Android build platform SDK} field, select the
\l{What is API Level?}{API level} to use for building the application.
Usually, you should select the highest API level available.
Usually, you should use the highest version of the Android SDK
build-tools for building. If necessary, select another version
in the \uicontrol {Android build-tools version} field.
\section3 Building AABs
For testing the application locally, use the APK format because
\QC can install and run the package on the device. For distribution
to the Google Play store, create an AAB by selecting
the \uicontrol {Build Android App Bundle (*.aab)} check box.
When building with CMake, you can view the selected ABIs in
\uicontrol {Initial Configuration} in the \uicontrol CMake section.
You can set additional ABIs as values of the \c ANDROID_ABI key:
\image qtcreator-android-cmake-settings.png {CMake settings for building AABs}
When building with Qbs or qmake, you can select the ABIs in the
\uicontrol ABIs field in the \uicontrol {Build Steps}:
\image qtcreator-android-build-steps.png {qmake settings for building AABs}
\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 has 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 has information about the algorithm that is used to sign
the certificate, as well as the signature of the certificate.
A password protects the keystore. In addition, you can protect each
alias with its individual password.
When you sign an Android application, you must select a keystore that
has certificates and a certificate alias from the keystore. The signing
process embeds the public key (certificate) for the alias into the APK.
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 has 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 has.
\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 configuration options to specify all the settings you need
for the \c androiddeployqt tool. You only need an Android manifest file
to specify Android-specific settings, such as the application icon.
However, you need the manifest file to publish the package in the Play Store.
For more information about manifest files, see
\l {Qt Android Manifest File Configuration}.
If you use CMake as the build system, you must specify the Android package
source directory, \c QT_ANDROID_PACKAGE_SOURCE_DIR, in the CMakeList.txt
file, as instructed in the \l{Locking Device Orientation}
{mobile device tutorial}.
To use \QC to create an Android manifest file and to open it in the Android
Manifest Editor:
\list 1
\li Select \uicontrol Projects > \uicontrol Build >
\uicontrol {Build Android APK} > \uicontrol {Create Templates}.
\li Check the path in \uicontrol {Android package source directory}.
\image qtcreator-android-create-template.png {Create Template dialog}
\li Select \uicontrol {Copy the Gradle files to Android directory} if you
plan to extend the Java part of your Qt application.
\li Select \uicontrol Finish to copy the template files to the \c android
directory and to open the manifest file for editing.
\image qtcreator-android-manifest-editor-package.webp {Package info in Android Manifest Editor}
\endlist
The following table summarizes the options you can set.
\table
\header
\li Option
\li Value
\row
\li \uicontrol {Package name}
\li A valid \l{Package Names}{package name} for the application.
For example, \c {org.example.myapplication}.
An automatically generated Java launcher that is packaged with the
application into an APK launches the application.
\row
\li \uicontrol {Version code}
\li An internal version number for the package that determines whether
one version of the application is more recent than another.
\row
\li \uicontrol {Version name}
\li The version number that is visible to users.
\row
\li \uicontrol {Minimum required SDK}
\li The minimum API level required to run the application if you set it
manually in the manifest file.
\row
\li \uicontrol {Target SDK}
\li The targeted API level of the application if you set it manually in
the manifest file.
\row
\li \uicontrol {Application name}
\li The application's name.
\row
\li \uicontrol {Activity name}
\li An activity name.
\row
\li \uicontrol {Style extraction}
\li The method that Qt uses to determine which \l{Styling}{UI style}
to use.
\row
\li \uicontrol {Screen orientation}
\li How to determine \l{Screen Orientation}{screen orientation}.
\row
\li \uicontrol {Application icon}
\li Images to use as \l{Icons}{application icons} depending on screen
resolution.
\row
\li \uicontrol {Splash screen}
\li Images to display as \l{Splash Screens}{splash screens} depending on
the screen orientation and resolution.
\row
\li \uicontrol Permissions
\li The \l{Setting Permissions}{permissions} that the application needs.
\endtable
On the top header, select the \uicontrol {XML Source} tab to edit the file
in XML format.
\section2 Package Names
Android application packages are usually named by using a hierarchical
pattern with the levels in the hierarchy separated by periods (.). In
general, a package name begins with the top level domain name of the
organization followed by the organization's domain name and any subdomain
names listed in reverse order. The organization can then choose a specific
name for their package. Package names should be written in all lowercase
characters whenever possible. For example, \c {org.qtproject.example}.
Complete conventions for disambiguating package names and rules for naming
packages when the Internet domain name cannot be directly used as a package
name are described in section 7.7 of the Java Language Specification.
For more information about package names, see
\l{Android Application Fundamentals}.
\section2 Styling
Qt uses different methods to determine how Qt Widgets and Qt Quick Controls
should be styled:
\list
\li Select \uicontrol Default or \uicontrol Full when using
Qt Widgets or Qt Quick Controls 1 in your project.
\note This method uses some Android non-SDK interfaces,
that are being restricted by Google starting from Android 9.0
(API 28).
\li Select \uicontrol Minimal when using Qt Quick Controls 2
but no Qt Widgets or Qt Quick Controls 1. This is faster than
using the default or full options.
\li Select \uicontrol None when using neither Qt Widgets
nor Qt Quick Controls 1 or 2.
\endlist
\section2 Screen Orientation
You can specify different options for determining screen orientation,
depending on sensor readings or user preferences. The following table
lists the options available.
\table
\header
\li Orientation
\li Description
\row
\li Unspecified
\li The system chooses the orientation. The policy it uses, and
therefore the choices made in specific contexts, may differ
from device to device.
\row
\li Behind
\li Use the same orientation as the activity that's immediately
beneath it in the activity stack.
\row
\li Landscape
\li Landscape orientation, where the display width is larger than
its height.
\row
\li Portrait
\li Portrait orientation, where the display height is larger than
its width.
\row
\li Reverse landscape
\li Landscape orientation in the opposite direction of normal
landscape.
\row
\li Reverse portrait
\li Portrait orientation in the opposite direction of normal
portrait.
\row
\li Sensor landscape
\li Landscape orientation, but it can be either normal or reverse
landscape based on the device sensor. The sensor is used even
if the user has locked sensor-based rotation.
\row
\li Sensor portrait
\li Portrait orientation, but it can be either normal or reverse
portrait based on the device sensor. The sensor is used even
if the user has locked sensor-based rotation.
\row
\li User landscape
\li Landscape orientation, but it can be either normal or reverse
landscape based on the device sensor and the user's preference.
\row
\li User portrait
\li Portrait orientation, but it can be either normal or reverse
portrait based on the device sensor and the user's preference.
\row
\li Sensor
\li The orientation is determined by the device orientation sensor.
The orientation of the display depends on how the user is
holding the device. It changes when the user rotates the device.
Some devices, however, will not rotate to all four possible
orientations by default. To allow all four orientations, select
the full sensor option. The sensor is used even if the user
locked sensor-based rotation.
\row
\li Full sensor
\li The orientation is determined by the device orientation sensor
for any of the four orientations. This is similar to the sensor
option, except that it allows any of the four possible screen
orientations, regardless of what the device will normally do.
For example, some devices won't normally use reverse portrait
or reverse landscape, but this option enables them.
\row
\li No sensor
\li The orientation is determined without reference to a physical
orientation sensor. The sensor is ignored, so the display will
not rotate based on how the user moves the device.
\row
\li User
\li The user's current preferred orientation.
\row
\li Full user
\li If the user has locked sensor-based rotation, this option
behaves in the same way as the user option. Otherwise, it
behaves the same as the full sensor option, and allows any
of the four possible screen orientations.
\row
\li Locked
\li Locks the orientation to its current rotation, whatever that is.
\endtable
\section2 Icons
You can set different images to be shown as application icons and splash
screens on low, medium, high, and extra high DPI displays. The following
list summarizes the DPI values typically associated with each category:
\list
\li Low-density (LDPI): ~120dpi
\li Medium-density (MDPI): ~160dpi
\li High-density (HDPI): ~240dpi
\li Extra-high-density (XHDPI): ~320dpi
\li Extra-extra-high-density (XXHDPI): ~480dpi
\li Extra-extra-extra-high-density (XXXHDPI): ~640dpi
\endlist
Specify settings for icons in the \uicontrol {Application icon} tab. Select
the image with the highest resolution as the \uicontrol {Master icon}.
\QC resizes the icon and sets versions of it to be shown on low, medium,
high, and extra high DPI displays, as needed. Alternatively, set the icons
for each resolution separately.
\image qtcreator-android-manifest-editor-app-icon.webp {Application icons in Android Manifest Editor}
\section2 Splash Screens
Specify settings for splash screens in the \uicontrol {Splash screen} tab.
Select images to display as splash screens depending on the device
orientation and screen resolution.
\image qtcreator-android-manifest-editor-splash-screen.webp {Splash screens in Android Manifest Editor}
By default, drawing an activity hides the splash screen. To keep it visible until
\l{https://doc.qt.io/qt-6/qnativeinterface-qandroidapplication.html#hideSplashScreen}
{QNativeInterface::QAndroidApplication::hideSplashScreen()} is
called, select the \uicontrol {Sticky splash screen} check box.
In \uicontrol {Image show mode}, select whether to center the splash screen
on the device display or scale it to fill the display.
Set a background color in \uicontrol {Background color}.
Select the images with the highest resolution as the
\uicontrol {Master image}, \uicontrol {Portrait master image},
and \uicontrol {Landscape master image}.
Select \uicontrol {Clear All} to reset all settings or remove all images.
\section2 Setting Permissions
Starting from Android 6.0 (API 23), applications have to request permissions
at runtime (see \l{QtAndroidPrivate::requestPermission()}). For
lower Android API levels, users have to grant the permissions when they
install the application. Android OS then grants the application access to the
appropriate data and features.
\image qtcreator-android-manifest-editor-permissions.webp {Permissions in Android Manifest Editor}
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
\c {android.permission.WRITE_EXTERNAL_STORAGE} for \l{Qt Core} or
\c {android.permission.ACCESS_BACKGROUND_LOCATION} for \l{Qt Positioning}.
To add a permission, select it from the list, and then click \uicontrol Add.
*/
View Git Blame Copy Permalink