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

/*!
    \page deployment-android.html
    \title Deploying an Application on Android
    \brief The technical steps required to deploy a Qt application on Android.
    \ingroup androidplatform
    \previouspage examples-android.html
    \nextpage android-openssl-support.html


    This article describes the technical steps required to deploy a Qt
    application to an Android device.

    \note \l{The androiddeployqt Tool} automates this process.

    \section1 Android 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 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.

    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.

    For more information on the AAB format, see
    \l{Android: App Bundles}{the Android App Bundles}.

    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.

    \section2 Generating the Application Bundle

    It is recommended to use Qt Creator or the Makefile created by qmake or CMake
    to create the application bundle.

    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.

    \note If you prefer building Android packages from the command line, see
    \l{Building the Android Application}.

    \section1 Android Package Templates

    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}:

    \badcode
    android {
        ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android

        DISTFILES += \
            android/AndroidManifest.xml \
            android/build.gradle \
            android/res/values/libs.xml
    }
    \endcode

    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 -j$(nproc) apk_install_target
    \endcode

    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 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. The Android Manifest is also used to define
    \l{Android Services}, and custom \l{Android: Introduction to Activities}{Android Activities}.

    For more information about the \c AndroidManifest.xml, see
    \l{Qt Android Manifest File Configuration}{Android Manifest file documentation}.

    \section2 Java Code

    Under \c{$Qt_install_dir/src/android/java/src/org/qtproject/qt/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 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.

    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
    @Override
    public void onActivityReenter(int resultCode, Intent data)
    {
        // Do something
        return super.onActivityReenter(resultCode, data);
    }
//@ANDROID-21
    \endcode

    \section2 Resources

    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 libs.xml

    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{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

    \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 Resources

    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.

    \section2 Custom Java Code

    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 Android Notifier}{Qt Android Notifier Example}.

    When using Qt Creator, add the Java files to your project using \l DISTFILES,
    so they are visible under the project files.

    \section2 Assets

    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}.

    \note Using \l{The Qt Resource System} entails having \c{.qrc} files bundled
        in the \c{.so} files which must be unpacked first to be loaded by the
        linker, while the Android assets are compressed in the \e{.apk} and can
        be directly used in your application. That means using the Android assets
        can take up less space, but it's not a cross-platform solution with Qt.

    \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{Qt Creator: Signing Android Packages}
    {Signing Android packages}.
*/
