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

/*!
    \page creator-how-to-deploy-android-apps.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Deploy applications to Android

    Because bundling applications as APK packages is not simple, Qt has the
    \l {The androiddeployqt Tool}{androiddeployqt} tool. When you deploy an
    application using a \e {Qt for Android kit}, \QC runs the tool to
    create the necessary files and to bundle them into an APK. For more
    information, see \l{Android Package Templates}.

    To view the packages that the \c androiddeployqt tool created, select
    \uicontrol {Open package location after build}.

    \section1 Specify deployment settings

    To specify settings for deploying applications, go to \uicontrol Projects >
    \uicontrol {Deploy Settings} and select a deploy configuration in
    \uicontrol {Active deployment configuration}.

    \image {qtcreator-android-deployment-settings.webp} {Deploy Settings tab in Projects}

    To add deploy configurations for a project, select \uicontrol Add.

    To rename the current deployment method, select \uicontrol Rename.

    To remove the current deployment method, select \uicontrol Remove.

    \details {About Android deploy settings}

    Android applications are packaged as ZIP files called Application Packages
    (APK), Android App Bundles (AAB), or Android Archives (AAR). You can
    install and run APK files on a device. You can upload AAB files to the
    Google Play Store.

    \l{Qt for Android} has binaries for armv7a, arm64-v8a, x86, and x86-64.
    To support several different ABIs in your application, build an AAB that
    has binaries for each of the ABIs. The Google Play Store uses the AAB
    to generate optimized APK packages for the devices that request downloads
    and automatically signs them with your publisher key.

    \QC supports the following methods of deployment for Android applications:

    \list
        \li As a stand-alone, distributable application package (APK).
        \li As an app bundle (AAB) for distribution in the Google Play store.
        \li As an AAR, which fundamentally differs from the APK and AAB formats
            in that it is an Android library. You can use it as a dependency for
            an Android app module, but you cannot run it alone.

            All Qt versions do not support AABs. Qt 6.3.0 and later support
            multi-abi builds for applications when you build with CMake. AARs
            are supported from Qt 6.8.0 onwards. For more information, see
            \l{Deploying an Application on Android}.
    \endlist

    To specify settings for application packages, go to \uicontrol Projects >
    \uicontrol {Build Settings} > \uicontrol {Build Android APK} and select
    \uicontrol Details.

    For more information about specifying additional start options for
    applications, see \l{Specify Android run settings}.

    \enddetails

    \section1 Select a device for deployment

    \QC deploys the packages on the Android device that you select in the
    kit selector. To add devices, select \uicontrol Manage.

    \image {qtcreator-kit-selector.webp} {Kit selector}

    \section1 Remove previous installations

    To remove previously installed files from the device, go to
    \uicontrol Projects > \uicontrol {Deploy Settings} and select
    \uicontrol {Uninstall the existing app before deployment}.

    \section1 Install pre-built APKs

    To install a pre-built APK, such as a 3rd-party application, on a device,
    go to \uicontrol Projects > \uicontrol {Deploy Settings} and select
    \uicontrol {Install an APK File}.

    \sa {Android}{How to: Develop for Android}, {Developing for Android}
*/

/*!
    \page creator-how-to-package-android-apps.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Create Android packages

    To specify settings for the \c androiddeployqt tool, go to
    \uicontrol Projects > \uicontrol {Build Settings} >
    \uicontrol {Build Android APK} and select \uicontrol Details.

    \image {qtcreator-build-settings-android-apk.webp} {Build Android APK step in the Build Settings tab in Projects}

    The \c androiddeployqt tool creates APKs based on the settings. For more
    information about the available options, see \l{androiddeployqt}.

    You can view information about what the \c androiddeployqt tool is doing in
    \l {Compile Output}. To view more information, select
    \uicontrol {Verbose output}.

    Select \uicontrol {Add debug server} to include the debug server binary
    into a package.

    \section1 Select API Level

    In the \uicontrol {Android build platform SDK} field, select the
    \l{What is API Level?}{API level} to use for building the application.
    Usually, you should select the highest API level available.

    Usually, you should use the highest version of the Android SDK
    build tools for building. If necessary, select another version
    in the \uicontrol {Android build-tools version} field.

    \section1 Build AABs

    For testing the application locally, use the APK format because
    \QC can install and run the package on the device. For distribution
    to the Google Play store, create an AAB by selecting
    \uicontrol {Build Android App Bundle (*.aab)}.

    When building with CMake, you can view the selected ABIs in
    \uicontrol {Initial Configuration} in the \uicontrol CMake section.
    You can set additional ABIs as values of the \c ANDROID_ABI key:

    \image {qtcreator-android-cmake-settings.png} {CMake settings for building AABs}

    When building with Qbs or qmake, you can select the ABIs in the
    \uicontrol ABIs field in the \uicontrol {Build Steps}:

    \image {qtcreator-android-build-steps.png} {qmake settings for building AABs}

    \section1 Build AARs

    Select the AAR target in the \uicontrol {Build Steps} section.

    \image {qt-creator-android-build-aar.webp} {Selecting the AAR target}

    \sa {Android}{How to: Develop for Android}, {Developing for Android}
*/

