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 the plugin.

Plugins path

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

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

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

Create a QtBuild block:

QtBuild{

}

Inside the QtBuild block, define the following paths.

QtPath

Qt path for version 6.8.0 or newer where the Qt version you want to build against is installed: Kotlin Groovy

qtPath = file("/home/username/Qt/6.8.0")

qtPath file('/home/username/Qt/6.8.0/Qt/6.8.0')

QML project directory

Add the path to the QML project directory:

projectPath = file("../qmlapp")

projectPath = file('../qmlapp')

Other properties are optional and explained below:

Optional: Qt kit directory

By default, this is not defined, and Multi-ABIs will be built. If this path is defined, then a build will be done for that kit ABI only.

qtKitDir = file("/home/username/qt/build/your-qt-kit")

qtKitDir = file('/home/username/qt/build/your-qt-kit')

Optional: Extra CMake arguments

For example:

setExtraCMakeArguments("-DCMAKE_BUILD_TYPE=Release")

extraCMakeArguments = ['-DCMAKE_BUILD_TYPE=Release']

Optional: ninjaPath

If your ninja is installed somewhere other than Qt/Tools/Ninja or not found in the system path, you can define it here:

ninjaPath = "/your/path/to/ninja"

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(.kts) 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 qtKitDir, change qtPath to use an absolute path instead of the relative one.

Relative:

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

Absolute:

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