Qt Gradle Plugin
Overview
What you need to know about version 1.1 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.0 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.0 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.
- Select custom install. If you change the location, make sure to note this as you will need it later.
- Deselect Qt Design Studio.
- Expand Qt 6.8 or later and select Qt for Android.
- Deselect Developer and Designer Tools.
- Select CMake and Ninja.
- Select any optional Qt modules you might need.
- 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:
qtPath = file("/home/username/Qt/6.8.0")
qtPath file('/home/username/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')
© 2024 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.