// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \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.
                \list
                    \li \c Bundled: includes all the app's dependencies inside
                        the APK.
                    \li \c Unbundled: excludes native libraries from the APK.
                        The libraries are expected to be present on the target
                        device. The location can be provided either by setting
                        the property
                        \l{cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX}{QT_ANDROID_SYSTEM_LIBS_PREFIX}
                        in your CMake project file, or by defining the path as
                        meta-data in
                        \l {Qt Android Manifest File Configuration}{AndroidManifest.xml}:
                        \badcode
                        <application>
                            <meta-data
                                android:name="system_libs_prefix"
                                android:value="path/to/libraries/"/>
                        </application>
                        \endcode
                        If no path is provided, \c /system/lib/ is used as the
                        default path.
                        \note \c Unbundled deployment does not support
                            incremental builds.
                        \note \c Unbundled deployment not supported when
                            deploying as AAB.
                \endlist
                Default is \c Bundled deployment.
        \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.

    \note androiddeployqt scans the QML files of the project to collect the QML imports.
    However, if you are loading QML code as a QString from C++ at runtime, that might
    not work properly because androiddeployqt won't be aware of it at deploy time.
    To remedy that, you can add a dummy QML file that imports such QML modules that
    are referenced at runtime.

    \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}.
*/
