Docs: Move manifest and androiddeployqt docs to where code lives

Removed content describing androiddeployqt from deployment-android.html
to androiddeployqt.html,the qdoc source now living in qtbase.
Docs src locations added to the qtcore.qdocconf.

Task-number: QTBUG-97842
Pick-to: 6.2
Change-Id: I94783520280098ce1ab35f335a644bea70b8131a
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>

3 files changed, 539 insertions, 1 deletions

diff --git a/src/android/templates/doc/src/android-manifest-file-configuration.qdoc b/src/android/templates/doc/src/android-manifest-file-configuration.qdoc
new file mode 100644
index 0000000000..24faef4c7b
--- /dev/null
+++ b/src/android/templates/doc/src/android-manifest-file-configuration.qdoc
@@ -0,0 +1,290 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page android-manifest-file-configuration.html
+\title Qt Android Manifest File Configuration
+\ingroup androidplatform
+\brief Provides details on the AndroidManifest.xml configuration.
+\previouspage android-openssl-support.html
+\nextpage android-services.html
+
+The Android Manifest is an XML file necessary for any Android app. It contains
+app configuration for different settings and features that the app use, as well
+as details on the app itself, such as, package name, app name, version, etc.
+Permissions and hardware features can also be set from the manifest.
+
+Qt for Android maintains a version of \c {AndroidManifest.xml} with default
+configuration that include features, permissions and other configuration
+used by the build system which are needed for building and running Qt apps
+on Android.
+
+\section1 Qt Project to Manifest Configuration
+
+Qt defines some \l {Android: App Manifest <meta-data>}{meta-data} that is passed
+from the build systems and to \l {Deploying an Application on Android}{androiddeployqt}
+which populates the manifest with the correct values without explicitly setting
+these in the manifest file. Such \l {Android: App Manifest <meta-data>}{meta-data}
+is assigned a value in the form \c {"-- %%INSERT_VALUE%% --"}, for example:
+
+\badcode
+<manifest ...
+    android:versionCode="-- %%INSERT_VERSION_CODE%% --"
+    ...
+</manifest>
+\endcode
+
+This would be populated with the version code that is set in, for example,
+\c CMake.
+
+\section1 Qt Default Configuration
+
+Qt sets the following manifest configuration by default:
+
+\table
+\header
+    \li Section
+    \li Option
+    \li Description
+\row
+    \li {1, 5} \l {Android: App Manifest <manifest>}{<manifest>}
+    \li package
+    \li Sets the package name. Default: \c {org.qtproject.example.app_name}.
+\row
+    \li \c {android:installLocation}
+    \li Sets the app's installation location, whether internal or external storage.
+        Default: \c auto.
+\row
+    \li android:versionCode
+    \li Sets the internal version code. Populated from \c ANDROID_VERSION_CODE (qmake)
+        and \c QT_ANDROID_VERSION_CODE (CMake). Default: \c 1.
+\row
+    \li android:versionName
+    \li Sets the public version name. Populated from \c ANDROID_VERSION_NAME (qmake)
+        and \c QT_ANDROID_VERSION_NAME (CMake). Default: \c {1.0}.
+\row
+    \li \c {<supports-screens>}
+    \li Sets the screen sizes that the app supports,
+        default values are \c anyDensity, \c largeScreens,
+        \c normalScreens, and \c smallScreens.
+\row
+    \li {1, 5} \l {Android: App Manifest <application>}{<application>}
+    \li android:name
+    \li The application class name. Default:
+        \c {org.qtproject.qt.android.bindings.QtApplication}.
+\row
+    \li android:label
+    \li The application name label. Default: the Qt project's target name.
+\row
+    \li android:extractNativeLibs
+    \li Extracts the native C++ libraries on installation. Default: \c true.
+\row
+    \li android:hardwareAccelerated
+    \li Sets hardware acceleration preference. Default: \c true.
+\row
+    \li android:requestLegacyExternalStorage
+    \li Whether to use Android scoped storage. Default \c true.
+\row
+    \li {1, 6} \l {Android: App Manifest <activity>}{<activity>}
+    \li android:name
+    \li The activity class name. Default: \c {org.qtproject.qt.android.bindings.QtActivity}.
+\row
+    \li android:label
+    \li The activity name label. Default: the Qt project's target name.
+\row
+    \li android:configChanges
+    \li Lists configuration changes that the activity handles. Default:
+        \c orientation, \c uiMode, \c screenLayout, \c screenSize,
+        \c smallestScreenSize, \c layoutDirection, \c locale, \c fontScale,
+        \c keyboard, \c keyboardHidden, \c navigation, \c mcc, \c mnc, \c density.
+\row
+    \li android:launchMode
+    \li The method used to launch the activity. Default: \c singleTop.
+\row
+    \li android:screenOrientation
+    \li The orientation of the activity's display on the device. Default: \c unspecified.
+\row
+    \li <intent-filter>
+    \li Specifies the types of intents that the activity can respond to. Default:
+        \badcode
+        <action android:name="android.intent.action.MAIN"/>
+        <category android:name="android.intent.category.LAUNCHER"/>
+        \endcode
+\endtable
+
+\section1 Qt Specific Meta-data
+
+In addition to the default manifest configuration that Qt sets, Qt defines
+some meta-data that is valid for Qt apps only. Such meta-data is usually
+under the \c <activity> section in the form:
+
+\badcode
+<meta-data
+    android:name="meta-data-name"
+    android:value="meta-data-value" />
+\endcode
+
+The following is a list of such meta-data defined by Qt:
+
+\table
+\header
+    \li meta-data name
+    \li Description
+\row
+    \target android.app.lib_name
+    \li android.app.lib_name
+    \li The filename of the native C++ library that is used by the activity.
+        \note This attribute is mandatory and shouldn't be removed.
+        Default: the Qt project's target name.
+\row
+    \li android.app.extract_android_style
+    \li The method used to extract the native Android Style information.
+        For more information, see \l {Style Extraction}.
+        Default: \c minimal.
+\row
+    \target android.app.background_running
+    \li android.app.background_running
+    \li Sets whether the app keeps running tasks in the background.
+        Setting this to \c true is the equivalent of setting the environment
+        variable \c QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED to \c 0.
+        Default: \c false.
+
+        \warning Setting this to \c true may cause unexpected crash if the
+        application tries to draw after \l {QGuiApplication::applicationStateChanged()}
+        signal is sent with a \l {Qt::ApplicationSuspended} state.
+\row
+    \target android.app.arguments
+    \li android.app.arguments
+    \li Sets a list of arguments to pass to the app \c {"arg1 arg2"}.
+        Populated from \c ANDROID_APPLICATION_ARGUMENTS (qmake) and
+        \c QT_ANDROID_APPLICATION_ARGUMENTS (CMake).
+        Default: not set.
+\row
+    \li android.app.splash_screen_drawable_portrait
+    \li Sets a drawable for a splash screen specific to portrait mode.
+        For example: \c {android:resource="@drawable/splash_portrait"}.
+        Default: not set.
+\row
+    \li android.app.splash_screen_drawable_landscape
+    \li Sets a drawable for a splash screen specific to landscape mode.
+        For example: \c {android:resource="@drawable/splash_landscape"}.
+        Default: not set.
+\row
+    \li android.app.splash_screen_drawable
+    \li Sets a drawable for a splash screen at the start of the app.
+        \note Orientation specific splash screens are checked first,
+        if not set, this is used instead.
+        For example: \c {android:resource="@drawable/splash"}.
+        Default: not set.
+\row
+    \li android.app.splash_screen_sticky
+    \li Sets whether the splash screen stays visible until explicitly hidden
+        by the app.
+        For more information, see
+        \l {QNativeInterface::}{QAndroidApplication::hideSplashScreen()}.
+\row
+    \target android.app.system_libs_prefix
+    \li android.app.system_libs_prefix
+    \li Specifies a custom system library path to use for library loading lookup.
+        This is necessary when running as a system app.
+        Default: \c {/system/lib/}.
+\endtable
+
+\section2 Meta-data in Services
+
+Some meta-data attributes can also be used in \l {Android Services}{Services}.
+The main ones are:
+
+\list
+    \li \l {android.app.lib_name}
+    \li \l {android.app.background_running}
+    \li \l {android.app.arguments}
+    \li \l {android.app.system_libs_prefix}
+\endlist
+
+\section2 Qt Permissions and Features
+
+Different Qt modules might require some Android permissions or features to
+function properly, for example, Camera permission in \l {QtMultimedia}.
+l{The androiddeployqt Tool} takes care of including such requirements into the
+Android manifest during the build. Qt defines the following lines into the
+manifest, which they get replaced by
+the actual values:
+
+\badcode
+<manifest ...
+    <!-- %%INSERT_PERMISSIONS -->
+    <!-- %%INSERT_FEATURES -->
+    ...
+</manifest>
+\endcode
+
+\note If those lines are removed from the project manifest, Qt won't be
+able to include the correct permissions. So some functionalities
+might not work properly.
+
+\section2 Style Extraction
+
+Qt uses different methods to determine how Qt Widgets and Qt Quick Controls
+should be styled:
+
+\list
+    \li \c default or \c full: when using Qt Widgets or Qt Quick Controls 1.
+        \note This method uses some Android non-SDK interfaces, that are being
+        restricted and removed by Google starting from Android 9.0 (API 28).
+        For that reason, this is not recommended for Android 9.0 or greater.
+    \li \c minimal: when using Qt Quick Controls 2 and no Qt Widgets or Qt Quick
+        Controls 1. This is faster than using the default or full options.
+    \li \c none: no style extraction.
+\endlist
+
+\section1 Qt Manifest before 6.2 Release
+
+Versions of Qt earlier than 6.2 used to have an additional set of meta-data
+defined by Qt. These attributes used to manage dependencies and some were
+used by the discontinued \c Ministro service. With Qt 6.2, they should be removed.
+Here is a list of these attributes:
+
+\list
+    \li android.app.qt_sources_resource_id
+    \li android.app.repository
+    \li android.app.bundled_libs_resource_id
+    \li android.app.bundle_local_qt_libs
+    \li android.app.use_local_qt_libs
+    \li android.app.libs_prefix
+    \li android.app.load_local_libs_resource_id
+    \li android.app.load_local_jars
+    \li android.app.static_init_classes
+    \li android.app.qt_libs_resource_id
+    \li android.app.ministro_not_found_msg
+    \li android.app.ministro_needed_msg
+    \li android.app.fatal_error_msg
+\endlist
+
+For more information on the Android Manifest, see
+\l{Android: App Manifest}{Android App Manifest}.
+*/
diff --git a/src/corelib/doc/qtcore.qdocconf b/src/corelib/doc/qtcore.qdocconf
index cb622647e8..93db5491c2 100644
--- a/src/corelib/doc/qtcore.qdocconf
+++ b/src/corelib/doc/qtcore.qdocconf
@@ -32,7 +32,9 @@ depends                 = *
 
 headerdirs  += ..
 
