Kotlin Gradle 插件中的编译器选项

Each release of Kotlin includes compilers for the supported targets: JVM, JavaScript, and native binaries for supported platforms.

These compilers are used by:

• The IDE, when you click the Compile or Run button for your Kotlin project.
• Gradle, when you call gradle build in a console or in the IDE.
• Maven, when you call mvn compile or mvn test-compile in a console or in the IDE.

You can also run Kotlin compilers manually from the command line as described in the Working with command-line compiler tutorial.

How to define options

Kotlin compilers have a number of options for tailoring the compiling process.

Using a build script, you can specify additional compilation options. 使用 Kotlin 编译任务的 compilerOptions 属性来指定。 For example:

【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 时，对于生产代码这些任务称为 compileKotlin 而对于测试代码称为 compileTestKotlin。对于自定义源代码集（source set）这些任务命名遵循 compile＜Name＞Kotlin 模式。

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

当面向 JavaScript 时，任务 compileKotlinJs 用于生产代码，而 compileTestKotlinJs 用于测试代码，以及对于自定义源代码集称为 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】

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

val compileKotlin = tasks.named<KotlinCompilationTask<*>>("compileKotlin")

compileKotlin.compilerOptions { /*……*/ }

【Groovy】

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

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

Gradle 任务的完整选项列表如下：

JVM 特有的属性

JVM、JS 与 JS DCE 的公共属性

We are going to deprecate the attribute freeCompilerArgs in future releases. If you miss some option in the Kotlin Gradle DSL, please, file an issue.

Example of additional arguments usage via freeCompilerArgs

Use the attribute freeCompilerArgs to supply additional (including experimental) compiler arguments. You can add a single argument to this attribute or a list of arguments:

【Kotlin】

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

val compileKotlin: KotlinCompilationTask<*> by tasks

// Single experimental argument
compileKotlin.compilerOptions.freeCompilerArgs.add("-Xexport-kdoc")
// Single additional argument, can be a key-value pair
compileKotlin.compilerOptions.freeCompilerArgs.add("-opt-in=org.mylibrary.OptInAnnotation")
// List of arguments
compileKotlin.compilerOptions.freeCompilerArgs.addAll(listOf("-Xno-param-assertions", "-Xno-receiver-assertions", "-Xno-call-assertions"))

【Groovy】

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")
        // Single additional argument, can be a key-value pair
        freeCompilerArgs.add("-opt-in=org.mylibrary.OptInAnnotation")
        // List of arguments
        freeCompilerArgs.addAll(["-Xno-param-assertions", "-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

JVM 与 JS 的公共属性

Example of setting a languageVersion

To set a language version, use the following syntax:

【Kotlin】

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

【Groovy】

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

Also, see Types for compiler options.

JS 特有的属性

Types for compiler options

Some of the compilerOptions use the new types instead of the String type:

下一步做什么？

Learn more about:

• Incremental compilation, caches support, build reports, and the Kotlin daemon.
• Gradle basics and specifics.
• Support for Gradle plugin variants.