Kotlin 编译器选项

-api-version version

只允许使用 Kotlin 库从指定的版本开始提供的 API 声明.

-help (-h)

显示编译器使用方法的帮助信息, 然后退出. 帮助信息中只会显示标准的编译选项. 如果需要显示更多的高级编译选项, 请使用 -X 参数.

-kotlin-home path

对 Kotlin 编译器指定一个自定义的路径, 用来查找运行时期的库文件.

-language-version version

这个选项根据指定的语言版本, 设置支持的语法和语义. 例如, Kotlin 编译器 2.4.0 版本如果指定 -language-version=2.2 选项, 只允许你使用 2.2 或更早版本的语言特性和标准库 API. 这有助于逐步迁移到更新的 Kotlin 版本.

-opt-in annotation

指定注解的完全限定名称, 通过这个注解启用 明确要求使用者同意(opt-in) API.

-P plugin:pluginId:optionName=value

向 Kotlin 编译器插件传递一个选项. 核心编译器插件, 以及它们的选项, 请参见本文档的 核心编译器插件 章节.

-progressive

允许编译器使用 渐进模式(progressive mode).

在渐进模式下, 对不稳定代码中功能废弃和 bug 修正, 会立即生效, 而不会等待完整的版本迁移周期完成. 渐进模式下编写的代码可以向后兼容(backwards compatible); 但是, 非渐进模式下编写的代码, 在渐进模式下编译时, 可能导致编译错误.

-script

运行 Kotlin 脚本文件. 使用这个选项时, 编译器会运行参数中指定的第一个 Kotlin 脚本文件(*.kts).

-verbose

允许输出最详细的 log, 包含编译过程的各种细节信息.

-version

显示编译器版本.

-X

显示编译器高级选项的帮助信息, 然后退出. 这些选项目前还不稳定: 选项的名称和行为都有可能变更, 并且不会有相关公告.

Kotlin 契约选项

以下选项启用实验性的 Kotlin 契约(contract)功能.

-Xallow-reified-type-in-catch

在 inline 函数的 catch 子句中启用对具体化(reified) 的 Throwable 类型参数的支持.

-Xcollection-literals

启用对 集合字面值(collection literal) 括号语法 [] 的支持.

-Xcompiler-plugin-order={plugin.before>plugin.after}

配置编译器 plugin 的运行顺序. 编译器先运行 plugin.before, 然后运行 plugin.after:

可以为 3 个或更多插件定义多条顺序规则. 例如:

这个设置表示以下运行顺序:

1. plugin.first

2. plugin.middle

3. plugin.last

如果某个编译器 plugin 不存在, 对应的规则会被忽略.

可以通过以下 ID 配置对应的 plugin:

这个运行顺序只控制编译器插件的后端, 不控制前端.

-Xdata-flow-based-exhaustiveness

为 when 表达式启用基于数据流的穷尽检查(exhaustiveness check).

-Xexplicit-context-arguments

为上下文参数(context parameter)启用明确的 上下文参数传递.

这可以通过在调用点传递上下文参数, 解决重载歧义.

-Xklib-ir-inliner

配置是否为 Kotlin/Native, Kotlin/JS 和 Kotlin/Wasm 启用 模块内内联(intra-module inlining). 这个功能默认启用.

这个选项支持以下模式:

• disabled: 为 Kotlin/Native, Kotlin/JS 和 Kotlin/Wasm, 禁用模块内内联.

• full: 启用跨模块内联.

-Xintrinsic-const-evaluation

启用 改进的编译期常量(improved compile-time constants).

-Xname-based-destructuring

配置编译器如何根据属性名称解析 基于名称的解构声明(destructuring declarations).

这个选项支持以下模式:

• only-syntax: 启用基于名称的解构的明确调用形式, 不改变既有的解构声明的行为.

• name-mismatch: 当对数据类使用基于位置的解构时, 如果使用的变量名称与属性名称不匹配, 报告警告.

• complete: 启用基于名称的解构的圆括号简写形式, 并且通过方括号语法, 继续支持基于位置的解构.

-Xphases-to-dump-before

设置为 ExternalPackageParentPatcherLowering, 在 IR 降级编译阶段之后创建一个 dump 文件. 通过 -Xdump-directory 编译器选项, 配置 Kotlin/JVM 的输出目录.

