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

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

    \title Developing for Android

    \quotation
    \l {Android}{How to: Develop for Android}
    \endquotation

    \brief Set up the toolchain for building applications for Android devices.

    Install a Qt version targeting Android and the Android SDK and NDK to develop
    Qt applications for Android devices. To check the Android version supported
    by each Qt version, see the \l {Qt for Android} documentation for the Qt
    version.

    To get helpful code editing features for Java, such as code completion,
    highlighting, function tooltips, and navigating in code, add a
    \l{Add a Java language server}{Java language server}.

    \QC integrates the Android Debug Bridge (\c adb) command-line tool for
    deploying applications to Android devices, running them, and reading their
    logs. The \c adb tool includes a client and server that run on
    the computer and a daemon that runs on the Android emulator or device.

    \note \QC only detects a device and connects to it after you
    \l{Debug on Android Devices}{enable USB debugging on it}.

    The following video shows the whole process from installing Qt for Android
    to debugging an application on an Android device:

    \youtube 5OiIqFTjUZI

    \section1 Requirements

    To use \QC to develop Qt applications for Android, you need:

    \list
        \li \l {Qt for Android}
        \li \l {Android Development Prerequisites}{Android tools} that \QC can
            automatically download, install, and configure for you.
    \endlist

    \sa {Android}{How to: Develop for Android}, {Get and Install Qt}
*/

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

    \ingroup creator-how-to-android

    \title Set up Android development environment

    \QC offers to automatically install all the necessary packages and tools and
    to set up your \l{Qt for Android} development environment by creating
    debuggers, toolchains, and kits.

    Use \QC to:

    \list
        \li Download and extract the Android SDK Command-line Tools.
        \li Install or update the essential packages such as NDKs,
            build tools, and platform tools.
    \endlist

    To set up the development environment for Android:

    \list 1
        \li Go to \preferences > \uicontrol SDKs > \uicontrol Android.
            \image {qtcreator-preferences-android.webp} {Android tab in SDKs preferences}
        \li In \uicontrol {JDK location}, set the path to the JDK.
            \QC checks the JDK installation and reports errors.

            By default, \QC tries to find a supported \l{Adoptium OpenJDK} or
            \l{OpenJDK} installation. If it cannot find one, you must set the
            path manually. If you have not installed a supported JDK, select
            \inlineimage {icons/online.png} {Open JDK download URL in the system's browser}
            to open the JDK download web page in the default browser.

            \note Use a 64-bit JDK because the 32-bit one might cause issues with
            \c cmdline-tools, and some packages might not appear in the list.
        \li In \uicontrol {Android SDK location}, set the path to the
            folder to install the \l{Android SDK Command-line Tools}.
        \li Select \uicontrol {Set Up SDK} to automatically download and extract
            the Android SDK Command-line Tools to the selected path.

            SDK Manager checks that you have the necessary tools. If you need
            more packages or updates, SDK Manager offers to add or remove
            the appropriate packages. Before taking action, it prompts you to
            accept the changes. In addition, it prompts you to accept Google
            licenses, as necessary.
        \li \uicontrol {Android NDK list} lists the installed NDK versions.
            SDK Manager installed the locked items. You can modify them only
            from the \uicontrol {Android SDK Manager} dialog. For more
            information, see \l{Manage Android NDK Packages}.
        \li Select \uicontrol {Automatically create kits for Android tool chains}
            to automatically create the necessary kits. \QC displays a
            warning if it cannot find a suitable Qt version.
        \li Optionally, in \uicontrol {Android OpenSSL Settings} group, set
            the path to the prebuilt OpenSSL libraries.

            For Qt applications that require OpenSSL support, add
            \l {Android OpenSSL support} to your project, as instructed in
            \l{Add external libraries to Android packages}.
        \li Select \uicontrol {Download OpenSSL} to download the OpenSSL
            repository to the selected path. If the automatic download fails,
            the download web page opens for manual download.
    \endlist

    \section1 Manual setup

    If the automatic setup does not meet your needs, download
    and install Android SDK Command-line Tools, and then install or update the
    necessary NDKs, tools, and packages. For more information, see
    \l{Getting Started with Qt for Android}.

    \section1 View Android toolchain settings

    A JSON configuration file defines the Android SDK Command-Line Tools download
    URL, the essential packages list, and the appropriate NDK for each Qt version.
    The file is in the \QC resource folder:

    \code [shell]
    # Linux and macOS
    ~/.config/QtProject/qtcreator/android/sdk_definitions.json

    # Windows
    C:\Users\Username\AppData\Local\QtProject\qtcreator\android\sdk_definitions.json
    \endcode

    For example, the SDK configuration file sets the NDK version to 22.1.7171670
    for use with Qt 6.3, Qt 6.2, and Qt 5.15.9 to 5.15.20:

    \code [json]
    "specific_qt_versions": [
    {       "versions": ["6.3", "6.2", "5.15.[9-20]"],
            "sdk_essential_packages": ["build-tools;31.0.0", "ndk;22.1.7171670"]
        },
    ]
    \endcode

    You can view the latest version of the configuration file that is up-to-date
    with the Android SDK and NDK changes, \l {sdk_definitions.json}{\c sdk_definitions.json}, in Git.

    \note For Qt 6.5 or later, \QC reads the NDK version that was used for
    building Qt from \c modules/Core.json and uses it instead of the version
    in \c sdk_definitions.json.

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

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

    \ingroup creator-how-to-android
    \ingroup creator-how-to-sdks

    \title Manage Android NDK packages

    To view the \l{Android NDK} versions that \QC installed, go to \preferences >
    \uicontrol SDKs > \uicontrol Android.

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

    SDK Manager installed the locked items. You can modify them only
    in the \uicontrol {Android SDK Manager} dialog.
    For more information, see \l{Manage Android SDK packages}.

    \section1 Download Android NDKs

    To manually download NDKs, select \inlineimage {icons/online.png}
    {Open Android NDK download URL in the system's browser}.

    \section1 Set default NDK

    To use the selected NDK version for all Qt versions by default, select
    \uicontrol {Make Default}.

    \section1 Add NDK paths

    To add custom NDK paths manually to the global list of NDKs, select
    \uicontrol Add. This creates custom toolchains and debuggers associated
    to that NDK.

    You have to manually create a kit that uses the custom NDK.

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

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

    \ingroup creator-how-to-android
    \ingroup creator-how-to-sdks

    \title Manage Android SDK packages

    Since Android SDK Tools version 25.3.0, Android has only a command-line
    tool, \l {sdkmanager}, for SDK package management. To simplify SDK
    management, \QC has an SDK Manager for installing, updating, and
    removing SDK packages. You can still use \c sdkmanager for advanced
    SDK management.

    To view the installed Android SDK packages, select \preferences >
    \uicontrol SDKs > \uicontrol Android > \uicontrol {SDK Manager}.

    \image {qtcreator-android-sdk-manager.webp} {SDK Manager in the Android tab in SDKs preferences}

    \section1 Show SDK packages

    To show packages for a release channel in \uicontrol Package, select the
    channel in \uicontrol {Show Packages} > \uicontrol Channel. Common channel
    IDs include \uicontrol Stable, \uicontrol Beta, \uicontrol Dev, and
    \uicontrol Canary.

    To show obsolete packages, select \uicontrol {Include obsolete}.

    To filter packages, select \uicontrol Available, \uicontrol Installed, or
    \uicontrol All.

    \section1 Update SDK packages

    To update the installed Android SDK packages:

    \list 1
        \li Select \uicontrol {Update Installed}.
        \li Select the packages to update.
        \li Select \uicontrol Apply.
    \endlist

    \section1 Set sdkmanager options

    To set advanced \c sdkmanager options:

    \list 1
        \li Select \uicontrol {Advanced Options}.
        \li In \uicontrol {SDK Manager arguments}, enter sdkmanager options from
            \uicontrol {Available arguments}.
    \image {qtcreator-android-sdk-manager-arguments.png} {Android SDK Manager Arguments dialog}
    \endlist

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

/*!
    \page creator-how-to-manage-avd.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Manage AVDs

    \include {androiddev.qdoc} {android-emulator-info}

    To view and add AVDs, go to \preferences > \uicontrol Devices.

    \image {qtcreator-android-avd-manager.webp} {Android device in Devices preferences}

    Select an AVD in \uicontrol Device to see its status in
    \uicontrol {Current state}.

    To update the status information, select \uicontrol Refresh.

    \section1 Start AVDs

    To start an AVD, select \uicontrol {Start AVD}. Usually, \QC starts an AVD
    when you select it in the \l{Build for many platforms}{kit selector} to
    \l{Deploy applications to Android}{deploy applications} to it.

    \section1 Set preferences for starting AVDs

    To set preferences for starting an AVD, select \uicontrol {AVD Arguments}.

    \image {qtcreator-android-avd-arguments.png} {Startup options for AVDs}

    Set the preferences in \uicontrol {Emulator command-line startup options}.
    For available options, see \l{Start the emulator from the command line}.

    To start the emulator manually from the terminal, enter:

    \code [shell]
    cd <ANDROID_SDK_ROOT>/emulator
    ./emulator -avd <AVD_NAME>
    \endcode

    \section1 Remove AVDs

    To remove an AVD from the list and the kit selector, select
    \uicontrol {Erase AVD}.

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

/*!
    \page creator-how-to-create-avd.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-android

    \title Create an Android Virtual Device (AVD)

    \include {androiddev.qdoc} {android-emulator-info}

    You can create AVDs for:

    \list
        \li Automotive
        \li Desktop
        \li Phone
        \li Tablet
        \li TV
        \li Wear
    \endlist

    To create a new AVD:

    \list 1
        \li Go to \preferences > \uicontrol Devices.
        \li Select \uicontrol Add > \uicontrol {Android Device} >
            \uicontrol {Start Wizard}.
            \image {qtcreator-android-create-avd.webp} {Create New AVD dialog}
        \li In \uicontrol Name, give the AVD a name.
        \li In \uicontrol {Target ABI / API}, select an Android system image
            architecture (ABI) and \l{What is API Level?}{API level} that you
            installed on the computer.
        \li In \uicontrol {Skin definition}, select the AVD type, then
            select one of the predefined AVD skins or \uicontrol Custom for
            a custom AVD skin.
        \li In \uicontrol {SD card size}, set the size of the SD card for the
            AVD.
        \li Select \uicontrol {Override existing AVD name} to overwrite an
            existing AVD with a new AVD using the same name (\c avdmanager \c -f
            option).
        \li Select \uicontrol OK to create the AVD.
    \endlist

    For more advanced options for creating a new AVD, use the command-line tool
    \l{avdmanager} or the Android Studio's native AVD Manager UI.

    Access files on the created and connected AVD in one of the following ways:

    \list
        \li Go to \uicontrol File > \uicontrol {Open From Device}.
        \li Go to the \uicontrol {File System} view and select the AVD in the
            menu.
        \li Use the \l {Navigate with locator}{locator}.
    \endlist

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

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

    \ingroup creator-how-to-android
    \ingroup creator-how-to-debug

    \title Debug on Android devices

    You can use LLDB to debug applications on Android devices that you develop
    with Qt 5.15.9 or later and Qt 6.2 or later.

    Recent releases of \QC have issues with Native (C++) debugging using LLDB
    on Android.

    This was fixed in \QC 17.0.1. To fix this in earlier releases, go to
    \preferences > \uicontrol Debugger > \uicontrol GDB, and add the following
    in \uicontrol {Additional Attach Commands}.

    \code [text]
    settings set plugin.jit-loader.gdb.enable off
    \endcode

    \image {qtcreator-preferences-debugger-gdb.webp} {GDB tab in Debugger preferences}

    \section1 Enable debugging on devices

    You enable debugging in different ways on different Android devices.
    Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}.
    Tap \uicontrol {Build number} in \uicontrol Settings > \uicontrol About
    several times to show \uicontrol {Developer Options}.

    \section1 Select a debug build configuration

    Go to \uicontrol Projects > \uicontrol {Build Settings}, and
    select a \l{glossary-build-config}{debug build configuration}
    in \uicontrol {Active build configuration} to build the
    application for debugging.

    \section1 Resolve conflicts with a second debugger

    \QC cannot debug applications on Android devices if Android Studio is
    running. If the following message appears in \l {Application Output},
    close Android Studio and try again:

    \code [text]
    Ignoring second debugger -accepting and dropping.
    \endcode

    \section1 Use Android Emulator

    \include {androiddev.qdoc} {android-emulator-info}

    \sa {Android}{How to: Develop for Android}, {Developing for Android},
    {Configure on-device developer options}
*/

//! [android-emulator-info]

    To emulate Android devices on Linux, \macos, or Windows, use an
    Android Emulator. The Android Emulator runs the Android operating system
    in a virtual machine called an Android Virtual Device (AVD).

//! [android-emulator-info]
