11.3 构建工具 API

原文链接: https://kotlinlang.org/docs/build-tools-api.html

11.3 构建工具 API

Beta

BTA 支持 Kotlin/JVM、Kotlin/JS 和 Kotlin/Wasm。它目前不支持 Kotlin/Native。

Kotlin 提供了构建工具 API（BTA），它简化了构建系统与 Kotlin 编译器的集成方式。

为构建系统添加完整的 Kotlin 支持（例如增量编译、Kotlin 编译器插件、守护进程以及 Kotlin Multiplatform）需要投入大量精力。BTA 的目标是在构建系统与 Kotlin 编译器生态之间提供统一的 API，从而降低这种复杂性。

BTA 定义了构建系统可以实现的一个统一入口点。这样就无需与编译器内部细节进行深度集成。

稳定性级别因目标而异：对 Kotlin/JVM 而言 BTA 处于 Beta 阶段，对 Kotlin/JS 和 Kotlin/Wasm 而言处于 Alpha 阶段。更多细节请参阅 。使用 BTA 需要通过 @OptIn(ExperimentalBuildToolsApi::class) 选择启用。

注意： 如果你对该提案感兴趣或想提供反馈，请参阅 KEEP。在 YouTrack 中关注其实现进展。

与 Gradle 的集成

Kotlin Gradle 插件（KGP）在 Kotlin/JVM 编译中默认使用 BTA。

注意： 我们非常欢迎你在 YouTrack 中反馈使用 KGP 的体验。

为 Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据启用 BTA

Alpha

从 Kotlin 2.4.20 开始，KGP 也可以通过 BTA 运行 Kotlin/JS、Kotlin/Wasm 和 Kotlin 元数据的编译。这让 KGP 与编译器的交互更加一致，在某些情况下编译也会变得更快、更稳定。

在 Kotlin 2.4.20 中，这些目标是作为可选启用的。要试用它们，请把相应的属性添加到你的 gradle.properties 文件中：

kotlin.js.runViaBuildToolsApi = true
kotlin.wasm.runViaBuildToolsApi = true
kotlin.metadata.runViaBuildToolsApi = true

配置不同的编译器版本

使用 BTA，你现在可以使用与 KGP 所用版本不同的 Kotlin 编译器版本。这在以下情况下很有用：

• 你想尝试新的 Kotlin 特性，但还没有更新构建脚本。
• 你需要最新的插件修复，但目前想继续使用较旧的编译器版本。

下面是一个在 build.gradle.kts 文件中进行这种配置的示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

import org.jetbrains.kotlin.buildtools.api.ExperimentalBuildToolsApi
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi

plugins {
    kotlin("jvm") version "2.4.20"
}

group = "org.jetbrains.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

kotlin {
    jvmToolchain(8)
    @OptIn(ExperimentalBuildToolsApi::class, ExperimentalKotlinGradlePluginApi::class)
    compilerVersion.set("2.3.21") // <-- 与 2.4.20 不同的版本
}

兼容的 Kotlin 编译器与 KGP 版本

BTA 支持：

• 之前的三个 Kotlin 主要编译器版本。
• 向前一个主要版本。

例如，在 KGP 2.2.0 中，受支持的 Kotlin 编译器版本是：

• 1.9.25
• 2.0.x
• 2.1.x
• 2.2.x
• 2.3.x

限制

把不同的编译器版本与编译器插件一起使用，可能会导致 Kotlin 编译器异常。Kotlin 团队计划在未来的 Kotlin 版本中解决这个问题。

使用 “in process” 策略启用增量编译

KGP 支持三种编译器执行策略。通常，“in-process” 策略（在 Gradle 守护进程中运行编译器）不支持增量编译。

使用 BTA 后，“in-process” 策略现在支持增量编译。要启用它，请把以下属性添加到你的 gradle.properties 文件中：

1

kotlin.compiler.execution.strategy=in-process

与 Maven 的集成

BTA 让 kotlin-maven-plugin 能够支持 Kotlin 守护进程，后者是默认的编译器执行策略。kotlin-maven-plugin 默认使用 BTA，因此无需任何配置。

BTA 使得将来可以提供更多特性，例如增量编译稳定化。