<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- deployment.qdoc -->
<title>Deploying an Application on Android | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td >Deploying an Application on Android</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<p class="naviNextPrevious headerNavi">
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#the-apk-package">The APK Package</a></li>
<li class="level1"><a href="#package-template">Package Template</a></li>
<li class="level2"><a href="#androidmanifest-xml">AndroidManifest.xml</a></li>
<li class="level2"><a href="#java-code">Java Code</a></li>
<li class="level2"><a href="#resources">Resources</a></li>
<li class="level2"><a href="#libraries">Libraries</a></li>
<li class="level1"><a href="#building-the-android-application-package">Building the Android Application Package</a></li>
<li class="level1"><a href="#androiddeployqt">androiddeployqt</a></li>
<li class="level2"><a href="#required-steps-before-running-androiddeployqt">Required Steps Before Running androiddeployqt</a></li>
<li class="level2"><a href="#command-line-arguments">Command Line Arguments</a></li>
<li class="level1"><a href="#dependencies-detection">Dependencies Detection</a></li>
<li class="level1"><a href="#android-specific-qmake-variables">Android-specific qmake Variables</a></li>
<li class="level1"><a href="#deployment-in-qt-creator">Deployment in Qt Creator</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Deploying an Application on Android</h1>
<span class="subtitle"></span>
<!-- $$$deployment-android.html-description -->
<div class="descr"> <a name="details"></a>
<p>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).</p>
<p>It is recommended that you use the <a href="deployment-android.html#androiddeployqt">androiddeployqt deployment tool</a> 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.</p>
<a name="the-apk-package"></a>
<h2 id="the-apk-package">The APK Package</h2>
<p>Applications on Android are packaged in a specially structured type of ZIP file called <code>APK</code>. When you build a Qt application using <code>qmake</code> and <code>make</code>, 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.</p>
<p>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.</p>
<a name="package-template"></a>
<h2 id="package-template">Package Template</h2>
<p>A template for the other sources of an APK package is contained in <code>$QTDIR/src/android/java</code>. 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 <code>$BUILD_TARGET</code>.</p>
<p>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:</p>
<pre class="cpp">
make install INSTALL_ROOT<span class="operator">=</span>$BUILD_TARGET
</pre>
<p>It will copy the application binary and any other installation requirements into the packaging directory.</p>
<p>The packaging directory will now consist of the following parts:</p>
<a name="androidmanifest-xml"></a>
<h3 >AndroidManifest.xml</h3>
<p>The <code>AndroidManifest.xml</code> 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.</p>
<p>For more information about general capabilities of and requirements for the <code>AndroidManifest.xml</code> file, please refer to the <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">Android documentation on this topic</a>.</p>
<p>There are some special variables recognized by Qt which can be placed inside the manifest:</p>
<ul>
<li><code>android.app.use_local_qt_libs</code>: If this is set to <code>1</code>, Qt libraries are expected to be found on the target device. If it is <code>0</code>, then libraries must be requested from the <b>Ministro</b> service.</li>
<li><code>android.app.bundle_local_qt_libs</code>: If set to <code>1</code>, the Qt libraries are expected to be bundled as part of the <code>APK</code>. If set to <code>0</code>, they are expected to be found in the <code>/data/local/tmp/qt</code> folder on the target device.<p><b>Note: </b>If <code>use_local_qt_libs</code> is 0, then this variable has no effect, since libraries are then requested through Ministro instead.</p></li>
</ul>
<p>Other variables in the manifest refer to resources, and more information about these can be found in the <a href="deployment-android.html#resources">documentation for the resources</a> below.</p>
<a name="java-code"></a>
<h3 >Java Code</h3>
<p>Under <code>$BUILD_TARGET/src</code> 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 <code>androiddeployqt</code>: <i>Bundled</i>, <i>Ministro</i> and <i>Debug</i>.</p>
<p>After loading the libraries, the Java code will call into the application's native <code>main()</code> 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.</p>
<p>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 <code>androiddeployqt</code> and Qt Creator during packaging.</p>
<p>For example, lets say the code contains the following:</p>
<pre class="cpp">
<span class="comment">//@ANDROID-21</span>
@Override
<span class="keyword">public</span> <span class="type">void</span> onActivityReenter(<span class="type">int</span> resultCode<span class="operator">,</span> Intent data)
{
<span class="comment">// Do something</span>
<span class="keyword">return</span> super<span class="operator">.</span>onActivityReenter(resultCode<span class="operator">,</span> data);
}
<span class="comment">//@ANDROID-21</span>
</pre>
<p>If your minimum Android API level is 20 or lower, then the code should be 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 should be left in.</p>
<a name="resources"></a>
<h3 >Resources</h3>
<p>Under the <code>res/</code> folder in the <code>$BUILD_TARGET</code> are Android resources that can be accessed from the <code>AndroidManifest.xml</code> 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.</p>
<p>In Qt, some translations used for the Ministro service and some files with meta-information are in the default resources of the application.</p>
<a name="res-values-libs-xml"></a>
<h4 >res/values/libs.xml</h4>
<p>One of the files containing meta information about the deployment of the application is <code>libs.xml</code>. It consists of the following values:</p>
<ul>
<li><code>qt_sources</code>: 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 <a href="http://necessitas.kde.org/necessitas/ministro.php">Ministro documentation</a> for more information about such repositories.</li>
<li><code>repository</code>: The Ministro repository to use at the given URL. This is used when the Ministro deployment mechanism is active.</li>
<li><code>bundled_libs</code>: Libraries in the APK's library folder which should be loaded on start-up. Library names should be specified without the <code>lib</code> prefix and <code>.so</code> suffix.</li>
<li><code>qt_libs</code>: Qt libraries which should be loaded on start-up. When bundled deployment is used, these are expected to be found inside the <code>APK</code>'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 <code>/data/local/tmp/qt</code> directory on the target device.</li>
<li><code>bundled_in_lib</code>: List of plugins which are bundled in the <code>APK</code>'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 <code>APK</code>'s library folder. The second of the pair is the original path of the file, relative to the Qt installation.</li>
<li><code>bundled_in_assets</code>: List of other types of Qt files which are bundled inside the <code>APK</code>'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 <code>bundled_in_lib array</code>. The difference is that the first of the pairs refers to the path of a file inside the <code>assets</code> 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.</li>
</ul>
<a name="res-values-strings-xml"></a>
<h4 >res/values/strings.xml</h4>
<p>The <code>strings.xml</code> file contains some strings used by the <code>AndroidManifest.xml</code> and by the deployment mechanisms, as well as some strings used when loading the Ministro service.</p>
<p>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 <code>JAR</code> files which should be included in the class path. The latter is only used for deployment with Ministro or debug deployment.</p>
<a name="libraries"></a>
<h3 >Libraries</h3>
<p>Under <code>libs</code> in the package directory, it's possible to place libraries that should be included in the application bundle. <code>JAR</code> libraries should be placed directly under <code>libs/</code>, while shared libraries should be put in a subdirectory suitably named after the target architecture of the libraries.</p>
<p>For deployment that bundles Qt in the <code>APK</code>, the Qt <code>JAR</code> files that are suffixed with <code>"bundled"</code> 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.</p>
<a name="building-the-android-application-package"></a>
<h2 id="building-the-android-application-package">Building the Android Application Package</h2>
<p>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 <code>android</code> tool which is part of the Google Android SDK.</p>
<p>Example:</p>
<pre class="cpp">
<span class="operator">%</span> android update project <span class="operator">-</span><span class="operator">-</span>path $BUILD_TARGET <span class="operator">-</span><span class="operator">-</span>target android<span class="operator">-</span><span class="number">16</span> <span class="operator">-</span><span class="operator">-</span>name <span class="type">QtApp</span>
</pre>
<p>This example will create build files in <code>$BUILD_TARGET</code> for an <code>APK</code> named <code>QtApp</code>. The Java code will be compiled against the <code>android-16</code> platform.</p>
<p>The project can then be built using the ant tool. If a release package is built it can be signed and aligned using <code>jarsigner</code> and <code>zipalign</code>.</p>
<a name="androiddeployqt"></a>
<h2 id="androiddeployqt">androiddeployqt</h2>
<p>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.</p>
<a name="required-steps-before-running-androiddeployqt"></a>
<h3 >Required Steps Before Running androiddeployqt</h3>
<p>Before running the tool, you need run <code>qmake</code> and <code>make</code> your project. Running <code>qmake</code> creates the <code>Makefile</code>, and it will also generate a <code>JSON</code> file containing important settings used by <code>androiddeployqt</code>.</p>
<p>You should then install the application binary (and any other requirements) into the library folder of the <code>APK</code>. If <code>$BUILD_TARGET</code> 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:</p>
<pre class="cpp">
<span class="operator">%</span> make install INSTALL_ROOT<span class="operator">=</span>$BUILD_TARGET
</pre>
<a name="command-line-arguments"></a>
<h3 >Command Line Arguments</h3>
<p>The only required command line argument when running the tool is <code>--output</code>. This should be set to <code>$BUILD_TARGET</code>, that is: the build directory where you installed your application binary.</p>
<p>Other command line arguments are optional but useful. Here's a quick overview. More information is available by passing the <code>--help</code> argument to androiddeployqt.</p>
<ul>
<li><code>--input <file name></code>: This allows you to specify the <code>JSON</code> file generated by <code>qmake</code>. By default, <code>androiddeployqt</code> will try to guess the file name based on the current working directory.</li>
<li><code>--deployment <mechanism></code>: Specify this to pick a different deployment mechanism than the default.</li>
<li><code>--install</code>: 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>
<li><code>--device <ID></code>: Specify the ID of the target device or emulator as reported by the <code>adb</code> tool. If an ID is specified, it will be passed to all calls to <code>adb</code>. If it is unspecified, no particular device or emulator will be requested by <code>adb</code>, causing it to pick a default instead.</li>
<li><code>--android-platform <platform></code>: The SDK platform used for building the Java code of the application. By default, the latest available platform is used.</li>
<li><code>--ant <path></code>: Specify the path to the <code>ant</code> executable. If this is unspecified, <code>androiddeployqt</code> will attempt to detect it on the <code>PATH</code>.</li>
<li><code>--release</code>: 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>
<li><code>--sign <url> <alias></code>: Sign the resulting package. Specifying this also implies <code>--release</code>. 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 <code>jarsigner</code> tool. Pass <code>--help</code> to <code>androiddeployqt</code> for more information about these.</li>
<li><code>--jdk <path></code>: Specify the path to the Java Development Kit. This is only required for signing packages, as it is only used for finding the <code>jarsigner</code> tool. If it is unspecified, then <code>androiddeployqt</code> will attempt to detect <code>jarsigner</code>, either using the <code>JAVA_HOME</code> environment variable, or on the <code>PATH</code>.</li>
<li><code>--verbose</code>: Specify this to output more information about what <code>androiddeployqt</code> is doing.</li>
</ul>
<a name="dependencies-detection"></a>
<h2 id="dependencies-detection">Dependencies Detection</h2>
<p>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 <code>QT += svg</code> to your <code>.pro</code> file so that the Qt SVG module becomes a dependency of your application.</p>
<p>If you are wondering why a particular plugin is not included automatically, you can run androiddeployqt with the <code>--verbose</code> option to get the list of missing dependencies for each excluded plugin. You can achieve the same in Qt Creator by ticking the <b>Verbose output</b> check box in the <b>Deployment configurations</b>. This is located in the <b>Run</b> tab of your <b>Projects</b> settings.</p>
<p>It's also possible to manually specify the dependencies of your application. See the documentation for the <code>ANDROID_DEPLOYMENT_DEPENDENCIES</code> qmake variable below.</p>
<a name="android-specific-qmake-variables"></a>
<h2 id="android-specific-qmake-variables">Android-specific qmake Variables</h2>
<p>Unless the project has special requirements such as third party libraries, it should be possible to run <code>androiddeployqt</code> on it with no modifications and get a working Qt for Android application as a result.</p>
<p>However, there are a set of <code>qmake</code> 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.</p>
<p>Here is a list of some variables that are particularly interesting when making Android applications:</p>
<ul>
<li><code>ANDROID_DEPLOYMENT_DEPENDENCIES</code>: By default, <code>androiddeployqt</code> 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 <i>potential</i> dependencies. If you want to minimize the size of your <code>APK</code>, it's possible to override the automatic detection using the <code>ANDROID_DEPLOYMENT_DEPENDENCIES</code> 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>
<li><code>ANDROID_PACKAGE_SOURCE_DIR</code>: This variable can be used to specify a directory where additions and modifications can be made to the default Android package template. The <code>androiddeployqt</code> tool will copy the application template from Qt into the build directory, and then it will copy the contents of the <code>ANDROID_PACKAGE_SOURCE_DIR</code> 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 <code>AndroidManifest.xml</code> for your application, then place this directly into the folder specified in this variable. You can also add custom Java files in <code>ANDROID_PACKAGE_SOURCE_DIR/src</code>.<p><b>Note: </b>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 <code>$QT/src/android/java</code>. You should never copy any files from the build directory, as these files have been altered to match the current build settings.</p></li>
<li><code>ANDROID_EXTRA_LIBS</code>: 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 <code>libssl.so</code> and <code>libcrypto.so</code> libraries here and OpenSSL should be enabled automatically.</li>
<li><code>ANDROID_EXTRA_PLUGINS</code>: 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, <code>androiddeployqt</code> will make sure everything is packaged and deployed properly.</li>
</ul>
<a name="deployment-in-qt-creator"></a>
<h2 id="deployment-in-qt-creator">Deployment in Qt Creator</h2>
<p>Qt Creator will run the <code>androiddeployqt</code> tool for you, and provides easy and intuitive user interfaces to specify many of the options. For more information, see <a href="http://doc.qt.io/qtcreator/creator-deploying-android.html">the Qt Creator documentation</a>.</p>
</div>
<!-- @@@deployment-android.html -->
<p class="naviNextPrevious footerNavi">
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
