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
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page deployment.html
\title Deploying Qt Applications
Deploying an Qt application does not require any C++
programming. All you need to do is to build Qt and your
application in release mode, following the procedures described in
this documentation. We will demonstrate the procedures in terms of
deploying the \l {tools/plugandpaint}{Plug & Paint} application
that is provided in Qt's examples directory.
\section1 Static vs. Shared Libraries
There are two ways of deploying an application:
\list
\li Static Linking
\li Shared Libraries (Frameworks on Mac)
\endlist
Static linking results in a stand-alone executable. The advantage
is that you will only have a few files to deploy. The
disadvantages are that the executables are large and with no
flexibility (i.e a new version of the application, or of Qt, will
require that the deployment process is repeated), and that you
cannot deploy plugins.
To deploy plugin-based applications, you can use the shared
library approach. Shared libraries also provide smaller, more
flexible executables. For example, using the shared library
approach, the user is able to independently upgrade the Qt library
used by the application.
Another reason why you might want to use the shared library
approach, is if you want to use the same Qt libraries for a family
of applications. In fact, if you download the binary installation
of Qt, you get Qt as a shared library.
The disadvantage with the shared library approach is that you
will get more files to deploy. For more information, see
\l{Creating Shared Libraries}.
\section1 Deploying Qt's Libraries
\table
\header
\li {4,1} Qt Libraries
\row
\li \l{Qt Core}{QtCore}
\li \l{Qt Network}{QtNetwork}
\li \l{Qt GUI}{QtGui}
\li \l{Qt SQL}{QtSql}
\row
\li \l{Qt Test}{QtTest}
\li \l{Qt Widgets}{QtWidgets}
\li \l{Qt QML}{QtQml}
\li \l{Qt Quick}{QtQuick}
\row
\li \l{Qt Multimedia}{QtMultimedia}
\li \l{Qt WebKit}{QtWebKit}
\li \l{Qt WebKit Widgets}{QtWebKitWidgets}
\li \l{Qt XML}{QtXml}
\row
\li \l{Qt XML Patterns}{QtXmlPatterns}
\li \l{Qt SVG}{QtSvg}
\li \l{Qt Concurrent}{QtConcurrent}
\li \l{Qt Print Support}{QtPrintSupport}
\row
\li \l{Qt D-Bus}{QtDBus}
\li \l{Qt OpenGL}{QtOpenGL}
\li \l{ActiveQt}{QtActiveQt}
\li \l{Qt Graphical Effects}{QtGraphicalEffects}
\row
\li \l{Qt Script}{QtScript}
\li \l{Qt Quick 1}{QtDeclarative}
\li \l{Qt Image Formats}{QtImageFormats}
\endtable
Qt is not a system library, so it must be redistributed with your
application. The minimum is to redistribute the run-time
of the libraries used by the application. However, with static linking,
the Qt run-times can be compiled into the executable.
In general, you should deploy all plugins that your Qt build uses,
excluding those that you have identified as unnecessary for your
application and its users.
For instance, you may need to deploy plugins for JPEG support and
SQL drivers, but you should also deploy plugins that your users may
require, including those for accessibility.
For more information about plugins, see \l{How to Create Qt Plugins}.
While deploying an application using the shared library approach,
you must ensure that the Qt libraries use the correct path to
find the Qt plugins, documentation, translation, and so on. To do this, you
can use a \c qt.conf file. For more information, see \l {Using
qt.conf}.
Depending on configuration, compiler-specific libraries must be
redistributed as well. For more information, see the
platform-specific application dependencies for
\l{Qt for Linux/X11 - Deployment#Application Dependencies}{X11},
\l{Qt for Windows - Deployment#Application Dependencies}{Windows},
and \l{Qt for OS X}{OS X}.
\section1 Licensing
Some of Qt's libraries are based on third party libraries that are
not licensed using the same dual-license model as Qt. As a result,
care must be taken when deploying applications that use these
libraries, particularly when the application is statically linked
to them.
The following table summarizes a few issues that
you should be aware of.
\table
\header \li Qt Library \li Dependency
\li Licensing Issue
\row \li \l{QtHelp} \li CLucene
\li The version of clucene distributed with Qt is licensed
under the GNU LGPL version 2.1 or later. This has implications for
developers of closed source applications. Please see the
\l{Qt Help#License Information}{Qt Help} documentation for more information.
\row \li \l{QtNetwork} \li OpenSSL
\li Some configurations of QtNetwork use OpenSSL at run-time. Deployment
of OpenSSL libraries is subject to both licensing and export restrictions.
More information can be found in the \l{Secure Sockets Layer (SSL) Classes}
documentation.
\row \li \l{QtWebKit} \li WebKit
\li WebKit is licensed under the GNU LGPL version 2 or later.
This has implications for developers of closed source applications.
Please see the \l{Qt WebKit Widgets#License Information}{Qt WebKit Widgets}
documentation for more information.
\endtable
\section1 Platform-Specific Notes
The procedure of deploying Qt applications is different for the
various platforms:
\list
\li \l{Qt for Linux/X11 - Deployment}{Qt for X11 Platforms}
\li \l{Qt for Windows - Deployment}{Qt for Windows}
\li \l{Qt for OS X#Deploying Applications on OS X}{Qt for OS X}
\li \l{Deploying an Application on Android}{Qt for Android}
\endlist
\sa {Deploying Translations}
*/
/*!
\page deployment-android.html
\contentspage Deploying Qt Applications
\title Deploying an Application on Android
This article gives a technical description of the steps required to take
any given Qt application and deploy it to an Android device (or market place).
It is recommended that you use the \l {androiddeployqt}{androiddeployqt deployment tool} or
Qt Creator to automate this work rather than perform the steps manually. The following
information will give you a technical insight into the structure of the resulting Android
application which is not normally required just to write an application.
\tableofcontents
\section1 The APK Package
Applications on Android are packaged in a specially structured type of ZIP file called \c APK.
When you build a Qt application using \c qmake and \c make, the result will be a binary file
which is built with the correct compiler and flags to be usable on an Android device with the
target architecture.
In order to turn this into a runnable application, it has to be put into a special directory
structure with some other files and packaged into an APK package.
\section1 Package Template
A template for the other sources of an APK package is contained in \c{$QTDIR/src/android/java}.
The first step of making an APK is to copy these files into an empty directory. In this
guide, we'll refer to this build directory as \c{$BUILD_TARGET}.
We also need to make sure the application binary is copied into the package. This can be
achieved by using the following command after running qmake on your application's project file:
\code
make install INSTALL_ROOT=$BUILD_TARGET
\endcode
It will copy the application binary and any other installation requirements into the packaging
directory.
The packaging directory will now consist of the following parts:
\section2 AndroidManifest.xml
The \c{AndroidManifest.xml} file gives detailed meta-information about your application. This
information is used for several things. It is used by the target device to decide which features
to enable, the default orientation of the application, and so on. In addition, it's used by the
market place for information on the version code, device support, package name, and lots more.
For more information about general capabilities of and requirements for the
\c{AndroidManifest.xml} file, please refer to the
\l{http://developer.android.com/guide/topics/manifest/manifest-intro.html}{Android documentation on this topic}.
There are some special variables recognized by Qt which can be placed inside the manifest:
\list
\li \c{android.app.use_local_qt_libs}: If this is set to \c 1, Qt libraries are expected to be
found on the target device. If it is \c 0, then libraries must be requested from the \b Ministro
service.
\li \c{android.app.bundle_local_qt_libs}: If set to \c 1, the Qt libraries are expected to be
bundled as part of the \c APK. If set to \c 0, they are expected to be found in the
\c{/data/local/tmp/qt} folder on the target device.
\note If \c{use_local_qt_libs} is 0, then this variable has no effect, since libraries
are then requested through Ministro instead.
\endlist
Other variables in the manifest refer to resources, and more information about these can
be found in the \l{Resources}{documentation for the resources} below.
\section2 Java Code
Under \c{$BUILD_TARGET/src} are the files comprising the Java code of the Android application.
The regular Android application launcher is a Java process, so Qt applications have a
Java-based entry point. The code in here will load the required Qt libraries, based on the
meta-information given in other files in the template. The code supports all the
three deployment mechanisms which are supported in Qt Creator and \c{androiddeployqt}: \e Bundled,
\e Ministro and \e Debug.
After loading the libraries, the Java code will call into the application's native \c{main()}
function on a new thread and the application will launch. At this point, the Java code in
the template is used to delegate events from Android into Qt.
One thing to note about the files in this directory is that they can contain code specific
to certain Android versions. Based on the minimum required Android API level of your
application it might be necessary to remove some of this code. This is done automatically
by \c androiddeployqt and Qt Creator during packaging.
For example, lets say the code contains the following:
\code
//@ANDROID-12
@Override
public boolean dispatchGenericMotionEvent(MotionEvent ev)
{
if (QtApplication.m_delegateObject != null && QtApplication.dispatchGenericMotionEvent != null)
return (Boolean) QtApplication.invokeDelegateMethod(QtApplication.dispatchGenericMotionEvent, ev);
else
return super.dispatchGenericMotionEvent(ev);
}
//@ANDROID-12
\endcode
If your minimum Android API level is 11 or lower, then the code should be removed before
building, since it's not a supported API on Android API level 11. However, if your minimum API
level is 12 or higher, it should be left in.
\section2 Resources
Under the \c{res/} folder in the \c{$BUILD_TARGET} are Android resources that can be accessed
from the \c{AndroidManifest.xml} and Java code of your application. A typical example of
resources which should be placed here are the icon files used by the application launcher to
represent your application.
In Qt, some translations used for the Ministro service and some files with meta-information
are in the default resources of the application.
\section3 res/values/libs.xml
One of the files containing meta information about the deployment of the application is
\c{libs.xml}. It consists of the following values:
\list
\li \c{qt_sources}: The URL of one or more Ministro repositories that contain the
necessary Qt libraries. This is used when the Ministro deployment mechanism is active. Read the
\l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro documentation} for more
information about such repositories.
\li \c{repository}: The Ministro repository to use at the given URL. This is used when the
Ministro deployment mechanism is active.
\li \c{bundled_libs}: Libraries in the APK's library folder which should be loaded on start-up.
Library names should be specified without the \c lib prefix and \c{.so} suffix.
\li \c{qt_libs}: Qt libraries which should be loaded on start-up. When bundled deployment is
used, these are expected to be found inside the \c{APK}'s library folder. When Ministro
deployment is in use, they are requested from the Ministro service on the device. And when
debugging deployment is in use, they are loaded from the \c{/data/local/tmp/qt} directory on the
target device.
\li \c{bundled_in_lib}: List of plugins which are bundled in the \c{APK}'s library folder. This
is only used when the bundling deployment mechanism is active. Qt's plugin system requires
plugins to be placed in a special directory structure which contains information about the
plugin category. The library folder in the APK does not support such a directory
structure, so the bundled_in_lib array contains the information lost when the directory
structure is flattened. Each item is a pair of paths, separated by a colon. The first of the
pair is the file name of the file bundled inside the \c{APK}'s library folder. The second of the
pair is the original path of the file, relative to the Qt installation.
\li \c{bundled_in_assets}: List of other types of Qt files which are bundled inside the
\c{APK}'s asset folder. This value is only used when the bundling deployment mechanism is active. The
format of the items is the same as for the \c{bundled_in_lib array}. The difference is that the
first of the pairs refers to the path of a file inside the \c{assets} directory of the
application instead of the library directory. This array is typically used for bundling QML
imports, which also require a special directory structure to be used inside Qt.
\endlist
\section3 res/values/strings.xml
The \c{strings.xml} file contains some strings used by the \c{AndroidManifest.xml} and by the
deployment mechanisms, as well as some strings used when loading the Ministro service.
In particular, the application name and the name of the application binary can be specified
here. There are also strings that contain additional libraries that should be loaded and
\c JAR files which should be included in the class path. The latter is only used for deployment
with Ministro or debug deployment.
\section2 Libraries
Under \c libs in the package directory, it's possible to place libraries that should be included
in the application bundle. \c JAR libraries should be placed directly under \c{libs/}, while
shared libraries should be put in a subdirectory suitably named after the target architecture
of the libraries.
For deployment that bundles Qt in the \c APK, the Qt \c JAR files that are suffixed with
\c{"bundled"} should be put into the libs directory. It is also required that the necessary
shared libraries and plugins are placed in the appropriate subdirectory of libs.
\section1 Building the Android Application Package
Once all the pieces are in place, a few steps are required to build the application package.
First, a build script needs to be generated. This is done using the \c android tool which is
part of the Google Android SDK.
Example:
\code
% android update project --path $BUILD_TARGET --target android-9 --name QtApp
\endcode
This example will create build files in \c{$BUILD_TARGET} for an \c APK named \c QtApp. The Java
code will be compiled against the \c{android-9} platform.
The project can then be built using the ant tool. If a release package is built it can
be signed and aligned using \c jarsigner and \c zipalign.
\section1 androiddeployqt
Building an application package is complex, so Qt comes with a tool which handles the work for
you. The steps described in this document so far are handled automatically by the tool.
\section2 Required Steps Before Running androiddeployqt
Before running the tool, you need run \c qmake and \c make your project. Running \c qmake
creates the \c Makefile, and it will also generate a \c JSON file containing important settings
used by \c androiddeployqt.
You should then install the application binary (and any other requirements) into the library
folder of the \c APK. If \c{$BUILD_TARGET} is your build directory (the first time you do this,
the directory should be empty at this point), then you can install the binary with the following
command:
\code
% make install INSTALL_ROOT=$BUILD_TARGET
\endcode
\section2 Command Line Arguments
The only required command line argument when running the tool is \c{--output}. This should
be set to \c{$BUILD_TARGET}, that is: the build directory where you installed your application
binary.
Other command line arguments are optional but useful. Here's a quick overview. More information
is available by passing the \c{--help} argument to androiddeployqt.
\list
\li \c{--input <file name>}: This allows you to specify the \c JSON file generated by \c qmake.
By default, \c androiddeployqt will try to guess the file name based on the current working
directory.
\li \c{--deployment <mechanism>}: Specify this to pick a different deployment mechanism than the
default.
\li \c{--install}: Specify this to install the finished package on the target device or
emulator. Note that if a previous version of the package is already installed, it will be
uninstalled first, removing any data it might have stored locally.
\li \c{--device <ID>}: Specify the ID of the target device or emulator as reported by the \c adb
tool. If an ID is specified, it will be passed to all calls to \c adb. If it is unspecified, no
particular device or emulator will be requested by \c adb, causing it to pick a default instead.
\li \c{--android-platform <platform>}: The SDK platform used for building the Java code of the
application. By default, the latest available platform is used.
\li \c{--ant <path>}: Specify the path to the \c ant executable. If this is unspecified,
\c androiddeployqt will attempt to detect it on the \c PATH.
\li \c{--release}: Specify this to create a release package instead of a debug package. With no
other arguments, release packages are unsigned and cannot be installed to any device before
they have been signed by a private key.
\li \c{--sign <url> <alias>}: Sign the resulting package. Specifying this also implies
\c{--release}. The URL of the keystore file and the alias of the key have to be specified. In
addition, there are a number of options that can be specified which are passed through to the
\c jarsigner tool. Pass \c{--help} to \c androiddeployqt for more information about these.
\li \c{--jdk <path>}: Specify the path to the Java Development Kit. This is only required for
signing packages, as it is only used for finding the \c jarsigner tool. If it is unspecified,
then \c androiddeployqt will attempt to detect \c jarsigner, either using the \c{JAVA_HOME}
environment variable, or on the \c PATH.
\li \c{--verbose}: Specify this to output more information about what \c androiddeployqt is
doing.
\endlist
\section1 Dependencies Detection
Qt comes with a number of plugins which are loaded at run-time when they are needed. These
can handle anything from connecting to SQL databases to loading specific image formats.
Detecting plugin dependencies is impossible as the plugins are loaded at run-time, but
androiddeployqt tries to guess such dependencies based on the Qt dependencies
of your application. If the plugin has any Qt dependencies which are not also dependencies of
your application, it will not be included by default. For instance, in order to ensure that
the SVG image format plugin is included, you will need to add \c{QT += svg} to your \c .pro file
so that the \l{Qt SVG} module becomes a dependency of your application.
If you are wondering why a particular plugin is not included automatically, you can run androiddeployqt
with the \c --verbose option to get the list of missing dependencies for each excluded plugin. You
can achieve the same in Qt Creator by ticking the \gui{Verbose output} check box in the
\gui{Deployment configurations}. This is located in the \gui{Run} tab of your \gui{Projects}
settings.
It's also possible to manually specify the dependencies of your application. See the documentation
for the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable below.
\section1 Android-specific qmake Variables
Unless the project has special requirements such as third party libraries, it should be
possible to run \c androiddeployqt on it with no modifications and get a working Qt for Android
application as a result.
However, there are a set of \c qmake variables that can be used to tailor your package. At some
point during development, you will most likely want to look into these variables, as they will
e.g. allow you to set the name of your application as it appears in the application menu on
devices.
Here is a list of some variables that are particularly interesting when making Android
applications:
\list
\li \c{ANDROID_DEPLOYMENT_DEPENDENCIES}: By default, \c androiddeployqt will detect the
dependencies of your application. But since run-time usage of plugins cannot be detected, there
could be false positives, as your application will depend on any plugins that are \e potential
dependencies. If you want to minimize the size of your \c APK, it's possible to override the
automatic detection using the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} variable. This should contain
a list of all Qt files which need to be included, with paths relative to the Qt install root.
Note that only the Qt files specified here will be included. Failing to include the correct
files can result in crashes. It's also important to make sure the files are listed in the
correct loading order. This variable provides a way to override the automatic detection
entirely, so if a library is listed before its dependencies, it will fail to load on
some devices.
\li \c{ANDROID_PACKAGE_SOURCE_DIR}: This variable can be used to specify a directory where
additions and modifications can be made to the default Android package template. The
\c androiddeployqt tool will copy the application template from Qt into the build directory, and
then it will copy the contents of the \c{ANDROID_PACKAGE_SOURCE_DIR} on top of this, overwriting
any existing files. The update step where parts of the source files are modified automatically
to reflect your other settings is then run on the resulting merged package. If you, for
instance, want to make a custom \c{AndroidManifest.xml} for your application, then place this
directly into the folder specified in this variable. You can also add custom Java files in
\c{ANDROID_PACKAGE_SOURCE_DIR/src}.
\note When adding custom versions of the build files (like strings.xml, libs.xml,
AndroidManifest.xml, etc.) to your project, make sure you copy them from the package template,
which is located in \c{$QT/src/android/java}. You should never copy any files from the build
directory, as these files have been altered to match the current build settings.
\li \c{ANDROID_EXTRA_LIBS}: A list of external libraries that will be copied into your application's
library folder and loaded on start-up. This can be used, for instance, to enable OpenSSL
in your application. Simply set the paths to the required \c{libssl.so} and \c{libcrypto.so}
libraries here and OpenSSL should be enabled automatically.
\li \c{ANDROID_EXTRA_PLUGINS}: This variable can be used to specify different resources that your
project has to bundle but cannot be delivered through the assets system, such as qml plugins. When
using this variable, \c androiddeployqt will make sure everything is packaged and deployed properly.
\endlist
\section1 Deployment in Qt Creator
Qt Creator will run the \c androiddeployqt tool for you, and provides easy and intuitive user
interfaces to specify many of the options. For more information, see
\l{Qt Creator: Deploying Applications to Android Devices}{the Qt Creator documentation}.
*/
|