Kotlin Gradle 插件中的编译器选项

每个 Kotlin 的发行版本都包含对于以下目标代码的编译器： JVM、JavaScript，以及支持平台的本地二进制文件。

这些编译器会在这些步骤中被调用：

• IDE，当你在你的 Kotlin 项目上点击编译或运行按钮时。
• Gradle，当你在控制台或者 IDE 上调用 gradle build 命令时。
• Maven，当你在控制台或者 IDE 上调用 mvn compile 或者 mvn test-compile命令时。

你也可以用命令行手动调用 Kotlin 编译器， 详见使用命令行编译器教程。

配置选项

Kotlin 编译器有一系列用于控制编译过程的参数。

通过构建脚本，你可以指定额外的编译选项。使用 Kotlin 编译任务中的 compilerOptions 属性来指定。 例如：

【Kotlin】

tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
    compilerOptions {
        freeCompilerArgs.add("-Xexport-kdoc")
    }
}

【Groovy】

tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
    compilerOptions {
        freeCompilerArgs.add("-Xexport-kdoc")
    }
}

面向 JVM

JVM 环境下的编译任务，对于生产代码叫做 compileKotlin，而对于测试代码则叫做 compileTestKotlin。对于自定义源代码集（source set），这些任务命名遵循 compile＜Name＞Kotlin 模式。

Android 项目中的任务名称包含构建变体 <--! -->名称，并遵循 compile<BuildVariant>Kotlin 的模式，例如 compileDebugKotlin 或 compileReleaseUnitTestKotlin。

对于 JVM 项目和 Android 项目，都可以通过项目的 Kotlin 扩展 DSL 去配置选项。

【Kotlin】

kotlin {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}

【Groovy】

kotlin {
    compilerOptions {
        apiVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
    }
}

有几点是需要注意的：

• android.kotlinOptions 和 kotlin.compilerOptions 这两个配置会相互覆写。只有最新（即最下面）的一个会生效。
• kotlin.compilerOptions 会影响项目中所有 Kotlin 编译任务的配置。
• 对于那些应用到 kotlin.compilerOptions 的任务，你可以通过 tasks.named<KotlinJvmCompile>("compileKotlin") { }（或者 tasks.withType<KotlinJvmCompile>().configureEach { }）来覆写配置。

面向 JavaScript

JavaScript 的编译任务，对于生产代码叫做 compileKotlinJs，对于测试代码叫做 compileTestKotlinJs。 对于自定义源代码集（source set），这些任务命名遵循 compile＜Name＞KotlinJs 模式。

要配置单个任务，请使用其名称：

【Kotlin】

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ……

val compileKotlin: KotlinCompilationTask<*> by tasks

compileKotlin.compilerOptions.suppressWarnings.set(true)

【Groovy】

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ……

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        suppressWarnings.set(true)
    }
}

请注意，对于 Gradle Kotlin DSL，首先从项目的 tasks 中获取任务。

相应地，为 JS 与公共目标使用类型 Kotlin2JsCompile 与 KotlinCompileCommon。

适用于全局的 Kotlin 编译任务

你也可以在项目中对所有的 Kotlin 编译任务进行配置：

【Kotlin】

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ……

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    compilerOptions { /*……*/ }
}

【Groovy】

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions { /*……*/ }
}

所有编译器选项

这里列出了 Gradle 任务的完整选项列表：

常规属性

JVM 特有的属性

JVM、JS 与 JS DCE 的公共属性

我们计划在今后的发行版本中将freeCompilerArgs选项弃用。如果你因此无法在 Kotlin Gradle DSL 中配置某些选项 请提出一个 Issue。

通过 freeCompilerArgs 选项配置额外的参数的示例

通过使用 freeCompilerArgs 来应用包括实验性参数在内的额外编译器参数。你可以在这个属性中加入一个单独的编译器参数或者一个编译器参数的列表。

【Kotlin】

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

val compileKotlin: KotlinCompilationTask<*> by tasks

// 单个实验性参数
compileKotlin.compilerOptions.freeCompilerArgs.add("-Xexport-kdoc")
// 单个附加参数，可以是键值对
compileKotlin.compilerOptions.freeCompilerArgs.add("-Xno-param-assertions")
// 参数列表
compileKotlin.compilerOptions.freeCompilerArgs.addAll(listOf("-Xno-receiver-assertions", "-Xno-call-assertions"))

【Groovy】

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // 单个实验性参数
        freeCompilerArgs.add("-Xexport-kdoc")
        // 单个附加参数，可以是键值对
        freeCompilerArgs.add("-Xno-param-assertions")
        // 参数列表
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

JVM 与 JS 的公共属性

设置 languageVersion 的示例

要设置语言的版本，请使用如下格式的语法：

【Kotlin】

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
              org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
            )
    }

【Groovy】

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion = 
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
}

另见编译器选项的类型。

JS 特有的属性

编译器选项的类型

一些 compilerOptions 使用独有的类型来替代字符串类型

下一步做什么？

了解更多关于：

• 增量编译、缓存支持、构建日志以及 Kotlin 守护进程。
• Gradle 的基础知识和特性。
• 对 Gradle 插件变体的支持。