- Qt 6.7
- Qt Core
- The androiddeployqt Tool
- Qt 6.7.0 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. The list below is available by passing the `--help` argument to androiddeployqt.

     Syntax: androiddeployqt --output <destination> [options]

     Creates an Android package in the build directory <destination> and
     builds it into an .apk file.

     Optional arguments:
         --input <inputfile>: Reads <inputfile> for options generated by
            qmake. A default file name based on the current working
            directory will be used if nothing else is specified.

         --deployment <mechanism>: Supported deployment mechanisms:
            bundled (default): Includes Qt files in stand-alone package.
            unbundled: Assumes native libraries are present on the device
            and does not include them in the APK.

         --aab: Build an Android App Bundle.

         --no-build: Do not build the package, it is useful to just install
            a package previously built.

         --install: Installs apk to device/emulator. By default this step is
            not taken. If the application has previously been installed on
            the device, it will be uninstalled first.

         --reinstall: Installs apk to device/emulator. By default this step
            is not taken. If the application has previously been installed on
            the device, it will be overwritten, but its data will be left
            intact.

         --device [device ID]: Use specified device for deployment. Default
            is the device selected by default by adb.

         --android-platform <platform>: Builds against the given android
            platform. By default, the highest available version will be
            used.

         --release: Builds a package ready for release. By default, the
            package will be signed with a debug key.

         --sign <url/to/keystore> <alias>: Signs the package with the
            specified keystore, alias and store password.
            Optional arguments for use with signing:
              --storepass <password>: Keystore password.
              --storetype <type>: Keystore type.
              --keypass <password>: Password for private key (if different
                from keystore password.)
              --sigfile <file>: Name of .SF/.DSA file.
              --digestalg <name>: Name of digest algorithm. Default is
                "SHA1".
              --sigalg <name>: Name of signature algorithm. Default is
                "SHA1withRSA".
              --tsa <url>: Location of the Time Stamping Authority.
              --tsacert <alias>: Public key certificate for TSA.
              --internalsf: Include the .SF file inside the signature block.
              --sectionsonly: Don't compute hash of entire manifest.
              --protected: Keystore has protected authentication path.
              --jarsigner: Deprecated, ignored.

            NOTE: To conceal the keystore information, the environment variables
              QT_ANDROID_KEYSTORE_PATH, and QT_ANDROID_KEYSTORE_ALIAS are used to
              set the values keysotore and alias respectively.
              Also the environment variables QT_ANDROID_KEYSTORE_STORE_PASS,
              and QT_ANDROID_KEYSTORE_KEY_PASS are used to set the store and key
              passwords respectively. This option needs only the --sign parameter.

         --jdk <path/to/jdk>: Used to find the jarsigner tool when used
            in combination with the --release argument. By default,
            an attempt is made to detect the tool using the JAVA_HOME and
            PATH environment variables, in that order.

         --qml-import-paths: Specify additional search paths for QML
            imports.

         --verbose: Prints out information during processing.

         --no-generated-assets-cache: Do not pregenerate the entry list for
            the assets file engine.

         --aux-mode: Operate in auxiliary mode. This will only copy the
            dependencies into the build directory and update the XML templates.
            The project will not be built or installed.

         --apk <path/where/to/copy/the/apk>: Path where to copy the built apk.

         --qml-importscanner-binary <path/to/qmlimportscanner>: Override the
            default qmlimportscanner binary path. By default the
            qmlimportscanner binary is located using the Qt directory
            specified in the input file.

         --depfile <path/to/depfile>: Output a dependency file.

         --builddir <path/to/build/directory>: build directory. Necessary when
            generating a depfile because ninja requires relative paths.

         --no-rcc-bundle-cleanup: skip cleaning rcc bundle directory after
            running androiddeployqt. This option simplifies debugging of
            the resource bundle content, but it should not be used when deploying
            a project, since it litters the 'assets' directory.

         --copy-dependencies-only: resolve application dependencies and stop
            deploying process after all libraries and resources that the
            application depends on have been copied.

         --help: Displays this information.

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.