-sourcedirs  += ..
+sourcedirs  += .. \
+                ../../tools/androiddeployqt \
+                ../../android/templates
 
 exampledirs += \
                ../ \
diff --git a/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc b/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc
new file mode 100644
index 0000000000..b77d3182c5
--- /dev/null
+++ b/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc
@@ -0,0 +1,246 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page android-deploy-qt-tool.html
+    \brief An overview of the androiddeployqt tool and how to use it.
+    \title The androiddeployqt Tool
+
+    \target androiddeployqt
+    Building an application package is complex, so Qt comes with a tool which
+    handles the work for you. The steps described in
+    \l{Deploying an Application on Android} are handled by the androiddeployqt
+    tool.
+
+    \section1 Prerequisites 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.
+
+    \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:
+
+
+    \badcode
+    mkdir build-project
+    cd build-project
+    \endcode
+
+    Followed by:
+
+    For qmake:
+    \badcode
+    qmake ../project/project.pro
+    make -j$(nproc)
+    make -j$(nproc) apk_install_target
+    \endcode
+
+    For CMake:
+    \badcode
+    cmake --build
+    \endcode
+
+    \section1 Command Line Arguments
+
+    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. Optionally, set the following environment
+                variables to conceal the signing information
+                \c QT_ANDROID_KEYSTORE_PATH, \c QT_ANDROID_KEYSTORE_ALIAS,
+                \c QT_ANDROID_KEYSTORE_STORE_PASS, and \c QT_ANDROID_KEYSTORE_KEY_PASS.
+                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 \c androiddeployqt without deploying it the device, run the following:
+
+    \badcode
+   .androiddeployqt --input $BUILD_DIR/android-project-deployment-settings.json --output $ANDROID_BUILD_DIR
+    \endcode
+
+    To deploy the built package to the device:
+
+    \badcode
+    androiddeployqt --verbose --output $ANDROID_BUILD_DIR --no-build --input $BUILD_DIR/android-project-deployment-settings.json --gradle --reinstall --device <adb_device_id>
+    \endcode
+
+    \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:
+
+    \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 \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.
+    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 \l androiddeployqt on it with no modifications
+    and get a working Qt for Android application.
+
+    There are two important environment variables used by Qt:
+
+    \list
+        \li \c{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.
+        \li \c{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.
+    \endlist
+
+    \note Qt Creator sets these variables by default.
+
+    There are a set of \c qmake or \c 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:
+
+    \list
+        \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_MIN_SDK_VERSION}
+        \li \l{ANDROID_TARGET_SDK_VERSION}
+        \li \l{JAVA_HOME}
+    \endlist
+
+    Also, the following \c qmake variables are primarily useful when writing a Qt module, and not
+    normal applications:
+
+    \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 runs \c androiddeployqt 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}.
+*/