Connecting Android Devices

You can connect Android devices to the development PC to build, run, debug, and analyze applications from Qt Creator. Devices with Android version 4.1 (API level 16) or later are supported.

If you have a tool chain for building applications for Android devices installed on the development PC, you can add it to Qt Creator. You can then add a kit with the tool chain, and the Qt version for Android for the device's architecture, to build applications for and run them on Android devices. Starting from Qt 5.14.0, Qt for Android package contains all the architectures (ABIs) installed as one. You can also allow Qt Creator to automatically create kits for installed Qt version and tool chains.

The Android Debug Bridge (adb) command line tool is integrated to Qt Creator to enable you to deploy applications to connected Android devices, to run them, and to read their logs. It includes a client and server that run on the development host and a daemon that runs on the emulator or device.

Requirements

To use Qt Creator to develop Qt applications for Android, you need the following:

  • AdoptOpenJDK for all platforms. You can also use OpenJDK on Linux.

    Note: Android SDK Tools versions <= 26.x have issues with JDK versions later than 8. It is recommended to use the latest Command-line SDK Tools.

  • Gradle for building application packages (APK) and app bundles (AAB) for Android devices. Gradle is delivered with Qt 5.9, and later, because Gradle scripts are not delivered with Android SDK tools since version 26.0.0.

    Note: Using Ant to build APKs is no longer supported.

  • Android SDK Tools

    The following Android SDK packages and tools are required for development:

    • Platform tools
    • Build tools
    • At least one SDK platform
    • The Android NDK from Google that provides the tool chain for building applications for Android devices. For a detailed list of Qt versions and their recommended NDK versions, see The Android NDK.
  • On Windows, you also need the Android Debug Bridge (ADB) driver on the Windows platform to enable USB debugging. The default USB driver on Windows does not allow debugging. For more information about installing ADB, see ADB driver installation.

Setting Up the Development Environment

To build Android applications with Qt, install Qt for Android 5.2, or later.

Note: You can build a 64-bit version of Qt for Android yourself. However, for such a Qt version, the minimum required Android version on devices is 5.0 (API level 21).

For more information, see Qt for Android.

Download and install the latest Android SDK, and then install or update the NDKs, tools and packages needed for development.

Starting from Qt Creator 4.12, Qt Creator offers to automatically set up your Android environment and install all the necessary packages and Tools, then creating debuggers, tool chains, and kits. For more information, see Specifying Android Device Settings.

Alternatively, use the Android SDK command line tools to install the required packages. In that case, it is recommended to create an empty folder and extract the downloaded archive into this folder.

Note: The recommended Android SDK Tools version is 25.3.0, or later. The version 25.2.5, or earlier, can be used but it is not advised because it cannot be fully integrated with Qt Creator.

  • Android SDK Tools version 25.3.0, or later

    This allows using the sdkmanager command line tool for SDK package management and the avdmanager tool for Android Virtual Device (AVD) management.

    The sdkmanager will install downloaded packages next to the tools folder that contains all command line tools. You must specify the path to the folder where you extracted the files as Android SDK location inside the Android settings.

    To install those packages, use the following command:

    ./sdkmanager "platform-tools" "platforms;android-29" "build-tools;29.0.2" "ndk-bundle"

    For Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1, the following should be installed instead:

    ./sdkmanager "platform-tools" "platforms;android-29" "build-tools;28.0.2" "ndk;19.2.5345600"

    Under Windows, Google's USB drivers can be installed by running:

    sdkmanager.bat "extras;google;usb_driver"

    For more information about altenative methods of obtaining the USB driver, see http://developer.android.com/sdk/win-usb.html. After the package installation is complete, install the driver from <ANDROID_SDK_ROOT>/extras/google/usb_driver. Try running a few basic adb commands now and check whether your Android device responds to them.

  • Android SDK Tools version 25.2.5, or earlier

    If your Qt version is earlier than v5.9, use this SDK tools version. The SDK tool used to install and update the other SDK tools and packages depends on the Android SDK Tools version that you have installed:

    Use the android tool that comes with the SDK Tools package. For example, on Ubuntu the following command starts the SDK update:

    ./android update sdk

Specifying Android Device Settings

