Tooling API - Gradle 构建系统

使用 Tooling API 嵌入 Gradle

Tooling API 简介

Gradle 提供了一个名为 Tooling API 的编程 API，您可以使用它将 Gradle 嵌入到自己的软件中。此 API 允许您执行和监视构建，以及查询 Gradle 以获取构建的详细信息。此 API 的主要受众是 IDE、CI 服务器及其他 UI 作者；但是，需要将 Gradle 嵌入其应用的任何人都可以使用此 API。

Gradle TestKit 使用 Tooling API 对您的 Gradle 插件进行功能测试。
Eclipse Buildship 使用 Tooling API 导入您的 Gradle 项目并运行任务。
IntelliJ IDEA 使用 Tooling API 导入您的 Gradle 项目并运行任务。

Tooling API 功能

Tooling API 的一个基本特点是它以版本无关的方式运行。这意味着您可以使用相同的 API 处理使用不同 Gradle 版本的构建，包括比您正在使用的 Tooling API 版本更新或更旧的版本。Tooling API 兼容 Gradle Wrapper，并且默认情况下使用与 Wrapper 支持的构建相同的 Gradle 版本。

Tooling API 提供的一些功能

查询构建的详细信息，包括项目层次结构和项目依赖项、外部依赖项（包括源和 Javadoc jar）、源目录以及每个项目的任务。
执行构建并监听标准输出和标准错误日志记录以及进度消息（例如，在命令行上运行时显示在“状态栏”中的消息）。
执行特定的测试类或测试方法。
在构建执行过程中接收感兴趣的事件，例如项目配置、任务执行或测试执行。
取消正在运行的构建。
将多个独立的 Gradle 构建合并为一个复合构建。
Tooling API 可以下载并安装合适的 Gradle 版本，类似于 wrapper。
此实现是轻量级的，只有少量依赖项。它也是一个行为良好的库，并且不对您的类加载器结构或日志记录配置做任何假设。这使得该 API 易于嵌入到您的应用中。

Tooling API 和 Gradle 构建守护进程

Tooling API 始终使用 Gradle 守护进程。这意味着对 Tooling API 的后续调用，无论是模型构建请求还是任务执行请求，都将在同一个长期运行的进程中执行。Gradle Daemon（守护进程）包含有关守护进程的更多详细信息，特别是关于何时会分叉新守护进程的情况的信息。

快速入门

由于 Tooling API 是面向开发人员的接口，因此 Javadoc 是其主要文档。

要使用 Tooling API，请将以下仓库和依赖项声明添加到您的构建脚本中

build.gradle.kts

repositories {
    maven { url = uri("https://repo.gradle.org/gradle/libs-releases") }
}

dependencies {
    implementation("org.gradle:gradle-tooling-api:$toolingApiVersion")
    // The tooling API need an SLF4J implementation available at runtime, replace this with any other implementation
    runtimeOnly("org.slf4j:slf4j-simple:1.7.10")
}

build.gradle

repositories {
    maven { url = 'https://repo.gradle.org/gradle/libs-releases' }
}

dependencies {
    implementation "org.gradle:gradle-tooling-api:$toolingApiVersion"
    // The tooling API need an SLF4J implementation available at runtime, replace this with any other implementation
    runtimeOnly 'org.slf4j:slf4j-simple:1.7.10'
}

Tooling API 的主要入口点是 GradleConnector。您可以从那里导航以查找代码示例并探索可用的 Tooling API 模型。您可以使用 GradleConnector.connect() 创建一个 ProjectConnection。一个 ProjectConnection 连接到一个 Gradle 项目。使用此连接，您可以执行任务、测试并检索与此项目相关的模型。

Java 和 Gradle 版本的兼容性

在实现 Gradle 集成时应考虑以下组件：Tooling API 版本、运行 Tooling API 客户端的 JVM（即 IDE 进程）、运行 Gradle 守护进程的 JVM 以及 Gradle 版本。

Tooling API 本身是一个 Java 库，作为 Gradle 发布的一部分发布。每个 Gradle 版本都有一个对应的 Tooling API 版本，版本号相同。

Tooling API 类加载到客户端的 JVM 中，因此它们应该具有匹配的版本。当前版本的 Tooling API 库是使用 Java 8 兼容性编译的。

运行 Tooling API 客户端的 JVM 和运行守护进程的 JVM 可以不同。同时，通过自定义构建操作发送到构建的类需要针对最低支持的 Java 版本。Gradle 支持的 JVM 版本是特定于版本的。上限定义在兼容性矩阵中。下限规则如下：

Gradle 3.x 和 4.x 需要最低 Java 7 版本。
Gradle 5 及更高版本需要最低 Java 8 版本。

Tooling API 版本保证支持运行过去五个主要版本的所有 Gradle 版本的构建。例如，Tooling API 8.0 版本兼容 Gradle 3.0 及更高版本。此外，Tooling API 保证兼容当前和下一个主要版本的未来 Gradle 发布。这意味着，例如，Tooling API 8.1 版本将能够运行 Gradle 9.x 构建，并且可能在 Gradle 10.0 中出现兼容性问题。

此页面有帮助吗？