1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
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
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
|
/****************************************************************************
**
** 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{QtAndroid::requestPermissionsSync()} or
\l{QtAndroid::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.
*/
|
