| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 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. |
| ** $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. |
| |
| \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 |
| |
| Unless Qt is part of the system libraries 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}. |
| |
| Applications using \l{Qt QML} also need to ship the |
| \l{All QML Modules}{QML modules} they use. |
| |
| 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 macOS}{\macos}. |
| |
| \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. |
| For more information, see \l{Third-Party Licenses Used in Qt}. |
| |
| Some configurations of QtNetwork use OpenSSL at run-time. Deployment |
| of OpenSSL libraries is subject to both licensing and export restrictions. |
| For more information, see \l{Secure Sockets Layer (SSL) Classes}. |
| |
| \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 macOS#Deploying Applications on macOS}{Qt for macOS} |
| \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 Qt Creator or the Makefile created by qmake to |
| create the application bundle. 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. |
| |
| All the steps described here are handled automatically by the build script and |
| the \l {androiddeployqt}{androiddeployqt deployment tool}, which are run by Qt Creator |
| for you. |
| |
| \note If you prefer building Android packages from the command line, you may use the "aab" |
| or "apk" build targets in the Makefile directly: |
| |
| \code |
| % make aab |
| \endcode |
| |
| or |
| |
| \code |
| % make apk |
| \endcode |
| |
| \tableofcontents |
| |
| \section1 The Application Bundle |
| |
| Applications on Android can be packaged in two ways: Either as Application Package (APK) |
| or Android App Bundle (AAB). Both are ZIP files which follow a predefined directory |
| structure. The difference between the two is that APK files can be downloaded to |
| and executed on a device. AAB, on the other hand, is intended to be interpreted by the |
| Google Play store and is used to generate APK files. |
| |
| For testing the application locally, the APK format is the most appropriate, as this can |
| be uploaded directly to the device and run. For distribution to the Google Play store, it is |
| recommended that you use AAB instead, which has a similar layout. The added convenience |
| of AAB is that you can include all target ABIs in the same bundle without increasing the |
| size of the actual package downloaded by your users. When using AAB, the Google Play store |
| generates optimized APK packages for the devices issuing the download request and |
| automatically sign them with your publisher key. |
| |
| Read \l{https://developer.android.com/guide/app-bundle}{the Android documentation} if you |
| want to know more about the AAB format. |
| |
| In either case, the files must be copied into a special directory structure first, before |
| bundling them in a single ZIP file |
| |
| This contains one or more binary \c .so files with the code for your application, as |
| well as any dependencies, such as Qt's libraries and plugins. In addition, it includes |
| \c .jar files containing compiled Java code, assets, resources, and some \c .xml |
| files that are used to describe the contents of the bundle. |
| |
| \section1 Package Template |
| |
| A template for the other sources of an APK package is contained in \c{$QTDIR/src/android/templates}. |
| The first step of making a package manually 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}. |
| |
| The default manifest contains some special parameters used by Qt to set up the application for |
| running. When you are creating your own Android manifest, you must make sure that it contains these |
| parameters. The \c androiddeployqt tool replaces content in the template with the correct |
| values. |
| |
| \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. |
| |
| 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-21 |
| @Override |
| public void onActivityReenter(int resultCode, Intent data) |
| { |
| // Do something |
| return super.onActivityReenter(resultCode, data); |
| } |
| //@ANDROID-21 |
| \endcode |
| |
| If your minimum Android API level is 20 or lower, the code is removed before |
| building, since it's not a supported API on Android API level 20. However, if your minimum API |
| level is 21 or higher, it is 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{bundled_libs}: Libraries in the package'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. |
| \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 ABI |
| of the libraries. |
| |
| \section1 Building the Android Application Package |
| |
| The project can be built using the gradle tool. If an APK intended for release is built, then |
| it should 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. |
| |
| In addition, there are Makefile build targets for building the package from the |
| command line. There is also automated support in Qt Creator for generating both \c APK and \c AAB |
| packages. |
| |
| \section2 Required Steps Before Running androiddeployqt |
| |
| Before running the tool manually, you need to run \c qmake and \c make on 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 bundle. 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{--aab}: Generate an Android Application Bundle, rather than an APK. Note that this |
| invalidates some of the other arguments, such as --install. |
| \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{--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}. |
| */ |