Qt Gradle Plugin

Overview

What you need to know about version 1.0 of the plugin:

Features

The plugin allows you to use Gradle to build a Qt QML project.

Supported configurations

You can find what is supported here.

Host environments

The host environment limitations for building Qt applications also exist for the plugin. The plugin has been tested on the following operating systems:

• Linux (Ubuntu 22.04)
• Windows (10, 11)
• macOS ARM (Xcode version 15.2)

Qt for Android

Qt for Android version 6.8 or later is required.

Android SDK

The SDK supported is the same for the Qt version you are using. See Android Supported Platforms.

Tools

The CMake and Ninja versions that are supported are packaged with the version of Qt you are installing.

Licensing

This plugin is covered by the Qt Community Edition license.

Attributions

The plugin may contain third party modules under the following permissive licenses:

Getting started

The following section covers installing the plugin, installing all the minimum required Qt dependencies for using the plugin and building a deployable APK.

Installing dependencies

• Qt for Android installation (6.8 or later)
• The Android SDK

Install Qt for Android

There are two ways to get Qt for Android, but for most users, we recommended the following way:

With the Qt Online Installer

To download and install Qt for Android, follow the instructions on the Get and Install Qt page, and do a custom install that includes at least the minimum requirements:

• Qt for Android
• CMake
• Ninja

The following instructions assume you don't want to install Qt Design Studio and Qt Creator. These would normally be installed by default but the instructions here explicitly deselect these and anything not required.

1. Select custom install. If you change the location make sure to note this as you will need it later.
2. Deselect Qt Design Studio.
3. Expand Qt 6.8 or later and select Qt for Android.
4. Deselect Developer and Designer Tools.
5. Select CMake and Ninja.
6. Select any optional Qt modules you might need.
7. Proceed to install.

Clone, build and install Qt yourself

This method should only be used by developers who are working with unreleased or modified Qt builds. It won't be covered here.

See Qt for Android - Building from Source.

Install the Android SDK

Install and note the location of a compatible Android SDK. See Android Supported Platforms.

Install the plugin

You can find the plugin here: Maven Gerrit

Use the plugin from Maven

Modify the settings.gradle(.kts) from your project's root. This downloads the plugin from the Qt Maven instance and you will be able to refer to its id in the build.gradle(.kts) later on.

Kotlin/Groovy (settings.gradle(.kts))

pluginManagement {
    repositories {
        mavenCentral()
    }
}

Configure the plugin

The plugin needs to know where certain parts of the Qt toolchain are. In the <yourappname>/app/build.gradle(.kts) file you need to define paths for plugin.

Kotlin (build.gradle.kts)

Inside the plugins block, include the plugin ID and version.

plugins {
    id("org.qtproject.qt.gradleplugin") version("1.+")
}

Inside Qt build block define the Qt path (with version >= 6.8.0) and path to the QML project. Other properties are optional and explained below.

// Qt Build is a extension of the Qt Build Task
QtBuild {
    // Qt installation directory
    qtPath = file("home/<your-username>/Qt/6.8.0")

    // QML project directory
    projectPath = file("../qmlapp")

    // Optional: Qt kit directory location
    // If defined build will be done to only that ABI
    // else will build using Multi-ABI
    qtKitDir = file('home/<your-username>/<your-Qt-builds>/<your-Qt-kit>')

    // Optional: Extra cmake arguments for configuration
    setExtraCMakeArguments("-DCMAKE_BUILD_TYPE=Release")

    // Optional: If your ninja is installed somewhere other than Qt/Tools/Ninja or
    // not found in system path you can define it here
    ninjaPath = '<your>/<path>/<to>/Ninja'
}

Groovy

plugins {
    id 'org.qtproject.qt.gradleplugin' version '1.+'
}

QtBuild {
    // Qt installation directory
    qtPath file('home/<your-username>/Qt/6.8.0')

    // QML project directory
    projectPath file('../qmlapp')

    // Optional: Qt kit directory location
    // If defined build will be done to only that ABI
    // else will build using Multi-ABI
    qtKitDir file('home/<your-username>/<your-Qt-builds>/<your-Qt-kit>')

    // Optional: Extra cmake arguments for configuration
    extraCMakeArguments = ['-DCMAKE_BUILD_TYPE=Release']

    // Optional: If your ninja is installed somewhere other than Qt/Tools/Ninja or
    // not found in system path you can define it here
    ninjaPath '<your>/<path>/<to>/Ninja'
}

Using the plugin

The plugin can be used from the command line. The following are the commands available.

Building the Qt application .aar:

gradlew QtBuildTask

Listing other available tasks:

gradlew tasks --group QtProject

If you want to use a build of Qt that was not obtained through the online installer, you need to modify the qtKitDir variable, defined in your project's build.gradle file. The file is in your project's <yourappname>/app folder. Its path could be, for example: qtquickview_java/app/build.gradle

qtKitDir = file('home/<your-username>/<your-Qt-builds>/<your-Qt-kit>')

Troubleshooting

Error:"'gradle' is not recognized..."

Fix: Add the location of the Gradle executable that is part of your desired Qt build installation into your system path environment variable

Linux & macOS

export PATH=$PATH:/home/<your-username>/<your-Qt-builds>/<your-Qt-kit>/src/3rdparty/gradle (Linux, macOS)

Windows

set PATH=%PATH%;C:\<your-username>\myQtBuilds\<your-Qt-kit>\src\3rdparty\gradle

Error:"No Qt for Android kit found".

Fix: qtPath = file('..../Qt') needs to have the Qt version as the path's target folder. For example:('..../Qt/6.8.0')

Error:"[home/../declarative/build/qt_generated/quick, aar] failed with exit code 1".

Fix: If you use c qtKitDir change qtPath to use absolute path instead the relative one.

Relative:

file('..../Qt/6.8.0')

Absolute:

file('/home/<username>/Qt/6.8.0')