The androiddeployqt Tool | Qt Core 6.4.1

- Qt 6.4
- Qt Core
- The androiddeployqt Tool
- Qt 6.4.1 Reference Documentation

# The androiddeployqt Tool

Building an application package is complex, so Qt comes with a tool which handles the work for you. The steps described in Deploying an Application on Android are handled by the androiddeployqt tool.

## Prerequisites Before Running androiddeployqt

Before running the tool manually, you need to run `qmake` or `CMake` on your project to generate `Makefiles` and a `JSON` file (i.e. `android-project-deployment-settings.json`) containing important settings used by `androiddeployqt`.

Note: It is not recommended to modify the androiddeployqt JSON file.

To prepare the build for androiddeployqt, it is recommended to build your project in a separate directory. Run the following commands:

     mkdir build-project
     cd build-project

Followed by:

For qmake:

     qmake ../project/project.pro
     make -j$(nproc)
     make -j$(nproc) apk_install_target

For CMake:

     cmake --build

## Command Line Arguments

The only required command line argument when running the tool is `--output`. Other command line arguments are optional but useful. Here's a quick overview. More information is available by passing the `--help` argument to androiddeployqt.

Argument | Brief Description
--- | ---
`--output <destination>` | Specifies the destination of the final package. Set this to `$ANDROID_BUILD_DIR`, that is the build directory where you installed your application binaries.
`--input <file name>` | This allows you to specify the generated `JSON` settings file. `androiddeployqt` will try to guess the file name based on the current working directory.
`--aab` | Generate an Android Application Bundle, rather than an APK. Note that this invalidates some of the other arguments, such as `--install`.
- `--deployment <mechanism>` | Specify this to pick a different deployment mechanism than the default. `Bundled`: includes all the app's dependencies inside the APK. `Unbundled`: excludes native libraries from the APK. The libraries are expected to be present on the target device. The location can be provided either by setting the property QT_ANDROID_SYSTEM_LIBS_PREFIX in your CMake project file, or by defining the path as meta-data in AndroidManifest.xml:
       <application>
           <meta-data
               android:name="system_libs_prefix"
               android:value="path/to/libraries/"/>
       </application>
If no path is provided, `/system/lib/` is used as the default path. Note: `Unbundled` deployment does not support incremental builds. Note: `Unbundled` deployment not supported when deploying as AAB. Default is `Bundled` deployment.
`--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.
`--device <ID>` | Specify the ID of the target device or emulator as reported by the `adb` tool. If an ID is specified, it will be passed to all calls to `adb`. If it is unspecified, no particular device or emulator will be requested by `adb`, causing it to pick a default instead.
`--android-platform <platform>` | The SDK platform used for building the Java code of the application. By default, the latest available platform is used.
`--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.
`--sign <url> <alias>` | Sign the resulting package. Specifying this also implies `--release`. The URL of the keystore file and the alias of the key have to be specified. Optionally, set the following environment variables to conceal the signing information `QT_ANDROID_KEYSTORE_PATH`, `QT_ANDROID_KEYSTORE_ALIAS`, `QT_ANDROID_KEYSTORE_STORE_PASS`, and `QT_ANDROID_KEYSTORE_KEY_PASS`. In addition, there are a number of options that can be specified which are passed through to the `jarsigner` tool. Pass `--help` to `androiddeployqt` for more information.
`--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 `jarsigner` tool. If it is unspecified, then `androiddeployqt` will attempt to detect `jarsigner`, either using the `JAVA_HOME` environment variable, or on the `PATH`.
`--verbose` | Specify this to output more information about what `androiddeployqt` is doing.
`--help` | Prints the help for the tool.

With a project named `project`, to directly build the application package with `androiddeployqt` without deploying it the device, run the following:

     .androiddeployqt --input $BUILD_DIR/android-project-deployment-settings.json --output $ANDROID_BUILD_DIR

To deploy the built package to the device:

     androiddeployqt --verbose --output $ANDROID_BUILD_DIR --no-build --input $BUILD_DIR/android-project-deployment-settings.json --gradle --reinstall --device <adb_device_id>

## 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 Qt SVG module to your project for it to become a dependency of your application:

     QT += svg

If you are wondering why a particular plugin is not included automatically, you can run androiddeployqt with the `--verbose` option to get the list of missing dependencies for each excluded plugin. You can achieve the same in Qt Creator by ticking the Verbose output check box in the Projects > Build Steps > Build Android APK > Advanced Actions.

It's also possible to manually specify the dependencies of your application. For more information, see ANDROID_DEPLOYMENT_DEPENDENCIES qmake variable.

Note: androiddeployqt scans the QML files of the project to collect the QML imports. However, if you are loading QML code as a QString from C++ at runtime, that might not work properly because androiddeployqt won't be aware of it at deploy time. To remedy that, you can add a dummy QML file that imports such QML modules that are referenced at runtime.

## Android-specific qmake Variables

Unless the project has special requirements such as third party libraries, it should be possible to run androiddeployqt on it with no modifications and get a working Qt for Android application.

There are two important environment variables used by Qt:

- `ANDROID_SDK_ROOT`: specifies the path to the Android SDK used for building the application. The Android SDK contains the build-tools, Android NDK, and Android toolchains.
- `ANDROID_NDK_ROOT`: specifies the path to the Android NDK used to build the application. It is not recommended to hard-code this path, since different Qt for Android versions can depend on different Android NDK versions.

Note: Qt Creator sets these variables by default.

There are a set of `qmake` or `CMake` variables that can be used to tailor your package. At some point during development, you will most likely want to look into these variables to customize your application.

Here is a list of some variables that are particularly interesting when making Android applications:

- ANDROID_PACKAGE_SOURCE_DIR
- ANDROID_VERSION_CODE
- ANDROID_VERSION_NAME
- ANDROID_EXTRA_LIBS
- ANDROID_EXTRA_PLUGINS
- ANDROID_ABIS
- ANDROID_API_VERSION
- ANDROID_DEPLOYMENT_DEPENDENCIES
- ANDROID_MIN_SDK_VERSION
- ANDROID_TARGET_SDK_VERSION
- JAVA_HOME

Also, the following `qmake` variables are primarily useful when writing a Qt module, and not normal applications:

- ANDROID_BUNDLED_JAR_DEPENDENCIES
- ANDROID_LIB_DEPENDENCIES
- ANDROID_PERMISSIONS
- ANDROID_FEATURES

Note: This list of variables can also be used with CMake.

## Deployment in Qt Creator

Qt Creator runs `androiddeployqt` by default, and provides easy and intuitive user interfaces to specify many of the options. For more information, see Qt Creator: Deploying Applications to Android Devices.