Table of Contents
Gradle provides a programmatic API called the Tooling API, which you can use for embedding Gradle into your own software. This API allows you to execute and monitor builds and to query Gradle about the details of a build. The main audience for this API is IDE, CI server, other UI authors; however, the API is open for anyone who needs to embed Gradle in their application.
A fundamental characteristic of the Tooling API is that it operates in a version independent way. This means that you can use the same API to work with builds that use different versions of Gradle, including versions that are newer or older than the version of the Tooling API that you are using. The Tooling API is Gradle wrapper aware and, by default, uses the same Gradle version as that used by the wrapper-powered build.
Some features that the Tooling API provides:
The Tooling API always uses the Gradle daemon. This means that subsequent calls to the Tooling API, be it model building requests or task executing requests will be executed in the same long-living process. Chapter 6, The Gradle Daemon contains more details about the daemon, specifically information on situations when new daemons are forked.
As the Tooling API is an interface for developers, the Javadoc is the main documentation for it. We provide several samples that live
in samples/toolingApi
in your Gradle distribution. These samples specify all of the required dependencies for the Tooling API with examples for
querying information from Gradle builds and executing tasks from the Tooling API.
To use the Tooling API, add the following repository and dependency declarations to your build script:
Example 14.1. Using the tooling API
build.gradle
repositories { maven { url 'https://repo.gradle.org/gradle/libs-releases' } } dependencies { compile "org.gradle:gradle-tooling-api:${toolingApiVersion}" // The tooling API need an SLF4J implementation available at runtime, replace this with any other implementation runtime 'org.slf4j:slf4j-simple:1.7.10' }
The main entry point to the Tooling API is the GradleConnector
. You can navigate from there to find code samples and
explore the available Tooling API models.
You can use GradleConnector.connect()
to create a ProjectConnection
.
A ProjectConnection
connects to a single Gradle project. Using the connection you can execute tasks, tests and retrieve models relative to this project.
The current version of the Tooling API supports running builds using Gradle versions 1.2 and later.
You should note that not all features of the Tooling API are available for all versions of Gradle. For example, build cancellation is only available when a build uses Gradle 2.1 and later. Refer to the documentation for each class and method for more details.
The current Gradle version can be used from Tooling API versions 2.0 or later.
The Tooling API requires Java 7 or later. The Gradle version used by builds may have additional Java version requirements.