-Xrepl

启动 Kotlin REPL.

-Xreturn-value-checker

配置编译器如何 报告被忽略的结果:

• disable: 禁用未使用返回值检查器(默认值).

• check: 启用检查器, 对来自已标注函数的被忽略的结果, 报告警告.

• full: 启用检查器, 将项目中所有函数视为已标注, 并对被忽略的结果报告警告.

警告管理

@argfile

从指定的文件中读取编译器选项. 这样的文件可以包含编译器选项, 对应的值, 以及源代码文件的路径. 选项和文件路径使用空格分隔. 比如:

要传递包含空格的值, 请使用单引号 (') 或双引号 (") 括起. 如果值本身包含引号, 请使用反斜线 (\) 转义符表示.

也可以传递多个参数文件, 比如, 如果想要将编译器选项和源代码文件分开的情况.

如果文件位置不在当前目录下, 请使用相对路径.

-classpath path (-cp path)

在指定的路径中查找 class 文件. 如果 classpath 中存在多个路径, 请使用操作系统的路径分隔符来分隔(对 Windows 系统是 ;, 对 macOS/Linux 系统是 :). classpath 可以包含文件路径, 目录路径, ZIP 文件, 或 JAR 文件.

-d path

将生成的 class 文件输出到指定的位置. 输出位置可以是一个目录, 一个 ZIP 文件, 或一个 JAR 文件.

-include-runtime

将 Kotlin 运行时库文件包含在最终输出的结果 JAR 文件中. 这样将使得最终输出的包可以在任何安装了 Java 环境中运行.

-jdk-home path

如果自定义的 JDK home 目录与默认的 JAVA_HOME 不用, 这个选项会将它添加到 classpath 中.

-Xjdk-release=version

指定生成的 JVM 字节码的目标版本. 将类路径中的 JDK API 限制为指定的 Java 版本. 自动设置 -jvm-target version. 可以指定的值是 1.8, 9, 10, ..., 26.

-jvm-default mode

控制接口中声明的函数如何编译为 JVM 上的默认方法.

-jvm-target version

指定编译产生的 JVM 字节码(bytecode)版本. 可以指定的值是 1.8, 9, 10, ..., 26. 默认值是 1.8.

-java-parameters

针对 Java 1.8 的方法参数反射(reflection on method parameter)生成元信息(metadata). 译者注: 等于 Java 1.8 编译参数 -parameters, 参见 javac 命令行编译器

-module-name name (JVM)

对编译产生的 .kotlin_module 指定一个自定义的名称.

-no-jdk

不要自动将 Java 运行时期库文件添加到 classpath 中.

-no-reflect

不要自动将 Kotlin 反射库文件(kotlin-reflect.jar) 添加到 classpath 中.

-no-stdlib (JVM)

不要自动将 Kotlin/JVM 标准库文件(kotlin-stdlib.jar) 和 Kotlin 反射库文件(kotlin-reflect.jar) 添加到 classpath 中.

-script-templates classnames[,]

脚本定义的模板类. 请使用类的完全限定名称, 如果有多个, 请使用逗号(,) 分隔.

-Xdump-directory

为 -Xphases-to-dump-before 编译器选项配置 dump 文件目录.

-Xjvm-expose-boxed

对模块中的所有的内联值类(Inline Value Class)生成装箱版本(Boxed), 并对使用它们的函数生成装箱的变体, 以供 Java 访问. 详情请参见 在 Java 中调用 Kotlin 代码 指南: 内联值类(Inline Value Class) 小节.

-Xnullability-annotations

配置 Kotlin 编译器如何解析来自指定的 Java 包的可否为 null 注解.

关于支持的注解和配置选项的完整列表, 请参见 可否为 null 注解.

-libraries path

包含 .meta.js 和 .kjsm 文件的 Kotlin 库路径, 如果有多个路径, 请使用操作系统的路径分隔符分隔.

-main {call|noCall}

指定执行时是否要调用 main 函数.

-meta-info

生成 .meta.js 和 .kjsm 文件时附带元信息(metadata). 开发 JS 库时, 请使用这个选项 .

-module-kind {umd|commonjs|amd|plain}

指定编译器生成的 JS 模块类型:

• umd - 统一模块定义(Universal Module Definition) 模块

• commonjs - CommonJS 模块

• amd - 异步模块定义(Asynchronous Module Definition) 模块

• plain - 普通 JS 模块

关于各种 JS 模块类型, 以及它们之间的差别, 请参见 这篇文章.

-no-stdlib (JS)

不要自动将默认的 Kotlin/JS 标准库添加到编译依赖中.

-output filepath

指定编译结果的输出目标文件. 参数值必须是一个 .js 文件路径, 包含文件名.

-output-postfix filepath

将指定文件的内容添加到编译输出文件的末尾部分.

-output-prefix filepath

将指定文件的内容添加到编译输出文件的先头部分.

-source-map

生成源代码映射文件(source map).

-source-map-base-dirs path

使用指定的路径作为起始目录(base directory). 起始目录用来计算源代码映射文件(source map)中的相对路径.

-source-map-embed-sources {always|never|inlining}

是否将源代码文件嵌入到源代码映射文件(source map)中.

-source-map-names-policy {simple-names|fully-qualified-names|no}

将你在 Kotlin 代码中声明的变量和函数名称添加到源代码映射文件(source map)中.

-source-map-prefix

向源代码映射文件(source map)中的路径添加指定的前缀.

-target {es5|es2015}

针对指定的 ECMA 版本生成 JS 文件.

-Xenable-implementing-interfaces-from-typescript

允许从 JavaScript/TypeScript 实现由 @JsExport 注解导出的 Kotlin 接口.

-Xes-long-as-bigint

编译为现代 JavaScript (ES2020) 时, 启用对 JavaScript BigInt 类型的支持, 用来表示 Kotlin 的 Long 值.

-enable-assertions (-ea)

在生成的代码中允许运行时断言(runtime assertion).

-entry name (-e name)

指定入口点的限定名称(qualified entry point name).

-g

允许编译产生 debug 信息. 这个选项会降低代码优化的级别, 并且不应该与 -opt 选项组合使用.

-generate-test-runner (-tr)

生成一个应用程序, 用于在工程中运行单元测试.

-generate-no-exit-test-runner (-trn)

生成一个应用程序, 用于运行单元测试, 但不会有明确的进程结束信息(explicit process exit).

-include-binary path (-ib path)

将外部的二进制文件打包到编译产生的 klib 文件内.

-library path (-l path)

链接指定的库文件. 关于在 Kotlin/native 工程中如何使用库, 请参见 Kotlin/Native 库.

-library-version version (-lv version)

指定库的版本.

-linker-option

在二进制文件构建过程中, 向链接程序传递一个参数. 这个选项可以用来链接到某些原生库文件.

-linker-options args

在二进制文件构建过程中, 向链接程序传递多个参数. 参数之间用空格分隔.

-list-targets

列出可用的硬件目标平台(hardware target).

-manifest path

指定一个 manifest 补充文件.

-module-name name (Native)

为编译产生的模块指定名称. 这个选项也可以用来对导出给 Objective-C 的声明指定名称前缀: 怎样为 Kotlin 框架指定自定义的 Objective-C 前缀?

-native-library path (-nl path)

包含原生的 bitcode 库文件.

-no-default-libs

不要将用户代码与编译器附带的预先构建的 平台库文件 链接.

-nomain

假定外部的库文件会提供应用程序启动时的 main 入口点(entry point).

-nopack

不要将库文件打包进入 klib 文件.

-nostdlib

不要链接到标准库.

-opt

允许编译优化(compilation optimization), 产生运行期性能更好的二进制文件. 不推荐将与 -g 选项组合使用, -g 选项会降低优化级别.

-output name (-o name)

指定编译输出文件的名称.

-produce output (-p output)

指定编译输出文件的类型:

• program

• static

• dynamic

• framework

• library

• bitcode

-repo path (-r path)

库文件的搜索路径. 详情请参见, 库的查找顺序.

-target target

指定编译的硬件目标平台(hardware target). 要查看可选择的硬件目标平台, 请使用 -list-targets 选项.

-Xccall-mode

为通过 cinterop 导入的 C 或 Objective-C 库, 启用 新的互操作模式.

-Xoverride-konan-properties=min.version.*

配置比 Kotlin 默认值更低的 Apple 目标平台最低支持版本. 例如: