1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page android-deploy-qt-tool.html
6 \brief An overview of the androiddeployqt tool and how to use it.
7 \title The androiddeployqt Tool
9 \target androiddeployqt
10 Building an application package is complex, so Qt comes with a tool which
11 handles the work for you. The steps described in
12 \l{Deploying an Application on Android} are handled by the androiddeployqt
15 \section1 Prerequisites Before Running androiddeployqt
17 Before running the tool manually, you need to run \c qmake or \c CMake
18 on your project to generate \c Makefiles and a \c JSON file (i.e.
19 \c{android-project-deployment-settings.json}) containing important settings
20 used by \c androiddeployqt.
22 \note It is not recommended to modify the androiddeployqt JSON file.
24 To prepare the build for androiddeployqt, it is recommended to build your
25 project in a separate directory. Run the following commands:
37 qmake ../project/project.pro
39 make -j$(nproc) apk_install_target
47 \section1 Command Line Arguments
49 The only required command line argument when running the tool is \c{--output}.
50 Other command line arguments are optional but useful. The list below is available
51 by passing the \c{--help} argument to androiddeployqt.
53 \quotefromfile main.cpp
54 \skipto Syntax: androiddeployqt --output <destination> [options]
55 \printuntil --help: Displays this information.
57 With a project named \c project, to directly build the application package
58 with \c androiddeployqt without deploying it the device, run the following:
61 .androiddeployqt --input $BUILD_DIR/android-project-deployment-settings.json --output $ANDROID_BUILD_DIR
64 To deploy the built package to the device:
67 androiddeployqt --verbose --output $ANDROID_BUILD_DIR --no-build --input $BUILD_DIR/android-project-deployment-settings.json --gradle --reinstall --device <adb_device_id>
70 \section1 Dependencies Detection
72 Qt comes with a number of plugins which are loaded at run-time when they are
73 needed. These can handle anything from connecting to SQL databases to loading
74 specific image formats. Detecting plugin dependencies is impossible as the
75 plugins are loaded at run-time, but androiddeployqt tries to guess such
76 dependencies based on the Qt dependencies of your application. If the plugin
77 has any Qt dependencies which are not also dependencies of your application,
78 it will not be included by default. For instance, in order to ensure that
79 the SVG image format plugin is included, you will need to add \l{Qt SVG}
80 module to your project for it to become a dependency of your application:
86 If you are wondering why a particular plugin is not included automatically,
87 you can run androiddeployqt with the \c{--verbose} option to get the list of
88 missing dependencies for each excluded plugin. You can achieve the same in
89 Qt Creator by ticking the \uicontrol {Verbose output} check box in the
90 \uicontrol {Projects} > \uicontrol {Build Steps} > \uicontrol {Build Android APK} >
91 \uicontrol {Advanced Actions}.
93 It's also possible to manually specify the dependencies of your application.
94 For more information, see \l{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable.
96 \note androiddeployqt scans the QML files of the project to collect the QML imports.
97 However, if you are loading QML code as a QString from C++ at runtime, that might
98 not work properly because androiddeployqt won't be aware of it at deploy time.
99 To remedy that, you can add a dummy QML file that imports such QML modules that
100 are referenced at runtime.
102 \section1 Android-specific qmake Variables
104 Unless the project has special requirements such as third party libraries,
105 it should be possible to run \l androiddeployqt on it with no modifications
106 and get a working Qt for Android application.
108 There are two important environment variables used by Qt:
111 \li \c{ANDROID_SDK_ROOT}: specifies the path to the Android SDK used for
112 building the application. The Android SDK contains the build-tools,
113 Android NDK, and Android toolchains.
114 \li \c{ANDROID_NDK_ROOT}: specifies the path to the Android NDK used to
115 build the application. It is not recommended to hard-code this path,
116 since different Qt for Android versions can depend on different
117 Android NDK versions.
120 \note Qt Creator sets these variables by default.
122 There are a set of \c qmake or \c CMake variables that can be used to tailor
123 your package. At some point during development, you will most likely want
124 to look into these variables to customize your application.
126 Here is a list of some variables that are particularly interesting when
127 making Android applications:
130 \li \l{ANDROID_PACKAGE_SOURCE_DIR}
131 \li \l{ANDROID_VERSION_CODE}
132 \li \l{ANDROID_VERSION_NAME}
133 \li \l{ANDROID_EXTRA_LIBS}
134 \li \l{ANDROID_EXTRA_PLUGINS}
136 \li \l{ANDROID_API_VERSION}
137 \li \l{ANDROID_DEPLOYMENT_DEPENDENCIES}
138 \li \l{ANDROID_MIN_SDK_VERSION}
139 \li \l{ANDROID_TARGET_SDK_VERSION}
143 Also, the following \c qmake variables are primarily useful when writing a Qt module, and not
147 \li \l{ANDROID_BUNDLED_JAR_DEPENDENCIES}
148 \li \l{ANDROID_LIB_DEPENDENCIES}
149 \li \l{ANDROID_PERMISSIONS}
150 \li \l{ANDROID_FEATURES}
153 \note This list of variables can also be used with CMake.
155 \section1 Deployment in Qt Creator
157 Qt Creator runs \c androiddeployqt by default, and provides easy
158 and intuitive user interfaces to specify many of the options. For more
159 information, see \l{Qt Creator: Deploying Applications to Android Devices}.
1.9.7