Android: update android building and getting started pages

Better organize few sections and provide updated commands for building
for Linux and Windows.

Also, remove/update few links and phrases and examples list.

Task-number: QTBUG-87070
Change-Id: I4da9c9cbdbd2fad3072e525e9d3fc21946149c88
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit b24df371cd65fe8ff0ad7fa1e11f06fd13e1d03e)
Reviewed-by: Tarja Sundqvist <tarja.sundqvist@qt.io>

4 files changed, 188 insertions, 86 deletions

diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index eb005557..bb9e038e 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -200,7 +200,7 @@
     \title Android: The Android NDK
 */
 /*!
-    \externalpage https://developer.android.com/studio/index.html
+    \externalpage https://developer.android.com/studio#downloads
     \title Android: Android Studio
 */
 /*!
@@ -300,13 +300,22 @@
     \title OpenJDK
 */
 /*!
-    \externalpage https://adoptopenjdk.net/
+    \externalpage https://adoptopenjdk.net/?variant=openjdk8&jvmVariant=hotspot
     \title AdoptOpenJDK
 */
 /*!
     \externalpage http://www.gradle.org
     \title Gradle
 */
+
+/*!
+    \externalpage https://account.qt.io/downloads
+    \title Qt Downloads
+*/
+/*!
+    \externalpage https://wiki.qt.io/Building_Qt_5_from_Git#Getting_the_source_code
+    \title Getting the source code
+*/
 /*!
     \externalpage https://qtcloudservices.com/
     \title Qt Cloud Services
diff --git a/doc/src/platforms/android/android-building.qdoc b/doc/src/platforms/android/android-building.qdoc
index 89fc657b..8b88efa4 100644
--- a/doc/src/platforms/android/android-building.qdoc
+++ b/doc/src/platforms/android/android-building.qdoc
@@ -1,4 +1,4 @@
-/****************************************************************************
+/****************************************************************************
 **
 ** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
@@ -34,7 +34,8 @@
     going through this guide. Accomplish the tasks in
     \l{Getting Started with Qt for Android} first.
 
-    You can download the Qt 5 sources from the \l Downloads page.
+    You can download the Qt 5 sources from the \l {Qt Downloads} page, or follow
+    the wiki guide for \l {Getting the source code}.
 
     \section1 Building on Linux
 
@@ -54,7 +55,7 @@
 
     \section3 Using Qt Creator
 
-    For more information, see\l{Qt Creator: Connecting Android Devices}{Connecting Android Devices}.
+    For more information, see \l{Qt Creator: Connecting Android Devices}{Connecting Android Devices}.
 
     \section3 Using Android Studio
 
@@ -63,6 +64,11 @@
     more information, see \l{Android: Update your tools with the SDK Manager}
     {Android Studio documentation}.
 
+
+    \section1 Building on Linux
+
+    To build Qt for Android under a Linux environment, follow the steps below:
+
     \section2 Installing the License File
 
     If you use Qt with a commercial license, the Qt tools look for a local license file.
@@ -78,17 +84,21 @@
 
     \section2 Unpacking the Archive
 
-    Unpack the archive if you have not done so already. For example,
-    if you have the \c{qt-everywhere-opensource-src-%VERSION%.tar.gz}
-    package, type the following commands at a command line prompt:
+    If you have downloaded the source code archive from \l {Qt Downloads}, then
+    unpack the archive if you have not done so already. For example, if you have
+    the \c{qt-everywhere-src-%VERSION%.tar.xz} package, type the following commands
+    at a command line prompt:
 
     \snippet snippets/code/doc_src_installation.qdoc 0
 
-    This creates the directory \c{/tmp/qt-everywhere-opensource-src-%VERSION%}
+    This creates the directory \c{/tmp/qt-everywhere-src-%VERSION%}
     containing the files from the archive. We only support the GNU version of
     the tar archiving utility. Note that on some systems it is called gtar.
 
-    \section2 Configuring and Building
+    Otherwise if you cloned the source code from Git, the source will be under
+    \e qt5 folder.
+
+    \section2 Configuring and Building on Linux
 
     Set the following environment variables, and add them to your \c{PATH};
     preferably at the end of \c{~/.profile}:
@@ -98,28 +108,25 @@
     export PATH=$JAVA_HOME/bin:$PATH
     \endcode
 
-    \note JDK 11 or below must be used to properly build Qt for Android.
+    \note JDK 11 or earlier must be used to properly build Qt for Android.
 
-    \note We use \l{OpenJDK} here, but you can other JDK alternatives such as \l{AdoptOpenJdk}.
+    \note We use \l{OpenJDK} here, but you can also use other JDK alternatives
+    such as \l{AdoptOpenJDK}.
 
-    To configure Qt for Android, run the following:
+    To configure Qt for Android, create a shadow build directory to keep the source
+    directory clean:
 
     \badcode
-    cd /tmp/qt-everywhere-opensource-src-%VERSION%
-    ./configure -xplatform android-clang -prefix </path/to/install> --disable-rpath -nomake tests -nomake examples -android-ndk <path/to/sdk>/ndk/<ndk_version> -android-sdk <path/to/sdk> -no-warnings-are-errors
-    \endcode
-
-    The \l{Qt Configure Options}{Configure Options} page contains more information
-    about the configure options.
-
-    You may provide the \c{-android-abis} parameter to limit the Android ABIs
-    being built, with either of: \e{armeabi-v7a}, \e{arm64-v8a}, \e{x86}, or \e{x86_64}:
+    mkdir <path_to_build_dir>/build-qt
+    cd <path_to_build_dir>/build-qt
 
-    \badcode
-    -android-abis armeabi-v7a,arm64-v8a
+    <path_to_qt_source>/configure -xplatform android-clang -prefix </path/to/install> -disable-rpath -nomake tests -nomake examples -android-ndk <path/to/sdk>/ndk/<ndk_version> -android-sdk <path/to/sdk> -no-warnings-are-errors
     \endcode
 
-    If the parameter is not specified, Qt is built for all supported ABIs.
+    \l{Qt Configure Options} contains more information about the configure options.
+
+    You can customize your build configuration in a more advanced manner. For
+    more information, see \l {Advanced Build Arguments}.
 
     To build the configured Qt code, run the following command:
     \badcode
@@ -140,44 +147,55 @@
 
     \section1 Building on Windows
 
-    First, you can use \l {Android: Android Studio}{Android Studio} to download
-    and install the Android SDK packages required for developing applications
-    for Android. For more information, see \l{Android: Update your tools with the SDK Manager}
-    {Android Studio documentation}.
-
+    To build Qt for Android under a Windows environment, follow the steps below:
 
     \section2 Preparing the Build Environment
 
     Install the following:
 
     \list
-        \li \l{Perl}
         \li A JDK package such as \l{AdoptOpenJDK}, \l{Java SE Development Kit}{JDK},
             or \l{OpenJDK}.
         \li \b {MinGW 7.3} toolchain
+        \li \l{Perl}
     \endlist
 
     Then set the respective environment variables from the \uicontrol{Environment Variables}
-    system UI, or from the build command line prompt as:
+    system UI, or from the build command line prompt. For the default \c {Command prompt}:
 
     \badcode
-    set "JDK_ROOT=<JDK_ROOT_PATH>\bin\"
-    set "MINGW_ROOT=<MINGW_ROOT_PATH>"
-    set "PERL_ROOT=<PERL_ROOT_PATH>"
+    set JDK_ROOT=<JDK_ROOT_PATH>\bin
+    set MINGW_ROOT=<MINGW_ROOT_PATH>\bin
+    set PERL_ROOT=<PERL_ROOT_PATH>\bin
+    set PATH=%MINGW_ROOT%;%PERL_ROOT%;%JDK_ROOT%:%PATH%
     \endcode
 
     Then, in the command line prompt, verify that:
 
-    \list
-        \li \c{where gcc.exe} lists \e{<MINGW_ROOT>.exe} first before \e{<PERL_ROOT>.exe}.
-        \li \c{where mingw32-make.exe} lists \e{<MINGW_ROOT32>-make.exe} first.
-        \li \c{where javac.exe} lists \e{<JDK_ROOT>} first.
-    \endlist
+    \badcode
+    where gcc.exe
+    \endcode
+
+    The command should list gcc.exe under the path \e {<MINGW_ROOT>} first.
+
+    \badcode
+    where mingw32-make.exe
+    \endcode
+
+    The command should list mingw32-make.exe under the path \e {<MINGW_ROOT>} first.
+
+    \badcode
+    where javac.exe
+    \endcode
+
+    The command should list javac.exe under the path \e {<JDK_ROOT>} first.
 
-    \note Currently, it is not possible to use Microsoft's compilers to build
-    the Windows host tools for Qt Android.
+    \note JDK 11 or earlier must be used to properly build Qt for Android.
 
-    \section2 Setting a Commercial License
+    \note Qt for Android does not support building with Microsoft Visual C++ (MSVC),
+    we only support building with MinGW.
+
+    \section2 Installing the License File
 
     If you have a commercially licensed Qt, install your license file. If you're using
     a binary installer or the commercial Qt Creator, your licenses are automatically
@@ -188,21 +206,26 @@
     name, you need to set the \c QT_LICENSE_FILE environment variable to the respective
     file path.
 
-    \section2 Building the Sources
+    \section2 Configuring and Building on Windows
 
-    Next, unpack the archive. Uncompress the files into the directory in which
-    you want Qt installed, for example: \c{C:\Qt\%VERSION%}. This install path must not contain any
-    spaces or Windows-specific file system characters.
+    If you have downloaded the source code archive from \l {Qt Downloads}, unpack
+    the archive. Uncompress the files into a temporary folder, for example,
+    \c {C:\Qt\Build\Src_%VERSION%}. This path must not contain any spaces or
+    Windows-specific file system characters.
 
     Run the following command to configure Qt:
 
     \badcode
-    cd <decompressed_source_code_folder>
-    configure.bat -prefix <\path\to\install> -platform win32-g++ -opengl es2 -xplatform android-clang -nomake tests -nomake examples -android-sdk <ANDROID_SDK_PATH> -android-ndk <ANDROID_SDK_PATH>\ndk\<ndk_version>
+    mkdir C:\Qt\Build\build-qt
+    cd C:\Qt\Build\build-qt
+
+    ..\Src_%VERSION%\configure.bat -platform win32-g++ -xplatform android-clang -prefix <\path\to\install> -nomake tests -nomake examples -android-sdk <ANDROID_SDK_PATH> -android-ndk <ANDROID_SDK_PATH>\ndk\<ndk_version> -android-ndk-host windows-x86_64 -no-warnings-are-errors
     \endcode
 
-    The \l{Qt Configure Options}{Configure Options} page contains more information
-    about the configure options.
+    \l{Qt Configure Options} contains more information about the configure options.
+
+    You can customize your build configuration in a more advanced manner. For
+    more information, see \l {Advanced Build Arguments}.
 
     To build the configured Qt for Android code, run the following:
 
@@ -218,4 +241,63 @@
     \badcode
     mingw32-make.exe install
     \endcode
+
+    \section1 Advanced Build Arguments
+
+    You may provide the \c{-android-abis} parameter to limit the Android ABIs
+    being built, with either of: \e{armeabi-v7a}, \e{arm64-v8a}, \e{x86}, or \e{x86_64}:
+
+    \badcode
+    -android-abis armeabi-v7a,arm64-v8a
+    \endcode
+
+    \note If the parameter is not specified, Qt is built for all supported ABIs.
+
+    Qt for Android contains Java code which is compiled into *.jar files with
+    \e javac. To set the \e javac version for source and target, use \e -android-javac-source
+    and \e -android-javac-target respectively:
+
+    \badcode
+    -android-javac-source 8 -android-javac-target 8
+    \endcode
+
+    To debug Qt with a developer build instead of a prefix build, use the following
+    instead of \c -prefix argument:
+
+    \badcode
+    -developer-build
+    \endcode
+
+    A developer build is meant to be used directly from the build directory.
+
+    \note A developer build takes more storage than a prefix build.
+
+    \section2 Building Separate Modules
+
+    It is possible to build specific Qt modules only. There are two options:
+
+    \list
+        \li Use the configured \e qt5 build with the following command:
+            \code
+            make -j$(nproc) module-qtbase
+            \endcode
+
+            The to install those modules, use:
+
+            \code
+            make -j$(nproc) module-qtbase-install_subtargets
+            \endcode
+
+            \note On Windows, use \e mingw32-make.exe instead.
+
+        \li Configure and build \e qtbase only, then use the resulting \e qmake to build
+            any other module. The only difference is that the configure script in
+            \e qtbase directory has to be used:
+
+            \badcode
+            mkdir <path_to_build_dir>/build-qt/qtbase
+            cd <path_to_build_dir>/build-qt/qtbase
+            <path_to_qt_source>/qtbase/configure [...]
+            \endcode
+    \endlist
 */
