Update Android documentation

A few things have changed with regards to packaging in Qt 5.14,
so we need the documentation to reflect these changes. One major
change is that we now also support the AAB packaging format,
which also requires multi-arch builds.

When going through the documentation, it was clear that a lot
of the information was already outdated, so I took the opportunity
to clean up a bit. I have removed some stale information, removed
some details that only served to confuse, and rewrote some parts
to match the current reality.

Change-Id: I1d016ea66e18c8f174257defec4af532b4960b15
Reviewed-by: BogDan Vatra <bogdan@kdab.com>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

4 files changed, 111 insertions, 145 deletions

diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc
index ebfda3f4..c7ad08bf 100644
--- a/doc/src/deployment/deployment.qdoc
+++ b/doc/src/deployment/deployment.qdoc
@@ -134,27 +134,61 @@
     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).
 
-    It is recommended that you use the \l {androiddeployqt}{androiddeployqt deployment tool} or
-    Qt Creator to automate this work rather than perform the steps manually. 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.
+    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.
+
+    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.
+
+    \note If you prefer building Android packages from the command line, you may use the "aab"
+    or "apk" build targets in the Makefile directly:
+
+    \code
+    % make aab
+    \endcode
+
+    or
+
+    \code
+    % make apk
+    \endcode
 
     \tableofcontents
 
-    \section1 The APK Package
+    \section1 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.
+
+    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.
+
+    Read \l{https://developer.android.com/guide/app-bundle}{the Android documentation} if you
+    want to know more about the AAB format.
 
-    Applications on Android are packaged in a specially structured type of ZIP file called \c APK.
-    When you build a Qt application using \c qmake and \c make, the result will be a binary file
-    which is built with the correct compiler and flags to be usable on an Android device with the
-    target architecture.
+    In either case, the files must be copied into a special directory structure first, before
+    bundling them in a single ZIP file
 
-    In order to turn this into a runnable application, it has to be put into a special directory
-    structure with some other files and packaged into an APK package.
+    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.
 
     \section1 Package Template
 
-    A template for the other sources of an APK package is contained in \c{$QTDIR/src/android/java}.
-    The first step of making an APK is to copy these files into an empty directory. In this
+    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}.
 
     We also need to make sure the application binary is copied into the package. This can be
@@ -180,31 +214,17 @@
     \c{AndroidManifest.xml} file, please refer to the
     \l{http://developer.android.com/guide/topics/manifest/manifest-intro.html}{Android documentation on this topic}.
 
-    There are some special variables recognized by Qt which can be placed inside the manifest:
-
-    \list
-    \li \c{android.app.use_local_qt_libs}: If this is set to \c 1, Qt libraries are expected to be
-    found on the target device. If it is \c 0, then libraries must be requested from the \b Ministro
-    service.
-    \li \c{android.app.bundle_local_qt_libs}: If set to \c 1, the Qt libraries are expected to be
-    bundled as part of the \c APK. If set to \c 0, they are expected to be found in the
-    \c{/data/local/tmp/qt} folder on the target device.
-
-    \note If \c{use_local_qt_libs} is 0, then this variable has no effect, since libraries
-    are then requested through Ministro instead.
-    \endlist
-
-    Other variables in the manifest refer to resources, and more information about these can
-    be found in the \l{Resources}{documentation for the resources} below.
+    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.
 
     \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. The code supports all the
-    three deployment mechanisms which are supported in Qt Creator and \c{androiddeployqt}: \e Bundled,
-    \e Ministro and \e Debug.
+    meta-information given in other files in the template.
 
     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
@@ -228,9 +248,9 @@
 //@ANDROID-21
     \endcode
 
-    If your minimum Android API level is 20 or lower, then the code should be removed before
+    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 should be left in.
+    level is 21 or higher, it is left in.
 
     \section2 Resources
 
@@ -252,29 +272,13 @@
     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{repository}: The Ministro repository to use at the given URL. This is used when the
-    Ministro deployment mechanism is active.
-    \li \c{bundled_libs}: Libraries in the APK's library folder which should be loaded on start-up.
+    \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_in_lib}: List of plugins which are bundled in the \c{APK}'s library folder. This
-    is only used when the bundling deployment mechanism is active. Qt's plugin system requires
-    plugins to be placed in a special directory structure which contains information about the
-    plugin category. The library folder in the APK does not support such a directory
-    structure, so the bundled_in_lib array contains the information lost when the directory
-    structure is flattened. Each item is a pair of paths, separated by a colon. The first of the
-    pair is the file name of the file bundled inside the \c{APK}'s library folder. The second of the
-    pair is the original path of the file, relative to the Qt installation.
-    \li \c{bundled_in_assets}: List of other types of Qt files which are bundled inside the
-    \c{APK}'s asset folder. This value is only used when the bundling deployment mechanism is active. The
-    format of the items is the same as for the \c{bundled_in_lib array}. The difference is that the
-    first of the pairs refers to the path of a file inside the \c{assets} directory of the
-    application instead of the library directory. This array is typically used for bundling QML
-    imports, which also require a special directory structure to be used inside Qt.
     \endlist
 
     \section3 res/values/strings.xml
@@ -291,43 +295,31 @@
 
     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 architecture
+    shared libraries should be put in a subdirectory suitably named after the target ABI
     of the libraries.
 
-    For deployment that bundles Qt in the \c APK, the Qt \c JAR files that are suffixed with
-    \c{"bundled"} should be put into the libs directory. It is also required that the necessary
-    shared libraries and plugins are placed in the appropriate subdirectory of libs.
-
     \section1 Building the Android Application Package
 
-    Once all the pieces are in place, a few steps are required to build the application package.
-    First, a build script needs to be generated. This is done using the \c android tool which is
-    part of the Google Android SDK.
-
-    Example:
-    \code
-    % android update project --path $BUILD_TARGET --target android-16 --name QtApp
-    \endcode
-
-    This example will create build files in \c{$BUILD_TARGET} for an \c APK named \c QtApp. The Java
-    code will be compiled against the \c{android-16} platform.
-
-    The project can then be built using the ant tool. If a release package is built it can
-    be signed and aligned using \c jarsigner and \c zipalign.
+    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.
 
     \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.
 
+    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 Required Steps Before Running androiddeployqt
 
-    Before running the tool, you need run \c qmake and \c make 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.
+    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.
 
     You should then install the application binary (and any other requirements) into the library
-    folder of the \c APK. If \c{$BUILD_TARGET} is your build directory (the first time you do this,
+    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:
 
@@ -345,6 +337,8 @@
     is available by passing the \c{--help} argument to androiddeployqt.
 
     \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.
@@ -358,8 +352,6 @@
     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{--ant <path>}: Specify the path to the \c ant executable. If this is unspecified,
-    \c androiddeployqt will attempt to detect it on the \c PATH.
     \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.
diff --git a/doc/src/platforms/android-building.qdoc b/doc/src/platforms/android-building.qdoc
index c33851d1..aeff44be 100644
--- a/doc/src/platforms/android-building.qdoc
+++ b/doc/src/platforms/android-building.qdoc
@@ -118,11 +118,12 @@
         -android-ndk <path/to/ndk> -android-sdk <path/to/sdk> -no-warnings-are-errors
         \endcode
 
-        You also need to provide the \c{-android-arch} parameter which is necessary to specify the
-        Android architecture, such as armeabi-v71 (default), arm64-v8a, x86, or x86_64:
+        You may provide the \c{-android-abis} parameter to limit the
+        Android ABIs targeted, such as armeabi-v7a, arm64-v8a, x86, or x86_64:
         \code
-        -android-arch armeabi-v71
+        -android-abis armeabi-v7a,arm64-v8a
         \endcode
+        If the parameter is not specified, Qt is built for all supported ABIs.
 
         \li To build the parts of Qt you have now configured run the following command. \e{nproc} is
             optional, representing the number of parallel jobs your system can do.
diff --git a/doc/src/platforms/android-platform-notes.qdoc b/doc/src/platforms/android-platform-notes.qdoc
index 6baed10f..f27bef48 100644
--- a/doc/src/platforms/android-platform-notes.qdoc
+++ b/doc/src/platforms/android-platform-notes.qdoc
@@ -61,59 +61,38 @@
 
     \section1 Application Package
 
-    On Android, apps are distributed in packages called \e APK. Qt Creator
-    builds the \e APK for you, but if you for some reason want to do this
-    manually, you must first make sure that the appropriate packaging and build
-    files are in place. For more detailed information about how the packaging
-    is done, see \l{Deploying an Application on Android}.
+    On Android, apps are distributed to devices in packages called \e APK.
+
+    For distributing apps in Google Play, a different format called AAB is used
+    instead.
 
-    \section1 Deployment
-
-    Qt Creator currently supports three methods of deployment for Android apps: the default
-    deployment method is suitable for distribution of the APK file. With this deployment method,
-    the necessary Qt libraries and files will be copied into your project directory, and bundled
-    as part of the APK, so that you get a stand-alone, distributable application package.
-
-    \section2 Deployment with Ministro
-    The second method is suitable if you want to minimize the size of your APK, and can be selected by
-    opening the \b Run settings of your project, expanding \b{Deploy Configurations} and removing the
-    tick from the \b{Use local Qt libraries} check box. In this case, your application will have an
-    external dependency called \b{Ministro}. If a user downloads your application, and it is the first
-    application on their device to depend on Ministro, they will be asked to install it before they can
-    run your application. Ministro downloads Qt libraries from a repository of your choice. The
-    repository URL can be set by editing the file \e{android/res/values/libs.xml} which is created by Qt
-    Creator when configuring your project. Ministro will then serve as a central repository for Qt
-    libraries, and several apps can share the libraries to limit the amount of duplication. Note that
-    using this deployment method requires a repository for the libraries you want to distribute.
-
-    \section2 Deployment for Debugging
-    The third method is more convenient when you are simply testing your application on a device
-    physically connected to your development machine (or an emulator). It will copy the Qt libraries
-    into a temporary directory on your device and run the application against these instead. An APK
-    built in this way is not distributable, since it relies on the device being prepared to contain
-    the Qt libraries in the correct location. However, since the Qt libraries are only copied into
-    the device once, it benefits from a faster turn-around time, so it's more suited for testing
-    changes to your application during development. This deployment method can be selected by
-    opening the \b Run settings of your project, expanding \b{Deploy Configurations} and choosing
-    \b{Deploy local Qt libraries}. Make sure the \b{Use local Qt libraries} check box is also ticked.
+    Although Qt Creator supports building both these package formats for you, you could
+    also build them manually when needed. To do so, ensure that the necessary packages
+    and build files are in place. For more detailed information about how the packaging
+    is done, see \l{Deploying an Application on Android}.
 
     \section1 Plugins and Imports Special Considerations
 
-    If an application uses plugins or imports that depend on other modules, these modules have to
+    If an application uses plugins that depend on other modules, these modules must
     be listed in the application's dependencies. This is because Qt Creator does not know ahead
-    of time which imports or plugins your application will end up loading.
+    of time which plugins your application will end up loading.
 
-    For example, if your application's QML code imports \l{Qt Multimedia}, then the Qt Multimedia module
-    must explicitly be made a dependency of the application. You can do this by adding it to the
-    application .pro file:
+    For example, if a plugin depends on \l{Qt Multimedia}, then the Qt Multimedia module
+    must explicitly be made a dependency of the application, otherwise the plugin cannot be
+    loaded. You can do this by adding it to the application's \c .pro file:
 
     \code
     QT += multimedia
     \endcode
 
-    It is also possible to manually enable dependencies on Qt libraries by opening the
-    \gui Run settings of your project, expanding \gui{Package configurations} and selecting the
-    \gui Libraries tab. Manually check the libraries that are dependencies of your project.
+    The automatic deployment tool detects any dependencies on QML modules that are imported
+    from the application's code, but in special case (for instance when QML code is generated
+    by the C++ code), this is not possible. If this generated code imports any special
+    QML modules, they are not detected by the deployment tool and therefore will
+    not be included in the application bundle.
+
+    In these cases, you must add "dummy" QML code importing the same modules as the generated
+    code, so that the automated tool detects the dependencies.
 
     \section1 Text Special Considerations
 
@@ -129,20 +108,6 @@
 
     \section1 OpenGL Special Considerations
 
-    There are some special considerations to be made when OpenGL is used. The platform plugin only
-    supports full screen top-level OpenGL windows. This means that even dialogs and popups will be
-    shown as full screen. There may also be drawing errors if you try to stack windows that have
-    animations or otherwise require updating their UI while they are obscured by another window.
-
-    It is recommended that you try to avoid multiple top-level windows in the case of Android apps, as
-    there is no traditional window system on this platform.
-
-    \note Embedding a QGLWidget inside a widget hierarchy is not supported. When QGLWidget is in use,
-    it must be the top-level widget.
-
-    \note Avoid using the legacy QGLWidget. For embedding OpenGL or Qt Quick content into a
-    widget-based user interface, prefer using QOpenGLWidget and QQuickWidget.
-
     Modern devices often support OpenGL ES 3.0 or 3.1 in addition to 2.0. To get a suitable OpenGL
     context, set the requested version via QSurfaceFormat::setVersion(). Note however that the
     header files are only available in recent API levels, for example to include gl31.h, you need to
@@ -169,12 +134,19 @@
 
     \section1 Supported Architectures
 
-    Qt for Android currently has binaries for ARMv7 and x86. Make sure you select the
-    correct architecture for the device or emulator you are targeting, otherwise your application
-    will crash. The MIPS archictecture is currently not supported by Qt.
+    Qt for Android currently has binaries for armv7a, arm64-v8a, x86 and x86-64.
+
+    If you want to support several different ABIs in your application, the recommendation is
+    to build an Application App Bundle (AAB) containing binaries for each of the ABIs. Based on this,
+    Google Play generates optimized Application Packages (APK) for the device issuing the download
+    request.
+
+    The Application App Bundle is generated by Qt Creator, if the corresponding checkbox for this
+    is selected in the project settings. It can also be built from the command line by using the
+    "aab" Makefile target.
+
+    \code
+    % make aab
+    \endcode
 
-    If you want to support several different architectures in your application, the recommendation is
-    to build separate APKs for each architecture, so that each APK only contains the binaries required
-    for the targeted architecture. For more information about this, see the Android documentation
-    about \l{http://developer.android.com/google/play/publishing/multiple-apks.html}{Multiple APK Support}.
 */
diff --git a/doc/src/platforms/android.qdoc b/doc/src/platforms/android.qdoc
index b35de320..54b2b15c 100644
--- a/doc/src/platforms/android.qdoc
+++ b/doc/src/platforms/android.qdoc
@@ -60,7 +60,7 @@ The following list summarizes what you can do with Qt for Android:
      \l{Qt Android Extras}.
  \li Develop secure applications using OpenSSL library.
  \li Create \l{Android Services}
- \li Create and deploy Application Package (APK) using Qt Creator.
+ \li Create and deploy Application Package using Qt Creator.
 \endlist
 
 The following topics provide more details about how to use Qt for Android:
@@ -135,8 +135,9 @@ The following topics provide more details about how to use Qt for Android:
 
   And that's it: Provided that the path referenced in the \c{project.properties} file is located
   under the \c{Android Package Source Directory}, the deployment tool will copy it into the
-  packaging directory and perform the necessary steps to include it in your \c{APK}. You can
-  now add Java code to your application which accesses the APIs provided by the library project.
+  packaging directory and perform the necessary steps to include it in your \c{APK} or \c{AAB}.
+  You can now add Java code to your application which accesses the APIs provided by the library
+  project.
 
 */