To configure connections to Android devices and general Android settings:

  1. Select Tools > Options > Devices > Android.

    "Android options"

  2. In the JDK location field, set the path to the JDK.

    By default, Qt Creator tries to find any valid JDK/OpenJDK installation. However, if none is found, you must set it manually. Click the (Download) button to open the JDK download web page in the default browser. Qt Creator checks the JDK installation and reports errors.

  3. In the Android Settings group, set the path to the Android SDK Tools.

    Select button to automatically download and extract the Android SDK Tools to the selected path. This will do the following:

    1. Download and extract the Android SDK Tools.
    2. Install or update the essential packages such as NDKs, build tools, platform tools.

    The SDK Tools download URL, the essential packages list, and the appropriate NDK for each Qt version are defined in a JSON configuration file. The file is located under the user's Qt Creator resource folder:

    # Linux and macOS
    ~/.config/QtProject/qtcreator/android/sdk_definitions.json
    
    # Windows
    C:\Users\Username\AppData\Local\QtProject\qtcreator\android\sdk_definitions.json

    For example, the SDK configuration file defines the NDK version 19.2.5345600 to be used for Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1 versions:

    "specific_qt_versions": [
        {
            "versions": ["5.12.[0-5]", "5.13.[0-1]"],
            "sdk_essential_packages": ["build-tools;28.0.2", "ndk;19.2.5345600"],
            "ndk_path": "ndk/19.2.5345600"
        }
    ]

    The latest version of the configuration file that is up-to-date with the Android SDK and NDK changes is found here.

    The installed NDK versions are listed below the SDK path. The items with a lock icon are versions installed from the SDK Manager, and can only be modified from the SDK Manager tab. For more information, see Managing Android SDK Packages. Custom NDK paths can be manually added to the global list of NDKs via the Add button. This creates custom tool chains and debuggers associated to that NDK, which can be used to create custom kits defined by the user.

    To manually download the SDK Tools, select to open the SDK or NDK download web page in the default browser.

    The SDK Manager checks the Android NDK and SDK installations, reports errors, and offers to install the necessary packages.

    "Android NDK and SDK checks"

  4. In the Android OpenSSL group, set the path to the prebuilt OpenSSL libraries.

    For Qt applications that require OpenSSL support, Qt Creator allows to quickly add the Android OpenSSL support to your project. For more details, see Adding External Libraries.

    Select to download the OpenSSL repository to the selected path. If the automatic download fails, the download web page opens for manual download.

  5. Select the Automatically create kits for Android tool chains check box to allow Qt Creator to create the kits for you. Qt Creator displays a warning if it cannot find a suitable Qt version.
  6. Select File > New File or Project > Application (Qt Quick) > Qt Quick Application - Empty > Choose, and follow the instructions of the wizard to create a project. For more information, see Creating Qt Quick Projects.
  7. To specify settings for deploying applications to Android, select Projects > Run for the Android kit, and then select Details to view the Deploy configurations. For more information about the options you have, see Deploying Applications to Android Devices.
  8. Enable debugging on your Android device.

    Debugging is enabled in different ways on different Android devices. Look for USB Debugging under Developer Options. On some devices Developer Options is hidden and becomes visible only when you tap the Build number field in Settings > About several times. For more details, check Configure on-device developer options.

  9. Connect the Android device to the development PC with a USB cable. You might be asked to select a device in the Select Android Devices dialog.

Managing Android SDK Packages

Since Android SDK Tools version 25.3.0, only a command-line tool, sdkmanager, is provided by Android for SDK package management. To make SDK management easier, Qt Creator provides an SDK Manager for installing, updating, and removing SDK packages. You can still use sdkmanager for advanced SDK management.

After you set the path to the Anroid SDK in Tools > Options > Devices > Android, the SDK Manager checks that all the necessary SDK packages have been installed. If packages are missing or updates are needed, the SDK Manager offers to add or remove those packages. Before taking action, it prompts you to accept the changes it is about to make. In addition, it prompts you to accept Google licenses, as necessary.

To view the installed Android SDK packages, select Tools > Options > Devices > Android > SDK Manager.

"Android SDK Manager"

To filter the packages, select Available, Installed, or All in Show Packages.

To update the installed Android SDK packages, select Update Installed. Select the packages to update, and then select Apply.

To specify advanced sdkmanager settings, select Advanced Options and enter arguments in the SDK Manager arguments field. The available arguments are listed and described in Available arguments.

To manage packages installed from Android SDK Tools version 25.2.5, or earlier, you can use the native Android SDK Manager. The Qt Creator SDK Manager and the native SDK Manager are mutually exclusive, because they are used for different Android SDK Tools versions. If you have the native SDK Manager installed, you can open it by selecting Native SDK Manager.

Managing Android Virtual Devices (AVD)

A list of AVDs is shown under Tools > Options > Devices > Android > AVD Manager. This works only with a valid SDK Tools path being set. The value in System/data partition size is used to set the emulator's system partition size upon execution with Start.

"Android NDK and SDK checks"

Creating a New AVD

To create new virtual devices, select Tools > Options > Devices > Android > AVD Manager > Add.

In the Create new AVD dialog, you can create a new custom AVD by setting the name, device type, skin, architecture, API level, and SD card size. You need to have a valid System Image installed before using this dialog, either from Qt Creator's SDK Manager tab or from Android Studio.

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

"Android NDK and SDK checks"

Selecting Android Devices

When you deploy an application to an Android device with Android version 4.2 (API 16) or later, the Select Android Device dialog opens. It lists the devices that are connected to the development PC, as well as AVDs, and their status. You can select devices or AVDs from the Compatible Devices list for deployment.

If Qt Creator determines that a device is not ready for deployment, it places the device in the Incompatible Devices list, with information about the issue. For example, you might need to authorize the connection on the device. After you authorize the connection on the device, select Refresh Device List. The device is moved to the Compatible Devices list and you can select it for deployment.

Other reasons for showing a device in Incompatible Devices are that the Android version on the device is too old or that the tool chain used for building does not match the Android architecture on the device (for example, you cannot deploy an ARM build on an x86 device).

"Select Android Devices dialog"

To create a new AVD, select Create Android Virtual Device.

To set a device as the default device for a particular Android architecture for the current project, select the Always use this device for architecture check box. The Select Android Devices dialog will not appear until you switch to another project or restart Qt Creator.

Using the Android Emulator

To run your application on the Android Emulator, you must have an Android virtual device (AVD). For more information about creating a new one, see Creating a New AVD. If you run an application without a device connected to the development PC and without an AVD specified, Qt Creator asks you to add an AVD.

For Android SDK Tools 25.2.5, or earlier, select Native AVD Manager to manage AVDs.

Note: The Android Emulator has a bug that prevents it from starting on some systems. If the Android Emulator does not start, you can try starting it manually by running the following commands:

cd <ANDROID_SDK>/emulator
./emulator -avd <AVD_NAME>

For more information, see Start the emulator from the command line.

Debugging on Android Devices

Select a debug build configuration to build the application for debugging.

Note: Qt Creator cannot debug applications on Android devices if Android Studio is running. If the following message is displayed in the Output pane, close Android Studio and try again:

Ignoring second debugger -accepting and dropping.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.