diff --git a/doc/src/platforms/android/android.qdoc b/doc/src/platforms/android/android.qdoc
index 6589e735..13a7ab20 100644
--- a/doc/src/platforms/android/android.qdoc
+++ b/doc/src/platforms/android/android.qdoc
@@ -98,10 +98,10 @@ In order to use \l{Qt for Android}, you need the following:
         is required to build Android apps. Other alternatives such as \l{OpenJDK}
         for Linux or \l{Java SE Development Kit} for Windows are also supported.
 
+        \note JDK 11 or earlier must be used when using Qt for Android.
+
     \li \l{Gradle} for building application packages (APK) and app bundles
         (AAB) for Android devices. Gradle is delivered with Qt 5.9, and later.
-        Because Gradle scripts are not delivered with  Android SDK tools since
-        version 26.0.0, they are delivered with Qt 5.9 and 5.6.3.
 
         \note Using Ant to build APKs is no longer supported.
 
@@ -132,49 +132,53 @@ In order to use \l{Qt for Android}, you need the following:
     \li \l{Android: The Android NDK}{The Android NDK}
         can be installed using the \c sdkmanager tool. Alternatively, you can
         download it and extract it manually to a path of your choosing.
-        Different Qt versions depend on different NDK versions, as listed below:
-
-        \list
-            \li Qt 5.14.0 or later, Qt 5.13.2 or later, and Qt 5.12.6 or later
-            \list
-                \li NDK r20b or r21
-                \li \e android-clang
-                \li \note Qt 5.14.0 and 5.14.1 with NDK r21 have a bug fixed at
-                    \l {QTBUG-81461}.
-            \endlist
-            \li Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1
-            \list
-                \li NDK r19c
-                \li \e android-clang
-            \endlist
-            \li Qt 5.11 and below
-                \list
-                    \li NDK r10e
-                    \li GCC toolchain
-                \endlist
-        \endlist
 \endlist
 
-After downloading and unpacking the SDK tools, install the essential packages
-using \l {Android: Android Studio}{Android Studio}, the Qt Creator
-\l{Qt Creator: Managing Android SDK Packages}{SDK Manager UI}, or the
-\l{Android: sdkmanager}{sdkmanager} command line tool.
+Different Qt versions depend on different NDK versions, as listed below:
+
+\table
+    \header
+        \li Qt version
+        \li NDK version
+        \li Toolchain
+    \row
+        \li Qt 5.14.0 or later
+            Qt 5.13.2 or later
+            Qt 5.12.6 or later
+        \li NDK r20b or r21
+        \li \e android-clang
+    \row
+        \li Qt 5.12.0 to 5.12.5
+            Qt 5.13.0 to 5.13.1
+        \li NDK r19c
+        \li \e android-clang
+    \row
+        \li Qt 5.11 and earlier
+        \li NDK r10e
+        \li \e GCC toolchain
+\endtable
+
+\li \note Qt 5.14.0 and 5.14.1 with NDK r21 have a bug fixed at \l {QTBUG-81461}.
 
 \note Make sure to unpack the Android SDK and NDK to a writeable location that Qt Creator
 can access later. Otherwise, Qt Creator won't be able to use \c sdkmanager or find all
 components even if they were installed manually.
 
