Android: update Android deployment docs

Task-number: QTBUG-80390
Change-Id: I370c7bf21b246927f164ececcb17af078cea7ed1
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

2 files changed, 368 insertions, 228 deletions

diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index fcc8ef72..b234576f 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -235,6 +235,18 @@
     \title Android: Binder
 */
 /*!
+    \externalpage https://developer.android.com/guide/app-bundle
+    \title Android: App Bundles
+*/
+/*!
+    \externalpage https://developer.android.com/guide/components/activities/intro-activities
+    \title Android: Introduction to Activities
+*/
+/*!
+    \externalpage https://developer.android.com/studio/build#build-files
+    \title Android: Build Configuration Files
+*/
+/*!
     \externalpage https://bugreports.qt.io/browse/QTBUG-81461
     \title QTBUG-81461
 */
diff --git a/doc/src/platforms/android/android-deploying-application.qdoc b/doc/src/platforms/android/android-deploying-application.qdoc
index 3503bc84..96da38a1 100644
--- a/doc/src/platforms/android/android-deploying-application.qdoc
+++ b/doc/src/platforms/android/android-deploying-application.qdoc
@@ -1,6 +1,6 @@
-/****************************************************************************
+/****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -30,111 +30,144 @@
 
     \title Deploying an Application on Android
 
-    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).
+    This article describes the technical steps required to deploy a Qt
+    application to an Android device.
 
-    It is recommended that you use Qt Creator or the Makefile created by qmake to
-    create the application bundle. 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.
+    \section1 Android Application Bundle
 
-    All the steps described here are handled automatically by the build script and
-    the \l {androiddeployqt}{androiddeployqt deployment tool}, which are run by Qt Creator
-    for you.
+    Applications on Android can be packaged in two ways; either as Application
+    Package (APK) or Android App Bundle (AAB). Both are ZIP files which follow
+    a predefined directory structure. The difference between the two is that APK
+    files can be deployed and executed on a device, whereas AAB is intended to
+    be interpreted by the Google Play store and is used to generate APK files
+    for different device architectures.
 
-    \note If you prefer building Android packages from the command line, you may use the "aab"
-    or "apk" build targets in the Makefile directly:
+    For testing the application locally, the APK format is the most appropriate,
+    as this can be uploaded directly to the device and run. 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.
 
-    \code
-    % make aab
-    \endcode
-
-    or
-
-    \code
-    % make apk
-    \endcode
+    For more information on the AAB format, see
+    \l{Android: App Bundles}{the Android App Bundles}.
 
-    \tableofcontents
+    In either case, the application bundle is generated from a specific directory
+    structure that contains the \c .so file of your code, as well as all Qt's
+    dependencies needed by your application. In addition, any \c .jar files,
+    Java code, assets, resources and \c .xml files are included.
 
-    \section1 The Application Bundle
+    \section2 Generating the Application Bundle
 
-    Applications on Android can be packaged in two ways: Either as Application Package (APK)
-    or Android App Bundle (AAB). Both are ZIP files which follow a predefined directory
-    structure. The difference between the two is that APK files can be downloaded to
-    and executed on a device. AAB, on the other hand, is intended to be interpreted by the
-    Google Play store and is used to generate APK files.
+    It is recommended to use Qt Creator or the Makefile created by qmake or CMake
+    to create the application bundle.
 
-    For testing the application locally, the APK format is the most appropriate, as this can
-    be uploaded directly to the device and run. For distribution to the Google Play store, it is
-    recommended that you 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 sign them with your publisher key.
+    All the steps described here are automatically handled by the build script
+    and the \l {androiddeployqt}{androiddeployqt deployment tool}, which are run
+    by Qt Creator by default.
 
-    Read \l{https://developer.android.com/guide/app-bundle}{the Android documentation} if you
-    want to know more about the AAB format.
+    \note If you prefer building Android packages from the command line, see
+    \l{Building the Android Application}.
 
-    In either case, the files must be copied into a special directory structure first, before
-    bundling them in a single ZIP file
+    \section1 Android Package Templates
 
-    This contains one or more binary \c .so files with the code for your application, as
-    well as any dependencies, such as Qt's libraries and plugins. In addition, it includes
-    \c .jar files containing compiled Java code, assets, resources, and some \c .xml
-    files that are used to describe the contents of the bundle.
+    The default templates used by Qt are found in \c {$Qt_install_dir/src/android/templates}.
+    The first step of making a custom package is to copy these files into an
+    empty directory, for example \c android, under your project. Then, you need
+    to define that path in your project's \c .pro file, using the variable
+    \l{ANDROID_PACKAGE_SOURCE_DIR}:
 
-    \section1 Package Template
+    \badcode
+    android {
+        ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android
 
-    A template for the other sources of an APK package is contained in \c{$QTDIR/src/android/templates}.
-    The first step of making a package manually is to copy these files into an empty directory. In this
-    guide, we'll refer to this build directory as \c{$BUILD_TARGET}.
+        DISTFILES += \
+            android/AndroidManifest.xml \
+            android/build.gradle \
+            android/res/values/libs.xml
+    }
+    \endcode
 
-    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:
+    Qt Creator copies the package templates to your Android build directory
+    (\e{$ANDROID_BUILD_DIR=$BUILD_DIR/android-build}) into your project build
+    directory (\e$BUILD_DIR). If you want to build from the command line, use
+    the following after running \c qmake or \c CMake:
 
     \code
-    make install INSTALL_ROOT=$BUILD_TARGET
+    export ANDROID_BUILD_DIR=$BUILD_DIR/android-build
+    make -j$(nproc) install INSTALL_ROOT=$ANDROID_BUILD_DIR
     \endcode
 
-    It will copy the application binary and any other installation requirements into the packaging
-    directory.
-
-    The packaging directory will now consist of the following parts:
+    The previous command copies the application's binaries and resources
+    into the $ANDROID_BUILD_DIR. The build directory acts now as the packaging directory,
+    which the application bundle is created from. The main parts of the package
+    templates are described in the following sections.
 
     \section2 AndroidManifest.xml
 
-    The \c{AndroidManifest.xml} 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.
-
-    For more information about general capabilities of and requirements for the
-    \c{AndroidManifest.xml} file, please refer to the
-    \l{http://developer.android.com/guide/topics/manifest/manifest-intro.html}{Android documentation on this topic}.
+    The \c{AndroidManifest.xml} file gives detailed meta-information about your
+    application. This information is used to customize your application bundle
+    and 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
+    Google Play Store for information on the version code, device support,
+    package name, and lots more.
+
+    For more information about the \c AndroidManifest.xml, see
+    \l{Android: App Manifest}{Android Manifest documentation}.
+
+    The default manifest contains some special parameters used by Qt to set up
+    the application and load all the necessary libraries for Qt. When you are
+    customizing your own Android manifest, make sure that it contains these
+    parameters. For that reason, it's recommended to start with the default
+    templates, then customize on top of that. The \l androiddeployqt tool replaces
+    content in the templates with the correct values. The parts that are filled
+    by \l androiddeployqt have the value as \c "-- %%INSERT_VALUE%% --", as in:
+
+    \badcode
+    <meta-data android:name="android.app.lib_name" android:value="-- %%INSERT_APP_LIB_NAME%% --"/>
+    <meta-data android:name="android.app.qt_sources_resource_id" android:resource="@array/qt_sources"/>
+    <meta-data android:name="android.app.repository" android:value="default"/>
+    <meta-data android:name="android.app.qt_libs_resource_id" android:resource="@array/qt_libs"/>
+    <meta-data android:name="android.app.bundled_libs_resource_id" android:resource="@array/bundled_libs"/>
+    <!-- Deploy Qt libs as part of package -->
+    <meta-data android:name="android.app.bundle_local_qt_libs" android:value="-- %%BUNDLE_LOCAL_QT_LIBS%% --"/>
+
+    <!-- Run with local libs -->
+    <meta-data android:name="android.app.use_local_qt_libs" android:value="-- %%USE_LOCAL_QT_LIBS%% --"/>
+    <meta-data android:name="android.app.libs_prefix" android:value="/data/local/tmp/qt/"/>
+    <meta-data android:name="android.app.load_local_libs_resource_id" android:resource="@array/load_local_libs"/>
+    <meta-data android:name="android.app.load_local_jars" android:value="-- %%INSERT_LOCAL_JARS%% --"/>
+    <meta-data android:name="android.app.static_init_classes" android:value="-- %%INSERT_INIT_CLASSES%% --"/>
+    \endcode
 
-    The default manifest contains some special parameters used by Qt to set up the application for
-    running. When you are creating your own Android manifest, you must make sure that it contains these
-    parameters. The \c androiddeployqt tool replaces content in the template with the correct
-    values.
+    The Android Manifest is also used to define \l{Android Services}, and custom
+    \l{Android: Introduction to Activities}{Android Activities}.
 
     \section2 Java Code
 
-    Under \c{$BUILD_TARGET/src} 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.
+    Under \c{$Qt_install_dir/src/android/java/src/org/qtproject/qt5/android/bindings/}
+    are the files comprising the Java code of the Android application. This Java
+    code is compiled under $ANDROID_BUILD_DIR and added to the application bundle. 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 Manifest file.
 
-    After loading the libraries, the Java code will call into the application's native \c{main()}
-    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.
+    After loading the libraries, the Java code will call into the application's
+    native \c{main()} function on a new thread and the application will launch.
+    At this point, the Java code in the templates is used to delegate events from
+    Android into Qt.
 
-    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 \c androiddeployqt and Qt Creator during packaging.
+    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 \c androiddeployqt and Qt Creator
+    during packaging.
 
-    For example, lets say the code contains the following:
+    If your minimum Android API level is 20 or lower, the code below is 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 is left in:
 
     \code
 //@ANDROID-21
@@ -147,196 +180,291 @@
 //@ANDROID-21
     \endcode
 
-    If your minimum Android API level is 20 or lower, the code is 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 is left in.
-
     \section2 Resources
 
-    Under the \c{res/} folder in the \c{$BUILD_TARGET} are Android resources that can be accessed
-    from the \c{AndroidManifest.xml} 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.
-
-    In Qt, some translations used for the Ministro service and some files with meta-information
-    are in the default resources of the application.
+    Under the \c{$Qt_instal_dir/src/android/templates/res/} folder are Android
+    resources that can be accessed from the \c{AndroidManifest.xml} and Java code
+    used by all Qt applications.
 
-    \section3 res/values/libs.xml
+    \section3 libs.xml
 
-    One of the files containing meta information about the deployment of the application is
-    \c{libs.xml}. It consists of the following values:
+    This file can be found at \c {$Qt_instal_dir/src/android/templates/res/values/libs.xml}.
+    One of the files containing meta information about the deployment of the
+    application is \c{libs.xml}. It consists of the following values:
 
     \list
-    \li \c{qt_sources}: 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
-    \l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro documentation} for more
-    information about such repositories.
-    \li \c{bundled_libs}: Libraries in the package's library folder which should be loaded on start-up.
-    Library names should be specified without the \c lib prefix and \c{.so} suffix.
-    \li \c{qt_libs}: Qt libraries which should be loaded on start-up. When bundled deployment is
-    used, these are expected to be found inside the \c{APK}'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 \c{/data/local/tmp/qt} directory on the
-    target device.
+        \li \c{bundled_libs}: Libraries in the package's library folder which
+            should be loaded on start-up. Library names should be specified
+            without the \c lib prefix and \c{.so} suffix.
+
+        \li \c{qt_libs}: Qt libraries which should be loaded on start-up. When
+            bundled deployment is used, these are expected to be found inside
+            the \c{APK}'s library folder.
     \endlist
 
-    \section3 res/values/strings.xml
+    \note Ministro is no longer maintained.
+
+    \section3 strings.xml
+
+    This file can be found at \c {$Qt_instal_dir/src/android/java/res/values/strings.xml}.
+    The \c{strings.xml} file contains strings used by the \c{AndroidManifest.xml}
+    and by the deployment mechanisms.
+
+    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 \c JAR files which should be included
+    in the class path.
+
+    \section3 Gradle Files
+
+    The main Gradle build file can be found at \c {$Qt_instal_dir/src/android/templates/build.gradle}.
+    This file is required by the Gradle build system used by Android to generate
+    the application's APK. For more information, see
+    \l{Android: Build Configuration Files}{Android Build Configuration Files}.
+
+    \section1 Customizing the Package Templates
+
+    \section2 Resouces
+
+    Put any resources used by your application under \c{$ANDROID_PACKAGE_SOURCE_DIR/res/}.
+    A typical example of resources customization which should be placed here are
+    the icons used by the application launcher to show your application.
 
-    The \c{strings.xml} file contains some strings used by the \c{AndroidManifest.xml} and by the
-    deployment mechanisms, as well as some strings used when loading the Ministro service.
+    \section2 Custom Java Code
 
-    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
-    \c JAR files which should be included in the class path. The latter is only used for deployment
-    with Ministro or debug deployment.
+    Place any Java code under the path \c{$ANDROID_PACKAGE_SOURCE_DIR/src/}.
+    Any code here can be used with your application, for example you can call
+    Java methods from within Qt code. For more information, see
+    \l{Qt JNI Messenger}{Qt JNI Messenger Example}.
 
-    \section2 Libraries
+    When using Qt Creator, add the Java files to your project using \l DISTFILES,
+    so they are visible under the project files.
 
-    Under \c libs in the package directory, it's possible to place libraries that should be included
-    in the application bundle. \c JAR libraries should be placed directly under \c{libs/}, while
-    shared libraries should be put in a subdirectory suitably named after the target ABI
-    of the libraries.
+    \section2 Assets
 
-    \section1 Building the Android Application Package
+    You can place any assets that are intended to be accessed by Java code under
+    \c{$ANDROID_PACKAGE_SOURCE_DIR/assets/}. For more information on using assets
+    with Qt, see \l{Porting to Android}. However, to have the best integration
+    with Qt, it is recommended to use \l{The Qt Resource System}.
 
-    The project can be built using the gradle tool. If an APK intended for release is built, then
-    it should be signed and aligned using \c jarsigner and \c zipalign.
+    \section2 Android Libraries
+
+    Under \c{$ANDROID_PACKAGE_SOURCE_DIR/libs} in your custom package directory,
+    it's possible to place libraries that should be included in the application
+    bundle. \c JAR libraries should be placed directly under
+    \c{$ANDROID_PACKAGE_SOURCE_DIR/libs/}, while shared libraries should be put
+    in a subdirectory named after the target ABI of the libraries. The supported
+    ABIs are: armeabi-v7a, arm64-v8a, x86, x86_64.
+
+    For more information, see also \l{Third-party Android Libraries}.
+
+    \section1 Building the Android Application
+
+    Starting from Qt 5.14.0, you may use the \e "aab" or \e "apk" build targets
+    from the Makefile directly to build the application bundle. Use the following
+    command to generate an AAB:
+
+    \badcode
+    make -j$(nproc) aab
+    \endcode
+
+    Or to generate the APK:
+
+    \badcode
+    make -j$(nproc) apk
+    \endcode
+
+    Under the hood, your Qt code is built and copied to the $ANDROID_BUILD_DIR,
+    then \l Gradle is used to build the Java code and package the application.
+    If an APK intended for release is built, then it should be signed with
+    \c jarsigner and aligned with \c zipalign. For more information on signing
+    the package with Qt Creator, see \l{Signing Android Packages}.
 
     \section1 androiddeployqt
 
-    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.
+    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 this tool. This section describes some of the steps
+    that this tool facilitates.
 
-    In addition, there are Makefile build targets for building the package from the
-    command line. There is also automated support in Qt Creator for generating both \c APK and \c AAB
-    packages.
+    \section2 Prerequisites Before Running androiddeployqt
 
-    \section2 Required Steps Before Running androiddeployqt
+    Before running the tool manually, you need to run \c qmake or \c CMake
+    on your project to generate \c Makefiles and a \c JSON file (i.e.
+    \c{android-project-deployment-settings.json}) containing important settings
+    used by \c androiddeployqt.
 
-    Before running the tool manually, you need to run \c qmake and \c make on your project. Running
-    \c qmake creates the \c Makefile, and it will also generate a \c JSON file containing important
-    settings used by \c androiddeployqt.
+    \note It is not recommended to modify the androiddeployqt JSON file.
 
-    You should then install the application binary (and any other requirements) into the library
-    folder of the \c bundle. If \c{$BUILD_TARGET} 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:
+    To prepare the build for androiddeployqt, it is recommended to build your
+    project in a separate directory. Run the following commands:
 
-    \code
-    % make install INSTALL_ROOT=$BUILD_TARGET
+    \badcode
+    mkdir build-project
+    cd build-project
+    ~/Qt/5.15.0/android/bin/qmake ../project/project.pro
+    export ANDROID_BUILD_DIR=$(pwd)/android-build/
+    make -j$(nproc)
+    make -j$(nproc) install INSTALL_ROOT=$ANDROID_BUILD_DIR
     \endcode
 
     \section2 Command Line Arguments
 
-    The only required command line argument when running the tool is \c{--output}. This should
-    be set to \c{$BUILD_TARGET}, that is: the build directory where you installed your application
-    binary.
+    The only required command line argument when running the tool is \c{--output}.
+    Other command line arguments are optional but useful. Here's a quick overview.
+    More information is available by passing the \c{--help} argument to androiddeployqt.
+
+    \table
+        \header
+            \li Argument
+            \li Brief Description
+        \row
+            \li \c{--output <destination>}
+            \li Specifies the destination of the final package. Set this to
+                \c{$ANDROID_BUILD_DIR}, that is the build directory where you installed
+                your application binaries.
+        \row
+            \li \c{--input <file name>}
+            \li This allows you to specify the generated \c JSON settings file.
+                \c androiddeployqt will try to guess the file name based on the
+                current working directory.
+        \row
+            \li \c{--aab}
+            \li Generate an Android Application Bundle, rather than an APK. Note
+                that this invalidates some of the other arguments, such as \c{--install}.
+        \row
+            \li \c{--deployment <mechanism>}
+            \li Specify this to pick a different deployment mechanism than the
+                default.
+        \row
+            \li \c{--install}
+            \li 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.
+        \row
+            \li \c{--device <ID>}
+            \li Specify the ID of the target device or emulator as reported by
+                the \c adb tool. If an ID is specified, it will be passed to all
+                calls to \c adb. If it is unspecified, no particular device or
+                emulator will be requested by \c adb, causing it to pick a default
+                instead.
+        \row
+            \li \c{--android-platform <platform>}
+            \li The SDK platform used for building the Java code of the application.
+                By default, the latest available platform is used.
+        \row
+            \li \c{--release}
+            \li 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.
+        \row
+            \li \c{--sign <url> <alias>}
+            \li Sign the resulting package. Specifying this also implies
+                \c{--release}. 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
+                \c jarsigner tool. Pass \c{--help} to \c androiddeployqt for
+                more information.
+        \row
+            \li \c{--jdk <path>}
+            \li Specify the path to the Java Development Kit. This is only
+                required for signing packages, as it is only used for finding
+                the \c jarsigner tool. If it is unspecified, then \c androiddeployqt
+                will attempt to detect \c jarsigner, either using the \c{JAVA_HOME}
+                environment variable, or on the \c PATH.
+        \row
+            \li \c{--verbose}
+            \li Specify this to output more information about what \c androiddeployqt is
+                doing.
+        \row
+            \li \c{--help}
+            \li Prints the help for the tool.
+    \endtable
+
+    With a project named \c project, to directly build the application package
+    with androiddeployqt without deploying it the device, run the following:
+
+    \badcode
+    ~/Qt/5.15.0/android/bin/androiddeployqt --input $BUILD_DIR/android-project-deployment-settings.json --output $ANDROID_BUILD_DIR --android-platform android-29 --jdk /usr/lib/jvm/java-8-openjdk-amd64 --gradle
+    \endcode
 
-    Other command line arguments are optional but useful. Here's a quick overview. More information
-    is available by passing the \c{--help} argument to androiddeployqt.
+    To deploy the built package to the device:
 
-    \list
-    \li \c{--aab}: Generate an Android Application Bundle, rather than an APK. Note that this
-    invalidates some of the other arguments, such as --install.
-    \li \c{--input <file name>}: This allows you to specify the \c JSON file generated by \c qmake.
-    By default, \c androiddeployqt will try to guess the file name based on the current working
-    directory.
-    \li \c{--deployment <mechanism>}: Specify this to pick a different deployment mechanism than the
-    default.
-    \li \c{--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.
-    \li \c{--device <ID>}: Specify the ID of the target device or emulator as reported by the \c adb
-    tool. If an ID is specified, it will be passed to all calls to \c adb. If it is unspecified, no
-    particular device or emulator will be requested by \c adb, causing it to pick a default instead.
-    \li \c{--android-platform <platform>}: The SDK platform used for building the Java code of the
-    application. By default, the latest available platform is used.
-    \li \c{--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.
-    \li \c{--sign <url> <alias>}: Sign the resulting package. Specifying this also implies
-    \c{--release}. 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
-    \c jarsigner tool. Pass \c{--help} to \c androiddeployqt for more information about these.
-    \li \c{--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 \c jarsigner tool. If it is unspecified,
-    then \c androiddeployqt will attempt to detect \c jarsigner, either using the \c{JAVA_HOME}
-    environment variable, or on the \c PATH.
-    \li \c{--verbose}: Specify this to output more information about what \c androiddeployqt is
-    doing.
-    \endlist
+    \badcode
+    ~/Qt/5.15.0/android/bin/androiddeployqt --verbose --output $ANDROID_BUILD_DIR --no-build --input $BUILD_DIR/android-project-deployment-settings.json --gradle --reinstall --device <adb_device_id>
+    \endcode
+
+    \section2 Dependencies Detection
 
-    \section1 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 \l{Qt SVG}
+    module to your project for it to become a dependency of your application:
 
-    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 \c{QT += svg} to your \c .pro file
-    so that the \l{Qt SVG} module becomes a dependency of your application.
+    \badcode
+    QT += svg
+    \endcode
 
-    If you are wondering why a particular plugin is not included automatically, you can run androiddeployqt
-    with the \c --verbose option to get the list of missing dependencies for each excluded plugin. You
-    can achieve the same in Qt Creator by ticking the \gui{Verbose output} check box in the
-    \gui{Deployment configurations}. This is located in the \gui{Run} tab of your \gui{Projects}
-    settings.
+    If you are wondering why a particular plugin is not included automatically,
+    you can run androiddeployqt with the \c{--verbose} option to get the list of
+    missing dependencies for each excluded plugin. You can achieve the same in
+    Qt Creator by ticking the \uicontrol {Verbose output} check box in the
+    \uicontrol {Projects} > \uicontrol {Build Steps} > \uicontrol {Build Android APK} >
+    \uicontrol {Advanced Actions}.
 
-    It's also possible to manually specify the dependencies of your application. See the documentation
-    for the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable below.
+    It's also possible to manually specify the dependencies of your application.
+    For more information, see \l{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable.
 
     \section1 Android-specific qmake Variables
 
-    Unless the project has special requirements such as third party libraries, it should be
-    possible to run \c androiddeployqt on it with no modifications and get a working Qt for Android
-    application as a result.
+    Unless the project has special requirements such as third party libraries,
+    it should be possible to run \l androiddeployqt on it with no modifications
+    and get a working Qt for Android application.
 
-    However, there are a set of \c qmake 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.
+    However, there are a set of \c qmake 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:
+    Here is a list of some variables that are particularly interesting when
+    making Android applications:
 
     \list
-    \li \c{ANDROID_DEPLOYMENT_DEPENDENCIES}: By default, \c androiddeployqt 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 \e potential
-    dependencies. If you want to minimize the size of your \c APK, it's possible to override the
-    automatic detection using the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} 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 \c{ANDROID_PACKAGE_SOURCE_DIR}: This variable can be used to specify a directory where
-    additions and modifications can be made to the default Android package template. The
-    \c androiddeployqt tool will copy the application template from Qt into the build directory, and
-    then it will copy the contents of the \c{ANDROID_PACKAGE_SOURCE_DIR} 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 \c{AndroidManifest.xml} for your application, then place this
-    directly into the folder specified in this variable. You can also add custom Java files in
-    \c{ANDROID_PACKAGE_SOURCE_DIR/src}.
-    \note 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 \c{$QT/src/android/java}. You should never copy any files from the build
-     directory, as these files have been altered to match the current build settings.
-    \li \c{ANDROID_EXTRA_LIBS}: 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 \c{libssl.so} and \c{libcrypto.so}
-    libraries here and OpenSSL should be enabled automatically.
-    \li \c{ANDROID_EXTRA_PLUGINS}: 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, \c androiddeployqt will make sure everything is packaged and deployed properly.
+        \li \l{ANDROID_PACKAGE_SOURCE_DIR}
+        \li \l{ANDROID_VERSION_CODE}
+        \li \l{ANDROID_VERSION_NAME}
+        \li \l{ANDROID_EXTRA_LIBS}
+        \li \l{ANDROID_EXTRA_PLUGINS}
+        \li \l{ANDROID_ABIS}
+        \li \l{ANDROID_API_VERSION}
+        \li \l{ANDROID_DEPLOYMENT_DEPENDENCIES}
+        \li \l{ANDROID_SDK_ROOT}
+        \li \l{ANDROID_NDK_ROOT}
+        \li \l{ANDROID_MIN_SDK_VERSION}
+        \li \l{ANDROID_TARGET_SDK_VERSION}
+        \li \l{JAVA_HOME}
     \endlist
 
+    Also, the most useful \c qmake variable when writing a Qt module:
+
+    \list
+        \li \l{ANDROID_BUNDLED_JAR_DEPENDENCIES}
+        \li \l{ANDROID_LIB_DEPENDENCIES}
+        \li \l{ANDROID_PERMISSIONS}
+        \li \l{ANDROID_FEATURES}
+    \endlist
+
+    \note This list of variables can also be used with CMake.
+
     \section1 Deployment in Qt Creator
 
-    Qt Creator will run the \c androiddeployqt tool for you, and provides easy and intuitive user
-    interfaces to specify many of the options. For more information, see
-    \l{Qt Creator: Deploying Applications to Android Devices}{the Qt Creator documentation}.
+    Qt Creator runs the \l androiddeployqt tool by default, and provides easy
+    and intuitive user interfaces to specify many of the options. For more
+    information, see \l{Qt Creator: Deploying Applications to Android Devices}{the Qt Creator documentation}.
 */