Kotlin Gradle 插件中的编译器选项
Kotlin 的每个版本都包含适用于受支持目标的编译器: JVM、JavaScript,以及适用于受支持平台的原生二进制文件。
这些编译器在以下场景中被调用:
- 在 IDE 中点击 Kotlin 项目的 Compile 或 Run 按钮时。
- 在控制台或 IDE 中调用
gradle build时。 - 在控制台或 IDE 中调用
mvn compile或mvn test-compile时。
你也可以按照使用命令行编译器教程中所述,从命令行手动运行 Kotlin 编译器。
如何定义选项
Kotlin 编译器提供了许多用于定制编译过程的选项。
Gradle DSL 支持对编译器选项进行全面配置。它适用于 Kotlin Multiplatform 和 JVM/Android 项目。
通过 Gradle DSL,你可以在构建脚本中的三个级别配置编译器选项:
- 扩展级别(Extension level):在
kotlin {}块中为所有目标和共享源集进行配置。 - 目标级别(Target level):在特定目标的块中进行配置。
- 编译单元级别(Compilation unit level):通常在特定的编译任务中进行配置。
较高层级的设置会作为较低层级的约定(默认值):
- 在扩展级别设置的编译器选项是目标级别选项的默认值,包括像
commonMain、nativeMain和commonTest这样的共享源集。 - 在目标级别设置的编译器选项是编译单元(任务)级别选项的默认值,例如
compileKotlinJvm和compileTestKotlinJvm任务。
反之,在较低层级所做的配置会覆盖较高层级的相关设置:
- 任务级别的编译器选项会覆盖目标级别或扩展级别的相关配置。
- 目标级别的编译器选项会覆盖扩展级别的相关配置。
要查看实际应用到编译中的是哪一级别的编译器实参,请使用 Gradle 的 DEBUG 级别日志。 对于 JVM 和 JS/WASM 任务,在日志中搜索 "Kotlin compiler args:" 字符串;对于 Native 任务,搜索 "Arguments =" 字符串。
如果你是第三方插件作者,最好在项目级别应用你的配置,以避免覆盖问题。为此,你可以使用全新的 Kotlin 插件 DSL 扩展类型。建议你在自己的文档中显式记录此配置。
扩展级别
你可以在顶层的 compilerOptions {} 块中为所有目标和共享源集配置通用编译器选项:
kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}目标级别
你可以在 target {} 块内的 compilerOptions {} 块中为 JVM/Android 目标配置编译器选项:
kotlin {
target {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}
}在 Kotlin Multiplatform 项目中,你可以在具体目标内配置编译器选项。例如:jvm { compilerOptions {}}。更多信息请参阅 Multiplatform Gradle DSL 参考。
编译单元级别
你可以在任务配置内的 compilerOptions {} 块中为特定的编译单元或任务配置编译器选项:
tasks.named<KotlinJvmCompile>("compileKotlin"){
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}你还可以通过 KotlinCompilation 在编译单元级别访问和配置编译器选项:
kotlin {
target {
val main by compilations.getting {
compileTaskProvider.configure {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
}
}
}
}
}如果你想为除 JVM/Android 和 Kotlin Multiplatform 之外的目标配置插件,请使用对应 Kotlin 编译任务的 compilerOptions {} 属性。以下示例展示了如何在 Kotlin 和 Groovy DSL 中完成此设置:
tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
compilerOptions {
apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
}
}tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
compilerOptions {
apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
}
}从 kotlinOptions {} 迁移到 compilerOptions {}
kotlinOptions {} 迁移到 compilerOptions {} 在 Kotlin 2.2.0 之前,你可以使用 kotlinOptions {} 块来配置编译器选项。由于 kotlinOptions {} 块自 Kotlin 2.0.0 起已弃用,本节提供了将构建脚本迁移为改用 compilerOptions {} 块的指南与建议:
集中管理编译器选项并使用类型化值
只要可能,尽量在扩展级别配置编译器选项,并在编译单元级别针对特定任务进行重写。
在 compilerOptions {} 块中不能使用原始字符串,因此需要将其转换为类型化值。例如,如果原来是这样:
plugins {
kotlin("jvm") version "2.4.21"
}
tasks.withType<KotlinCompile>().configureEach {
kotlinOptions {
jvmTarget = "17"
languageVersion = "2.4"
apiVersion = "2.4"
}
}plugins {
id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}
tasks.withType(KotlinCompile).configureEach {
kotlinOptions {
jvmTarget = '17'
languageVersion = '2.4'
apiVersion = '2.4'
}
}迁移后应为:
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
plugins {
kotlin("jvm") version "2.4.21"
}
kotlin {
// 扩展级别
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.4")
apiVersion = KotlinVersion.fromVersion("2.4")
}
}
// 在编译单元级别进行重写的示例
tasks.named<KotlinJvmCompile>("compileKotlin"){
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.4")
}
}import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
plugins {
id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}
kotlin {
// 扩展级别
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
languageVersion = KotlinVersion.fromVersion("2.4")
apiVersion = KotlinVersion.fromVersion("2.4")
}
}
// 在编译单元级别进行重写的示例
tasks.named("compileKotlin", KotlinJvmCompile).configure {
compilerOptions {
apiVersion = KotlinVersion.fromVersion("2.4")
}
}迁移不再使用 android.kotlinOptions
如果你的构建脚本之前使用了 android.kotlinOptions,请迁移为改用 kotlin.compilerOptions。可以在扩展级别或目标级别进行配置。
例如,对于 Android 项目:
plugins {
id("com.android.application")
kotlin("android")
}
android {
kotlinOptions {
jvmTarget = "17"
}
}plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
}
android {
kotlinOptions {
jvmTarget = '17'
}
}更新为:
plugins {
id("com.android.application")
kotlin("android")
}
kotlin {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
}
kotlin {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}又例如,对于带有 Android 目标的 Kotlin Multiplatform 项目:
plugins {
kotlin("multiplatform")
id("com.android.application")
}
kotlin {
androidTarget {
compilations.all {
kotlinOptions.jvmTarget = "17"
}
}
}plugins {
id 'org.jetbrains.kotlin.multiplatform'
id 'com.android.application'
}
kotlin {
androidTarget {
compilations.all {
kotlinOptions {
jvmTarget = '17'
}
}
}
}更新为:
plugins {
kotlin("multiplatform")
id("com.android.application")
}
kotlin {
androidTarget {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}
}plugins {
id 'org.jetbrains.kotlin.multiplatform'
id 'com.android.application'
}
kotlin {
androidTarget {
compilerOptions {
jvmTarget = JvmTarget.fromTarget("17")
}
}
}迁移 freeCompilerArgs
将所有
+=操作替换为add()或addAll()函数。如果你使用了
-opt-in编译器选项,请检查 KGP API 参考 中是否已有专用 DSL,并改用专用 DSL。将所有使用
-progressive编译器选项的地方迁移为使用专用 DSL:progressiveMode.set(true)。将所有使用
-Xjvm-default编译器选项的地方迁移为使用专用 DSL:jvmDefault.set()。选项映射关系如下:迁移前 迁移后 -Xjvm-default=all-compatibilityjvmDefault.set(JvmDefaultMode.ENABLE)-Xjvm-default=alljvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)-Xjvm-default=disablejvmDefault.set(JvmDefaultMode.DISABLE)
例如,如果原来是这样:
kotlinOptions {
freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
freeCompilerArgs += listOf("-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all")
}kotlinOptions {
freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
freeCompilerArgs += ["-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all"]
}迁移为:
kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes"))
progressiveMode.set(true)
jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
}
}kotlin {
compilerOptions {
optIn.add("kotlin.RequiresOptIn")
freeCompilerArgs.addAll(["-Xcontext-receivers", "-Xinline-classes"])
progressiveMode.set(true)
jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
}
}针对 JVM
如前所述,你可以在扩展级别、目标级别以及编译单元级别(任务)为 JVM/Android 项目定义编译器选项。
默认的 JVM 编译任务在生产代码中名为 compileKotlin,在测试代码中名为 compileTestKotlin。自定义源集的任务则遵循 compile<Name>Kotlin 模式命名。
你可以在终端中运行 gradlew tasks --all 命令,并在 Other tasks 分组中搜索 compile*Kotlin 任务名称,以查看 Android 编译任务列表。
需要注意的一些重要细节:
kotlin.compilerOptions会配置项目中的每个 Kotlin 编译任务。- 你可以通过
tasks.named<KotlinJvmCompile>("compileKotlin") { }(或tasks.withType<KotlinJvmCompile>().configureEach { })方式来覆盖kotlin.compilerOptionsDSL 所应用的配置。
针对 JavaScript
JavaScript 编译任务在生产代码中名为 compileKotlinJs,在测试代码中名为 compileTestKotlinJs,对于自定义源集则为 compile<Name>KotlinJs。
要配置单个任务,请使用其名称:
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
val compileKotlin: KotlinCompilationTask<*> by tasks
compileKotlin.compilerOptions.suppressWarnings.set(true)import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named('compileKotlin', KotlinCompilationTask) {
compilerOptions {
suppressWarnings = true
}
}请注意,在使用 Gradle Kotlin DSL 时,应先从项目的 tasks 中获取该任务。
分别对 JS 和 common 目标使用 Kotlin2JsCompile 和 KotlinCompileCommon 类型。
你可以在终端中运行 gradlew tasks --all 命令,并在 Other tasks 分组中搜索 compile*KotlinJS 任务名称,以查看 JavaScript 编译任务列表。
所有 Kotlin 编译任务
也可以对项目中的所有 Kotlin 编译任务进行统一配置:
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
compilerOptions { /*...*/ }
}import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named('compileKotlin', KotlinCompilationTask) {
compilerOptions { /*...*/ }
}所有编译器选项
以下是通过 Kotlin Gradle 插件可用的 Kotlin 编译器选项的完整列表:
通用属性
| 名称 | 说明 | 可选值 | 默认值 |
|---|---|---|---|
allWarningsAsErrors | 若有任何警告则报错 | false | |
apiVersion | 控制你的代码可以使用哪些 Kotlin API。更多信息请参阅 -api-version。 | "2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL) | |
extraWarnings | 启用额外的声明、表达式和类型编译器检查,若为 true 则输出警告 | true, false | false |
freeCompilerArgs | 额外编译器实参的列表。你也可以在此处使用实验性的 -X 实参。参见示例 | [] | |
languageVersion | 控制编译期间可用的 Kotlin 语言功能和语法。更多信息请参阅 -language-version。 | "2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL) | |
optIn | 用于配置选择加入编译器实参列表的属性 | listOf( /* opt-ins */ ) | emptyList() |
progressiveMode | 启用渐进式编译器模式 | true, false | false |
suppressWarnings | 不生成警告 | false | |
verbose | 启用详细日志输出。仅在启用 Gradle debug 日志级别时生效 | false |
我们计划在未来版本中弃用 freeCompilerArgs 属性。如果你在 Kotlin Gradle DSL 中发现缺少某些选项,请提交 issue。
通过 freeCompilerArgs 使用额外实参的示例
使用 freeCompilerArgs 属性来提供额外的(包括实验性的)编译器实参。你可以向该属性添加单个实参或实参列表:
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
kotlin {
compilerOptions {
// 指定 Kotlin API 版本和 JVM 目标
apiVersion.set(KotlinVersion.KOTLIN_2_4)
jvmTarget.set(JvmTarget.JVM_1_8)
// 单个实验性实参
freeCompilerArgs.add("-Xexport-kdoc")
// 单个额外实参
freeCompilerArgs.add("-Xno-param-assertions")
// 在模块路径上解析额外的根模块
freeCompilerArgs.add("-Xadd-modules=jdk.incubator.vector")
// 实参列表
freeCompilerArgs.addAll(
listOf(
"-Xno-receiver-assertions",
"-Xno-call-assertions"
)
)
}
}import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...
tasks.named('compileKotlin', KotlinCompilationTask) {
compilerOptions {
// 指定 Kotlin API 版本和 JVM 目标
apiVersion = KotlinVersion.KOTLIN_2_4
jvmTarget = JvmTarget.JVM_1_8
// 单个实验性实参
freeCompilerArgs.add("-Xexport-kdoc")
// 单个额外实参,可以是键值对
freeCompilerArgs.add("-Xno-param-assertions")
// 在模块路径上解析额外的根模块
freeCompilerArgs.add("-Xadd-modules=jdk.incubator.vector")
// 实参列表
freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
}
}设置 languageVersion 的示例
要设置语言版本,请使用以下语法:
kotlin {
compilerOptions {
languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
}
}tasks
.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
.configureEach {
compilerOptions.languageVersion =
org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4
}某些属性使用自定义类型。更多信息请参阅编译器选项的类型。
JVM 专属属性
| 名称 | 说明 | 可选值 | 默认值 |
|---|---|---|---|
javaParameters | 为方法形参的 Java 1.8 反射生成元数据 | false | |
jvmTarget | 生成的 JVM 字节码的目标版本 | "1.8", "9", "10", ..., "25", 26"。另见编译器选项的类型 | "1.8" |
jvmTargetValidationMode |
| WARNING, ERROR, IGNORE | ERROR |
jvmDefault | 控制接口中声明的函数如何编译为 JVM 上的默认方法 | ENABLE, NO_COMPATIBILITY, DISABLE | ENABLE |
noJdk | 不要自动将 Java 运行时引入类路径中 | false | |
-Xadd-modules | (实验性)除初始模块外,解析指定的根模块。设置为 ALL-MODULE-PATH 值以解析模块路径上的所有模块。 | 通过 freeCompilerArgs 传入的以逗号分隔的模块名称或 ALL-MODULE-PATH |
JavaScript 专属属性
| 名称 | 说明 | 可选值 | 默认值 |
|---|---|---|---|
friendModulesDisabled | 禁用 internal 声明导出 | false | |
main | 指定在执行时是否应调用 main 函数 | JsMainFunctionExecutionMode.CALL, JsMainFunctionExecutionMode.NO_CALL | JsMainFunctionExecutionMode.CALL |
moduleKind | 编译器生成的 JS 模块类型 | JsModuleKind.MODULE_AMD, JsModuleKind.MODULE_PLAIN, JsModuleKind.MODULE_ES, JsModuleKind.MODULE_COMMONJS, JsModuleKind.MODULE_UMD | null |
sourceMap | 生成源代码映射 | false | |
sourceMapEmbedSources | 将源文件嵌入到源代码映射中 | JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYS | null |
sourceMapNamesPolicy | 将你在 Kotlin 代码中声明的变量和函数名称添加到源代码映射中。关于此行为的更多信息,请参阅我们的编译器参考 | JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NO | null |
sourceMapPrefix | 为源代码映射中的路径添加指定前缀 | null | |
target | 为特定 ECMA 版本生成 JS 文件 | "es5", "es2015", "es2020" | "es5" |
useEsClasses | 允许生成的 JavaScript 代码使用 ES2015 类。对于 ES2015 和 ES2020 目标默认启用 | null |
编译器选项的类型
部分 compilerOptions 使用自定义类型而不是 String 类型:
| 选项 | 类型 | 示例 |
|---|---|---|
apiVersion 与 languageVersion | KotlinVersion | compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_4) |
jvmTarget | JvmTarget | compilerOptions.jvmTarget.set(JvmTarget.JVM_11) |
main | JsMainFunctionExecutionMode | compilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL) |
moduleKind | JsModuleKind | compilerOptions.moduleKind.set(JsModuleKind.MODULE_ES) |
sourceMapEmbedSources | JsSourceMapEmbedMode | compilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING) |
sourceMapNamesPolicy | JsSourceMapNamesPolicy | compilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES) |
后续步骤
深入了解:
