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 的模式,例如 compileDebugKotlincompileReleaseUnitTestKotlin

当面向 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 与公共目标使用类型 Kotlin2JsCompileKotlinCompileCommon

也可以在项目中配置所有 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 特有的属性

名称 描述 可能的值 默认值
javaParameters 为方法参数生成 Java 1.8 反射的元数据 false
jvmTarget 生成的 JVM 字节码的目标版本 "1.6"(已弃用)、 "1.8"、 "9"、 "10"、……、 "18"、 "19"。 Also, see Types for compiler options "1.8"
noJdk 不要自动在类路径中包含 Java 运行时 false

JVM、JS 与 JS DCE 的公共属性

名称 描述 可能的值 默认值
allWarningsAsErrors 任何警告都报告为错误 false
suppressWarnings 不生成警告 false
verbose 启用详细日志输出。 仅在已启用 Gradle debug 日志时才有效 false
freeCompilerArgs 附加编译器参数的列表。You can use experimental -X arguments here too. See an example []

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 的公共属性

名称 描述 可能的值 默认值
apiVersion 限制只使用来自内置库的指定版本中的声明 "1.3"(已弃用)、 "1.4"(已弃用)、 "1.5"、 "1.6"、 "1.7", "1.8", "1.9"(实验性的)
languageVersion 提供与指定 Kotlin 版本源代码级兼容 "1.3"(已弃用)、 "1.4"(已弃用)、 "1.5"、 "1.6"、 "1.7", "1.8", "1.9"(实验性的)

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 特有的属性

名称 描述 可能的值 默认值
friendModulesDisabled 禁用内部声明导出 false
main 定义是否在执行时调用 main 函数 "call"、 "noCall". Also, see Types for compiler options "call"
metaInfo 使用元数据生成 .meta.js 与 .kjsm 文件。用于创建库 true
moduleKind 编译器生成的 JS 模块类型 "umd"、 "commonjs"、 "amd"、 "plain", "es". Also, see Types for compiler options "umd"
outputFile 编译结果的目标 *.js 文件 "\/js/packages/\/kotlin/\.js"
sourceMap 生成源代码映射(source map) true
sourceMapEmbedSources 将源代码嵌入到源代码映射中 "never"、 "always"、 "inlining". Also, see Types for compiler options
sourceMapNamesPolicy Add variable and function names that you declared in Kotlin code into the source map. For more information on the behavior, see our compiler reference. "simple-names", "fully-qualified-names", "no". Also, see Types for compiler options "simple-names"
sourceMapPrefix 将指定前缀添加到源代码映射中的路径
target 生成指定 ECMA 版本的 JS 文件 "v5" "v5"
typedArrays 将原生数组转换为 JS 带类型数组 true

Types for compiler options

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

Option Type Example
jvmTarget JvmTarget compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
apiVersion and languageVersion KotlinVersion compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_1_9)
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)

下一步做什么?

Learn more about: