Kotlin Gradle plugin 中的编译与缓存

Kotlin Gradle plugin 支持增量编译(Incremental Compilation)模式, 对 Kotlin/JVM 和 Kotlin/JS 项目默认启用. 增量编译模式会监视 classpath 中的文件在两次编译之间的变更, 因此只有变更过的文件会被编译. 这种方法与 Gradle 的构建缓存 一起配合工作, 并支持 编译回避(compilation avoidance).

对 Kotlin/JVM, 增量编译依赖于类路径快照(Classpath Snapshot), 类路径快照捕获模块的 API 结构, 确定什么时候需要重新编译. 为了优化整个流程管道, Kotlin 编译器使用两种类型的类路径快照:

• 细粒度快照(Fine-grained Snapshot): 包含类成员的详细信息, 例如属性或函数. 当检测到成员级变更时, Kotlin 编译器只重编译依赖于被修改的成员的那些类. 为了保持性能, Kotlin Gradle plugin 会创建为 Gradle 缓存中的 .jar 文件粗粒度快照(Coarse-grained Snapshot).

• 粗粒度快照(Coarse-grained Snapshot): 只包含类 ABI 的 hash. 当 ABI 的一部分发生变更时, Kotlin 编译器会重编译依赖于被修改的类的所有类. 对于不经常变更的类, 例如外部库, 这很有用.

note

Kotlin/JS 项目 使用另一种基于历史文件的增量编译方式.

有以下几种方式可以禁用增量编译设定:

• 对 Kotlin/JVM 项目: 设置 kotlin.incremental=false.

• 对 Kotlin/JS 项目: 设置 kotlin.incremental.js=false.

• 在命令行参数中, 添加 -Pkotlin.incremental=false 或 -Pkotlin.incremental.js=false.

  需要向所有后续的编译命令都添加这个参数.

当你禁用增量编译时, 增量编译的缓存会在构建后失效. 初次编译永远不会是增量编译.

tip

有时增量编译的问题会在错误发生之后再经过多轮才报告给使用者. 请使用 构建报告 来追踪变更历史和编译历史. 这样可以帮助你提供可重现的 bug 报告.

关于我们目前的增量编译方案如何工作, 以及与以前方案的区别, 请阅读我们的 blog.

Kotlin 插件支持 Gradle 构建缓存, 构建缓存会保存构建的输出, 并在未来的构建中重复使用.

如果想要对所有的 Kotlin 任务禁用缓存, 请将系统属性 kotlin.caching.enabled 设置为 false (也就是使用参数 -Dkotlin.caching.enabled=false 来执行编译).

Kotlin plugin 使用 Gradle 配置缓存, 通过对之后的构建重用配置阶段的结果, 来增加构建处理的速度.

关于如何启用配置缓存, 请参见 Gradle 文档. 启用这个功能之后, Kotlin Gradle plugin 会自动开始使用它.

Kotlin daemon 会:

• 与 Gradle daemon 共同运行来编译项目.

• 当你使用 IntelliJ IDEA 内建的构建系统来编译项目时, 它会在 Gradle daemon 之外单独运行.

在 Gradle 的 执行阶段, 当一个 Kotlin 编译任务开始编译源代码时, Kotlin daemon 就会启动. Kotlin daemon 会和 Gradle daemon 一起停止, 或在没有 Kotlin 编译任务执行, 空闲 2 个小时之后停止.

Kotlin daemon 使用与 Gradle daemon 相同的 JDK.

org.gradle.jvmargs=-Xmx1500m -Xms500m -XX:MaxMetaspaceSize=1g

-Xmx1500m -XX:ReservedCodeCacheSize=320m -XX:MaxMetaspaceSize=1g -XX:UseParallelGC -ea -XX:+UseCodeCacheFlushing -XX:+HeapDumpOnOutOfMemoryError -Djava.awt.headless=true -Djava.rmi.server.hostname=127.0.0.1 --add-exports=java.base/sun.nio.ch=ALL-UNNAMED