-\section2 Updating the Android SDK
+\section2 Installing the Android SDK Essentials
 
-Use the \c sdkmanager command line tool to update the packages list and then
-install the essential packages:
+After downloading and unpacking the Commandline SDK Tools, use the \c sdkmanager
+command line tool to install the essential packages:
 
 \badcode
 cd <ANDROID_SDK_ROOT>/tools/bin/
 ./sdkmanager --sdk_root=<ANDROID_SDK_ROOT> --install "cmdline-tools;latest"
-./sdkmanager --sdk_root=<ANDROID_SDK_ROOT> --install "platform-tools" "platforms;android-29" "build-tools;29.0.2" "ndk;21.1.6352462"
+./sdkmanager --sdk_root=<ANDROID_SDK_ROOT> --install "platform-tools" "platforms;android-29" "build-tools;29.0.2" "ndk;21.3.6528147"
 \endcode
 
+\l {Android: Android Studio}{Android Studio} or the Qt Creator's
+\l{Qt Creator: Managing Android SDK Packages}{SDK Manager UI} can also be used
+to install the essential SDK packages.
+
 To use the \l {Android: Android Emulator}{Android Emulator}, install it by
 entering:
 
diff --git a/doc/src/platforms/android/examples-android.qdoc b/doc/src/platforms/android/examples-android.qdoc
index 2b147909..f96b3dcd 100644
--- a/doc/src/platforms/android/examples-android.qdoc
+++ b/doc/src/platforms/android/examples-android.qdoc
@@ -58,16 +58,23 @@
     \endlist
 
     \l {Qt Android Extras} is an Android specific module used to integrate Qt
-    API with Java API by enabling communication between Qt code {C++ and QML}
-    and Java code. The following examples demonstrate using the module:
+    API with Java API by enabling communication between Qt code (C++ and QML)
+    and Java code. The following examples demonstrate some of the features of
+    the module:
 
     \list
-        \li \l{Qt Notifier} .demonstrates how to call Java code from an
+        \li \l{Qt Notifier} demonstrates how to call Java code from an
             Android application.
         \li \l{Qt JNI Messenger} demonstrates communication between Java code
-            and QML or C++ using NJI calls.
+            and QML or C++ using JNI calls.
+        \li \l{Android Custom Activity} demonstrates working with custom Android activities.
+        \li \l{Qt JNI Music List} demonstrates how to exchange data from complex Java objects.
+        \li \l{Android Service with Qt Remote Objects} demonstrates how to run an Android service,
+            and how to communicate between the service and the app using Qt Remote Objects.
     \endlist
 
+    For the full list examples, see \l {Qt Android Extras Examples}.
+
     \section1 Qt Quick and QML Examples for Android
 
     The following Qt Quick and QML examples are useful when developing