Since Gradle 1.0-milestone-3, Gradle has had 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 different target versions of Gradle. The Tooling API is Gradle wrapper aware and, by default, uses the same target Gradle version as that used by the wrapper-powered project.
Some features that the Tooling API provides today:
In the future we may support other interesting features:
The Tooling API uses the daemon all the time. This means that subsequent calls to the Tooling API, be it model building requests or task executing requests can 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.
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.
There are two ways of using the GradleConnector
to connect to a Gradle build.
GradleConnector.connect()
to create a ProjectConnection
.
ProjectConnection
can only be used to connect to a single Gradle project at a time. Executing tasks and retrieving models are all relative to this project.
GradleConnector.newGradleConnection()
to create a
GradleConnectionBuilder
.
GradleConnectionBuilder
can be used to connect to any number of Gradle builds at one time. Executing tasks and retrieving models are performed in the context
of the composite. Instead of retrieving a single model for a single Gradle project, the Tooling API can provide all models for all projects with a single method call.