/*!
    \page creator-how-to-sign-android-apps.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Sign Android packages

    To publish your application, you must sign it by using a \e {public-private
    key pair} that consists of a \e certificate and a corresponding
    \e {private key} and is identified by an \e alias. The key pair is used to
    verify that the future versions of your application are actually created by
    you.

    \warning Keep the key pair in a safe place and take backup copies because
    you cannot update the application if you lose the key pair.

    You can use \QC to generate a keystore and a \e {self-signed} certificate.
    The generated certificate has the structure of an X.509 v3 digital
    certificate. It has information about the version, serial number, and
    validity period of the certificate, the ID of the algorithm that is used to
    encrypt the data, the organization that issued the certificate, and the
    \e subject (owner) of the certificate. In case of a self-signed certificate,
    the issuer and owner of the certificate are the same. In addition, the
    certificate has information about the algorithm that is used to sign
    the certificate, as well as the signature of the certificate.

    A password protects the keystore. In addition, you can protect each
    alias with its individual password.

    When you sign an Android application, you must select a keystore that
    has certificates and a certificate alias from the keystore. The signing
    process embeds the public key (certificate) for the alias into the APK.

    \section2 Create a keystore and certificate

    To create a keystore and a self-signed certificate:

    \list 1

        \li Go to \uicontrol Projects > \uicontrol {Build Settings} >
            \uicontrol {Build Android APK} and select \uicontrol Details.

            \image {qtcreator-build-settings-android-apk.webp} {Build Android APK step in the Build Settings tab in Projects}

        \li In the \uicontrol Keystore field, select \uicontrol Create to create
            a new keystore that has one key pair in the
            \uicontrol {Create a Keystore and a Certificate} dialog:

            \image {qtcreator-android-certificate.png} {Create a Keystore and a Certificate dialog}

        \li In the \uicontrol Keystore group, enter a password to protect the
            keystore.

        \li In the \uicontrol Certificate group, specify the key size and validity
            period of the certificate. You can specify a separate password to
            protect the key pair or use the keystore password.

        \li In the \uicontrol {Certificate Distinguished Names} group, enter
            information about yourself and your company or organization that
            identifies the issuer and the owner of the key pair.

        \li Select \uicontrol Save.

        \li In the \uicontrol {Keystore File Name} dialog, enter a name for the
            keystore and select a location for it.

        \li In the \uicontrol Keystore dialog, enter the keystore password to create
            the key pair in the keystore.

    \endlist

    \section2 Sign a package

    To sign an Android package by using a key pair:

    \list 1

        \li Go to \uicontrol Projects > \uicontrol {Build Settings} >
            \uicontrol {Build Android APK} and select \uicontrol Details.

        \li In the \uicontrol Keystore field, select \uicontrol Choose to select an existing
            keystore.

        \li In the \uicontrol {Certificate alias} field, select an alias from the list
            of key pairs that the keystore has.

        \li Select \uicontrol {Sign package} to use the alias to
            sign the Android package.

    \endlist

    \sa {Android}{How to: Develop for Android}, {Developing for Android}
*/

/*!
    \page creator-how-to-add-libraries-to-android-packages.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Add external libraries to Android packages

    \QC automatically detects which Qt libraries an application uses and adds
    them as dependencies.

    To copy external libraries into the application's library folder and load
    them on startup:

    \list 1
        \li Go to \uicontrol Projects > \uicontrol {Build Settings} >
            \uicontrol {Build Android APK}, and select \uicontrol Details.
            \image {qtcreator-build-settings-android-apk.webp} {Build Android APK step in the Build Settings tab in Projects}
        \li In \uicontrol {Additional Libraries}, select the libraries to add.
    \endlist

    \section1 Add OpenSSL libraries

    To add OpenSSL libraries, select \uicontrol {Include prebuilt OpenSSL libraries}
    in the \uicontrol {Additional Libraries} group.

    This adds the OpenSSL include project that you specify in \preferences >
    \uicontrol SDKs > \uicontrol {Android OpenSSL Settings}. This works for both
    qmake and CMake projects.

    \image {qtcreator-preferences-android.webp} {Android tab in SDKs preferences}

    You can also manually add the paths to the required \c libssl.so and
    \c libcrypto.so libraries to the \uicontrol {Additional Libraries} field.

    \sa {Android}{How to: Develop for Android}, {Developing for Android}
*/