org.gradle.jvmargs=-Dkotlin.daemon.jvm.options=-Xmx1500m,Xms500m

kotlin.daemon.jvmargs=-Xmx1500m -Xms500m

-Xmx1500m -XX:ReservedCodeCacheSize=320m -Xms500m

kotlin {
    kotlinDaemonJvmArgs = listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC")
}

tasks.withType(CompileUsingKotlinDaemon).configureEach { task ->
    task.kotlinDaemonJvmArguments = ["-Xmx1g", "-Xms512m"]
}

tasks.withType<CompileUsingKotlinDaemon>().configureEach {
    kotlinDaemonJvmArguments.set(listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"))
}

tasks.withType(CompileUsingKotlinDaemon::class).configureEach { task ->
    task.kotlinDaemonJvmArguments.set(["-Xmx1g", "-Xms512m"])
}

从 Kotlin 2.0.0 开始, 默认使用 K2 编译器.

要在 Kotlin 2.0.0 之后的版本中使用以前的编译器, 请使用以下方法:

• 在你的 build.gradle.kts 文件中, 设置语言版本 为 1.9.

  或者

• 使用以下编译器选项: -language-version 1.9.

关于 K2 编译器的优点, 请参见 K2 编译器迁移向导.

Kotlin 编译器执行策略 定义 Kotlin 编译器在哪里执行, 以及各种情况下是否支持增量编译.

有 3 种编译器执行策略:

要定义一个 Kotlin 编译器执行策略, 你可以使用以下属性之一:

• Gradle 属性 kotlin.compiler.execution.strategy.

• Compile Task 属性 compilerExecutionStrategy.

Task 属性 compilerExecutionStrategy 的优先级高于 Gradle 属性 kotlin.compiler.execution.strategy.

kotlin.compiler.execution.strategy 属性可以使用的值是:

1. daemon (默认值)

2. in-process

3. out-of-process

在 gradle.properties 中使用 Gradle 属性 kotlin.compiler.execution.strategy:

kotlin.compiler.execution.strategy=out-of-process

Task 属性 compilerExecutionStrategy 可以使用的值是:

1. org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy.DAEMON (默认值)

2. org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy.IN_PROCESS

3. org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy.OUT_OF_PROCESS

在你的构建脚本中使用 Task 属性 compilerExecutionStrategy:

import org.jetbrains.kotlin.gradle.tasks.CompileUsingKotlinDaemon
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy

// ...

tasks.withType<CompileUsingKotlinDaemon>().configureEach {
    compilerExecutionStrategy.set(KotlinCompilerExecutionStrategy.IN_PROCESS)
}

import org.jetbrains.kotlin.gradle.tasks.CompileUsingKotlinDaemon
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy

// ...

tasks.withType(CompileUsingKotlinDaemon)
    .configureEach {
        compilerExecutionStrategy = KotlinCompilerExecutionStrategy.IN_PROCESS
    }

Kotlin 编译器的 fallback 策略是指, 如果 daemon 因为某种原因失败, 则在 Kotlin daemon 之外运行编译任务. 如果 Gradle daemon 启动, 编译器会使用 "In process" 策略. 如果 Gradle daemon 没有启动, 编译器会使用 "Out of process" 策略.

当 fallback 发生时, 在你的 Gradle 构建输出中会收到以下警告信息:

Failed to compile with Kotlin daemon: java.lang.RuntimeException: Could not connect to Kotlin compile daemon
[exception stacktrace]
Using fallback strategy: Compile without Kotlin daemon
Try ./gradlew --stop if this issue persists.

但是, 静默的 fallback 到其他策略, 会消耗大量的系统资源, 或导致不确定的构建结果. 关于这个问题, 请参见这个 YouTrack issue. 要避免这个问题, 有一个 Gradle 属性 kotlin.daemon.useFallbackStrategy, 默认值为 true. 当它的值设置为 false 时, daemon 启动或通信时问题会导致构建失败. 请在 gradle.properties 文件中声明这个属性:

kotlin.daemon.useFallbackStrategy=false

在 Kotlin 编译任务中也有一个 useDaemonFallbackStrategy 属性, 如果同时使用, 它的优先级会高于 Gradle 属性.

tasks {
    compileKotlin {
        useDaemonFallbackStrategy.set(false)
    }
}

tasks.named("compileKotlin").configure {
    useDaemonFallbackStrategy = false
}

如果运行编译所需要的内存不足, 你会在 log 中看到相关信息.

从 Kotlin 2.0.0 开始, 要试用最新的语言版本, 请在你的 gradle.properties 文件中设置 kotlin.experimental.tryNext 属性. 使用这个属性时, Kotlin Gradle plugin 会将语言版本增加到比你的 Kotlin 版本的默认值的下一个版本. 例如, 在 Kotlin 2.0.0 中, 默认的语言版本是 2.0, 因此这个属性会将语言版本配置为 2.1.

或者, 你也可以运行以下命令:

./gradlew assemble -Pkotlin.experimental.tryNext=true

在 构建报告 中, 你可以看到用来编译每个任务的语言版本.

构建报告包括不同编译阶段的持续时间, 以及为什么不能进行增量编译的原因. 如果编译时间太长, 或对于相同的项目出现了不同的编译时间, 可以使用构建报告来调查性能问题.

Kotlin 构建报告可以帮助你调查构建性能相关的问题, 它比 Gradle build scans 更加有效, Gradle Build Scan 中的粒度只是单个 Gradle Task.

通过对长时间运行的编译分析构建报告, 可以帮助你解决两种常见问题:

• 构建不能增量模式运行. 分析原因, 并解决底层问题.

• 构建是增量模式运行, 但耗费太多时间. 可以尝试重新组织源代码文件 — 切分大的文件, 将不同的类保存到不同的文件, 重构大的类, 在不同的文件中声明顶层函数, 等等.

构建报告还会显示项目中使用的 Kotlin 版本. 此外, 从 Kotlin 1.9.0 开始, 你可以在你的 Gradle Build Scan 中看到, 编译代码时使用的是哪个编译器.

请参见 如何阅读构建报告 以及 JetBrains 如何使用构建报告.

kotlin.build.report.output=file

# 需要的报告输出格式. 可以任意组合
kotlin.build.report.output=file,single_file,http,build_scan,json

# 如果使用 single_file 输出, 则必须设置. 表示报告的输出位置
# 请使用这个设定, 代替已废弃的 `kotlin.internal.single.build.metrics.file` 属性
kotlin.build.report.single_file=some_filename

# 如果使用 json 输出, 则必须设置. 表示报告的输出位置
kotlin.build.report.json.directory=my/directory/path

# 可选项. 文件格式的报告的输出目录. 默认值是: build/reports/kotlin-build/
kotlin.build.report.file.output_dir=kotlin-reports

# 可选项. 用来标记你的构建报告的标签 (例如, debug parameters)
kotlin.build.report.label=some_label

# 必须设置. 基于 HTTP(S) 的报告的 POST 地址
kotlin.build.report.http.url=http://127.0.0.1:8080

# 可选项. 如果 HTTP endpoint 要求身份验证, 通过这个设置指定用户名和密码
kotlin.build.report.http.user=someUser
kotlin.build.report.http.password=somePassword

# 可选项. 将构建的 Git branch 名称添加到构建报告
kotlin.build.report.http.include_git_branch.name=true|false

# 可选项. 将编译器参数添加到构建报告
# 如果一个项目包含很多模块, 构建报告中的编译器参数可能非常重, 而且并没有多大帮助
kotlin.build.report.include_compiler_arguments=true|false

Maximum number of custom values (1,000) exceeded

kotlin.build.report.build_scan.custom_values_limit=500

学习:

• Gradle 的基本概念与详细信息.

• 对 Gradle plugin 变体的支持.