Deploying an Application on Android

This article describes the technical steps required to deploy a Qt application to an Android device.

Android Packaging Options

You can package code on Android in three ways: either as an Application Package (APK), an Android App Bundle (AAB), or an Android Archive (AAR). Each is a specific type of ZIP format that follow a predefined directory structure. The differences between these formats are:

• APK files can be deployed and executed on a device.
• An AAB is intended to be interpreted by the Google Play store and is used to generate APK files for different device architectures and form factors.
• An AAR fundamentally differs from the APK and AAB formats in that it is an Android library. You can use it as a dependency for an Android app module, but you cannot run it by itself.

Android Application Bundle

For testing the application locally, the APK format is appropriate, as this can be installed and run directly on the device. For distribution to the Google Play store, it is recommended to 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 signs them with your publisher key. For more information, see Publishing to Google Play.

For more information on the AAB format, see the Android App Bundles.

In either case, the application bundle is generated from a specific directory structure that contains the shared libraries of your project and Qt's dependencies needed by your application. In addition, any assets, resources, jar files or project Java code is compiled and included.

Generating the Application Bundle

It is recommended to use Qt Creator to deploy Qt for Android apps. Otherwise, the same can be done through the command line with the help of CMake or qmake. For more information, see Building Qt for Android Projects from Command Line.

The packaging and deployment process is handled by CMake or qmake which, under the hood, use the androiddeployqt tool to manage the specifics of building and deploying an Android app. Qt Creator also uses the same tool.

Extending Qt with Android Facilities

By default, Qt for Android does most of the heavy lifting to get an Android app up and running, having the most useful APIs available directly from Qt, or using QJniObject to invoke not readily available APIs. The same is valid for CMake, which handles the various build and deployment cases. However, in some other cases, it might be required to have the full power of native Android facilities, such as writing Java/kotlin code or using Android resource management. Qt allows that by allowing the user to extend the set of templates.

The default templates used by Qt are found under the Qt for Android install path, for example, under ~/Qt/<version>/android_<abi>/src/android/templates for Unix. To use those templates, it's possible to have Qt Creator copy them to your project, see Qt Creator: Editing Manifest Files. Or you can manually copy them over to your project source under a android sub-directory. Then make sure to define the following property in your CMakeLists.txt:

 set_property(TARGET target_name PROPERTY QT_ANDROID_PACKAGE_SOURCE_DIR
           "${CMAKE_CURRENT_SOURCE_DIR}/android")

Or for qmake in your pro file:

 android: ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android

The build process copies the templates to the build directory <build_path>/android-build from your project or from the default templates if the project didn't set QT_ANDROID_PACKAGE_SOURCE_DIR. After that, the directory <build_path>/android-build acts as the packaging directory. The application bundle is created from there using Gradle.

Now, let's go through the different parts that the user can work with after extending the default templates.

AndroidManifest.xml

The AndroidManifest.xml file gives detailed meta-information about your application. This information is used to customize your application bundle, and it's used by the device to decide which features to enable, such as the default orientation of the application. In addition, it's used by the Google Play Store for information on the version code, device support, package name, and lots more. The Android Manifest is also used to define Android Services and custom Android Activities.

For more information about the AndroidManifest.xml, see Android Manifest file documentation, and Qt Creator's page for Qt Creator: Editing Manifest Files.

Gradle Files

Gradle is used to build Android packages. Qt includes two sets of Gradle related files:

• Gradle wrapper, which is used to download a specific version of Gradle itself, and the build scripts that are used to invoke the Gralde build. These files come with Qt under for example ~/Qt/<version>/android_<abi>/src/3rdparty/gradle.

  Note: Usually, using the same Gradle version that Qt comes with is recommended. However, if you wish to use a different Gradle version, you can modify the Gradle wrapper gradle-wrapper.properties and set it to the Gradle version you want to use.

• The Gradle configuration file build.gradle, which is under the Android Templates. This file is required by Gradle and can be used to customize the build. It can be used to set the build target or minimum API or add library dependencies. It can also be used to set the Android Gradle plugin, which is a required Gradle dependency for building Android apps. An example of this is:

   buildscript {
       ...
       dependencies {
           classpath 'com.android.tools.build:gradle:8.6.0'
       }
   }
  

  For more information, see Android: Build Configuration Files.

Java/Kotlin Code

To include any Java/Kotlin code to target some APIs that Qt doesn't cover or for some other reason, place any code under the path <QT_ANDROID_PACKAGE_SOURCE_DIR>/src/. For example, you can call Java methods from within Qt code. For an example, see Qt Android Notifier Example.

Resources

Android allows the addition of resource files such as icons, images, strings, colors, and so on. Those resources can be referenced directly from Java/Kotlin code or the manifest file. Any such files can be added to your project under <QT_ANDROID_PACKAGE_SOURCE_DIR>/res/. For example, app icons can be added under res/drawable/icon.png.

For more information, see Android: App resources overview.

Qt Internal Resources

By default, Qt packages a few resources that are needed for the apps to run properly. For example, on Unix, these resources are found under ~/Qt/<version>/android_<abi>/src/android/templates/res.

strings.xml

This file can be found at res/values/strings.xml. This file contains strings the Qt library uses to reference message translations for various languages.

libs.xml

This file can be found at res/values/libs.xml. It is used purely to manage deployment information of the Qt libraries, and it's not recommended to be manually modified.

Android Assets

For more information on managing Android assets, see Adding resources.

Android Libraries

For more information on using third-party libraries with your Qt project, see Including a Library to an Android Project.