diff options
Diffstat (limited to 'doc/src/platforms/android/android-deploying-application.qdoc')
| -rw-r--r-- | doc/src/platforms/android/android-deploying-application.qdoc | 342 |
1 files changed, 342 insertions, 0 deletions
diff --git a/doc/src/platforms/android/android-deploying-application.qdoc b/doc/src/platforms/android/android-deploying-application.qdoc new file mode 100644 index 000000000..3503bc846 --- /dev/null +++ b/doc/src/platforms/android/android-deploying-application.qdoc @@ -0,0 +1,342 @@ +/**************************************************************************** +** +** 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-android.html + + \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}. +*/ |