/*!
    \page creator-how-to-android-manifest.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Edit Android manifest files

    You can use the configuration options in \uicontrol Projects >
    \uicontrol {Build Settings} > \uicontrol {Build Android APK} to specify all
    the settings you need for the \c androiddeployqt tool during application
    development.

    \image {qtcreator-build-settings-android-apk.webp} {Build Android APK step in the Build Settings tab in Projects}

    You only need an Android manifest file to specify Android-specific settings,
    such as the application icon or a splash screen.

    However, you need the manifest file to publish the package in the Play Store.

    If you use CMake as the build system, you must specify the Android package
    source directory, \c QT_ANDROID_PACKAGE_SOURCE_DIR, in the \c CMakeList.txt
    file.

    \section1 Create a manifest file

    To use \QC to create an Android manifest file:

    \list 1

    \li Go to \uicontrol Projects > \uicontrol {Build Settings} >
        \uicontrol {Build Android APK}, and select \uicontrol {Create Templates}.

    \li Check the path in \uicontrol {Android package source directory}.

        \image {qtcreator-android-create-template.png} {Create Template dialog}

    \li Select \uicontrol {Copy the Gradle files to Android directory} if you
        plan to extend the Java part of your Qt application.

    \li Select \uicontrol Finish to copy the template files to the \c android
        directory and to open the manifest file in text format for editing.

    \endlist

    \section1 Set manifest file options

    To edit the manifest file:

    \list
        \li In \uicontrol Projects, select the manifest file.
        \li Go to \uicontrol Tools > \uicontrol Android >
        \uicontrol {Manifest XML Source}.
    \endlist

    \image {qtcreator-android-manifest-source.webp} {Android Manifest XML Source editor}

    For more information about setting options in Android manifest files, see
    \l {Qt for Android Manifest File Configuration}.

    You can use editors to set application icons, splash screens, and
    permissions.

    \section2 Screen orientation

    In the \c {<activity>} section, set the \c {android:screenOrientation} option
    to determine screen orientation depending on sensor readings or user
    preferences. The default value is \c {unspecified}.

    \details {Screen orientation options}

    \table
        \header
            \li Orientation
            \li Description
        \row
            \li \c {unspecified}
            \li The system chooses the orientation. The policy it uses, and
                therefore the choices made in specific contexts may differ
                from device to device.
        \row
            \li \c {behind}
            \li Use the same orientation as the activity that's immediately
                beneath it in the activity stack.
        \row
            \li \c {landscape}
            \li Landscape orientation, where the display width is larger than
                its height.
        \row
            \li \c {portrait}
            \li Portrait orientation, where the display height is larger than
                its width.
        \row
            \li \c {reverseLandscape}
            \li Landscape orientation in the opposite direction of normal
                landscape.
        \row
            \li \c {reversePortrait}
            \li Portrait orientation in the opposite direction of normal
                portrait.
        \row
            \li \c {sensorLandscape}
            \li Landscape orientation, but it can be either normal or reverse
                landscape based on the device sensor. The sensor is used even
                if the user has locked sensor-based rotation.
        \row
            \li \c {sensorPortrait}
            \li Portrait orientation, but it can be either normal or reverse
                portrait based on the device sensor. The sensor is used even
                if the user has locked sensor-based rotation.
        \row
            \li \c {userLandscape}
            \li Landscape orientation, but it can be either normal or reverse
                landscape based on the device sensor and the user's preference.
        \row
            \li \c {userPortrait}
            \li Portrait orientation, but it can be either normal or reverse
                portrait based on the device sensor and the user's preference.
        \row
            \li \c {sensor}
            \li The orientation is determined by the device orientation sensor.
                The orientation of the display depends on how the user is
                holding the device. It changes when the user rotates the device.
                Some devices, however, will not rotate to all four possible
                orientations by default. To allow all four orientations, select
                the full sensor option. The sensor is used even if the user
                locked sensor-based rotation.
        \row
            \li \c {fullSensor}
            \li The orientation is determined by the device orientation sensor
                for any of the four orientations. This is similar to the sensor
                option, except it allows any of the four possible screen
                orientations, regardless of what the device usually does.
                For example, some devices won't normally use reverse portrait
                or reverse landscape, but this option enables them.
        \row
            \li \c {noSensor}
            \li The orientation is determined without reference to a physical
                orientation sensor. The sensor is ignored, so the display will
                not rotate based on how the user moves the device.
        \row
            \li \c {user}
            \li The user's current preferred orientation.
        \row
            \li \c {fullUser}
            \li If the user has locked sensor-based rotation, this option
                behaves in the same way as the user option. Otherwise, it
                behaves the same as the full sensor option and allows any
                of the four possible screen orientations.
        \row
            \li \c {locked}
            \li Locks the orientation to its current rotation, whatever that is.
    \endtable
    \enddetails

    \section2 Icons

    To set images to use as application icons depending on screen density, go to
    \uicontrol Tools > \uicontrol Android > \uicontrol {Icon}.

    \image {qtcreator-android-manifest-icon.webp} {Icon editor}

    You can set different images to be shown as application icons and splash
    screens on low, medium, high, and extra high DPI displays. The following
    list summarizes the DPI values typically associated with each category:

    \list
        \li Low-density (LDPI): ~120dpi
        \li Medium-density (MDPI): ~160dpi
        \li High-density (HDPI): ~240dpi
        \li Extra-high-density (XHDPI): ~320dpi
        \li Extra-extra-high-density (XXHDPI): ~480dpi
        \li Extra-extra-extra-high-density (XXXHDPI): ~640dpi
    \endlist

    To generate a set of icons at the appropriate resolution for each pixel
    density from an image, select \uicontrol {Select Master Icon}.

    To clear icons, select \uicontrol {Clear Icon}.

    \section2 Splash screens

    To specify settings for splash screens, go to \uicontrol Tools >
    \uicontrol Android > \uicontrol {Splash Screen}.

    \image {qtcreator-android-manifest-editor-splash-screen.webp} {Splash screen editor}

    Select images to display as splash screens depending on the device
    orientation and screen resolution.

    Select the images with the highest resolution in
    \uicontrol {Select Master Image}, \uicontrol {Select Portrait Image},
    and \uicontrol {Select Landscape Image}.

    In \uicontrol {Image show mode}, select whether to center the splash screen
    on the device display or scale it to fill the display.

    Set a background color in \uicontrol {Background color}.

    By default, drawing an activity hides the splash screen. To keep it visible until
    \l{QNativeInterface::QAndroidApplication::hideSplashScreen()} is
    called, select \uicontrol {Sticky splash screen}.

    Select \uicontrol {Clear All} to reset all settings or remove all images.

    \section2 Permissions

    Starting from Android 6.0 (API 23), applications have to request permissions
    at runtime (see \l{QCoreApplication::requestPermission()}). Users must grant
    these permissions when installing the application for lower Android API levels.
    The Android OS then grants the application access to the appropriate data and
    features.

    To set permissions:

    \list 1
        \li Go to \uicontrol Tools > \uicontrol Android >
            \uicontrol {Permissions}.
            \image {qtcreator-android-manifest-permissions.webp} {Permissions editor}
        \li Select a permission in the drop-down list, and then select
            \uicontrol Add to add it to the \uicontrol {Permission} list.
        \li Select the permission, and then select \uicontrol {Edit Attributes}
            to set attributes for the permission.
            \image {qtcreator-android-permissions-attributes.webp} {Permission attribute editor}
        \li In \uicontrol {Attribute}, select an attribute.
        \li In \uicontrol {Value}, enter a value for the attribute.
        \li Select \uicontrol Add to set the attribute and value.
        \li Select \uicontrol OK to add the attribute to the permission.
    \endlist

    Select \uicontrol {Include default permissions for Qt modules} and
    \uicontrol {Include default features for Qt modules} to add the
    permissions needed by Qt libraries, such as
    \c {android.permission.ACCESS_BACKGROUND_LOCATION} for \l{Qt Positioning}.

    \sa {Android}{How to: Develop for Android}, {Developing for Android},
    {Qt for Android Manifest File Configuration}
*/

