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
ormvn 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 特有的属性
名称 | 描述 | 可能的值 | 默认值 |
---|---|---|---|
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 文件 | "\ |
|
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: