改进翻译

Kotlin 编译器选项

每个 Kotlin 版本都包含支持目标的编译器: 用于所支持平台的 JVM、JavaScript 与 Native 二进制文件。

当单击 Kotlin 项目的 Compile运行(Run) 按钮时,IDE 会使用这些编译器。

还可以按照使用命令行编译器 教程中所述在命令行手动运行 Kotlin 编译器

编译器选项

Kotlin 编译器具有许多用于定制编译过程的选项。 此页面列出了针对不同目标的编译器选项,并提供了每个选项的描述。

有几种方法可以设置编译器选项及其值(编译器参数):

  • 在 IntelliJ IDEA 的 设置(Settings) | 构建、执行、部署(Build, Execution, Deployment) | 编译器(Compilers) | Kotlin Compiler 窗口中, 在 附加命令行参数(Additional command-line parameters) 文本框中输入编译器参数。
  • 如果使用 Gradle,请在 Kotlin 编译任务的 kotlinOptions 属性中指定编译器参数。 详情请参见使用 Gradle
  • 如果使用 Maven,请在 Maven 插件节点的 <configuration> 元素中指定编译器参数。 详情请参见使用 Maven
  • 如果运行命令行编译器,则将编译器参数直接添加到工具函数调用中,或将其写入 argfile。 For example:
$ kotlinc hello.kt -include-runtime -d hello.jar

Note: On Windows, when you pass compiler arguments that contain delimiter characters (whitespace, =, ;, ,), surround these arguments with double quotes (").

$ kotlinc.bat hello.kt -include-runtime -d "My Folder\hello.jar"

公共选项

以下选项对于所有 Kotlin 编译器都是通用的。

-version

显示编译器版本。

-nowarn

禁止编译器在编译期间显示警告。

-Werror

将所有警告转换为编译错误。

-verbose

启用详细的日志记录输出,其中包括编译过程的详细信息。

-script

运行 Kotlin 脚本文件。 使用此选项调用时,编译器将执行给定参数中的第一个 Kotlin 脚本文件(*.kts)。

-help (-h)

显示用法信息并退出。仅显示标准选项。 要显示高级选项,请使用 -X

-X

显示有关高级选项的信息并退出。这些选项当前不稳定: 它们的名称与行为可能会更改,恕不另行通知。

-kotlin-home <path>

指定用于发现运行时库的 Kotlin 编译器的自定义路径。

-P plugin:<pluginId>:<optionName>=<value>

将选项传递给 Kotlin 编译器插件。 可用插件及其选项列在编译器插件中。

-language-version <version>

提供与指定版本的 Kotlin 的源代码兼容性。

-api-version <version>

仅允许使用 Kotlin 捆绑库指定版本中的声明。

-progressive

为编译器启用渐进模式

在渐进模式下,针对不稳定代码的弃用与错误修复将立即生效, 而无需经历正常的迁移周期。 以渐进模式编写的代码是向后兼容的。 但是,以非渐进模式编写的代码可能会在渐进模式下导致编译错误。

@<argfile>

从给定文件中读取编译器选项。这样的文件可以包含带有值与源文件路径的编译器选项。 选项与路径应由空格分隔。例如:

-include-runtime -d hello.jar
hello.kt

要传递包含空格的值,请用单引号(')或双引号(")引起来。 如果值中包含引号,请使用反斜杠(\)对其进行转义。

-include-runtime -d 'My folder'

还可以传递多个参数文件,例如,将编译器选项与源文件分开。

$ kotlinc @compiler.options @classes

如果文件位于与当前目录不同的位置,请使用相对路径。

$ kotlinc @options/compiler.options hello.kt

Kotlin/JVM 编译器选项

用于 JVM 的 Kotlin 编译器将 Kotlin 源文件编译为 Java 类文件。 用于 Kotlin 到 JVM 编译的命令行工具是 kotlinckotlinc-jvm。 也可以使用它们来执行 Kotlin 脚本文件。

除了公共选项外,Kotlin/JVM 编译器还具有以下列出的选项。

-classpath <path> (-cp <path>)

在指定的路径中搜索类文件。用系统路径分隔符将类路径的各个元素分开(在Windows上是 ; 在macOS/Linux上是 :)。 类路径可以包含文件和目录路径、ZIP 或 JAR 文件。

-d <path>

将生成的类文件放置到指定位置。该位置可以是目录、ZIP 或 JAR 文件。

-include-runtime

将 Kotlin 运行时包含在生成的 JAR 文件中。 使生成的归档文件可在任何启用 Java 的环境中运行。

-jdk-home <path>

如果自定义 JDK 主目录与默认的 JAVA_HOME 不同,请使用它来将其包含在类路径中。

-jvm-target <version>

指定生成的 JVM 字节码的目标版本。可能的值为 1.61.891011121314。 默认值为 1.6

-java-parameters

为 Java 1.8 反射方法参数生成元数据。

-module-name <name>

为生成的 .kotlin_module 文件设置自定义名称。

-no-jdk

不要自动将 Java 运行时包含在类路径中。

-no-reflect

不要自动将 Kotlin 反射(kotlin-reflect.jar)包含到类路径中。

-no-stdlib

不要自动将 Kotlin/JVM 标准库(kotlin-stdlib.jar)与 Kotlin 反射(kotlin-reflect.jar)包含到类路径中。

-script-templates <classnames[,]>

脚本定义模板类。使用完全限定的类名,并用逗号(,)分隔。

Kotlin/JS 编译器选项

JS 的 Kotlin 编译器将 Kotlin 源文件编译为 JavaScript 代码。 Kotlin 到 JS 编译的命令行工具是 kotlinc-js

除了公共选项外,Kotlin/JS 编译器还具有以下列出的选项。

-libraries <path>

具有 .meta.js.kjsm 文件的 Kotlin 库的路径,由系统路径分隔符分隔。

-main {call|noCall}

定义是否应在执行时调用 main 函数。

-meta-info

使用元数据生成 .meta.js.kjsm 文件。 创建 JS 库时使用此选项。

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

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

要了解有关不同类型的 JS 模块及其之间区别的更多信息, 请参见这篇文章

-no-stdlib

不要自动将默认的 Kotlin/JS 标准库包含在编译依赖项中。

-output <filepath>

设置编译结果的目标文件。该值必须是包含其名称的 .js 文件的路径。

-output-postfix <filepath>

将指定文件的内容添加到输出文件的末尾。

-output-prefix <filepath>

将指定文件的内容添加到输出文件的开头。

-source-map

生成源代码映射。

-source-map-base-dirs <path>

使用指定的路径作为基本目录。基本目录用于计算源代码映射中的相对路径。

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

将源代码文件嵌入到源代码映射中。

-source-map-prefix

将指定的前缀添加到源代码映射中的路径。

Kotlin/Native 编译器选项

Kotlin/Native 编译器将 Kotlin 源代码文件编译为用于所支持平台的 Native 二进制文件。 Kotlin/Native 编译的命令行工具是 kotlinc-native

除了公共选项外,Kotlin/Native 编译器还具有以下列出的选项。

-enable-assertions (-ea)

在生成的代码中启用运行时断言。

-g

启用输出调试信息。

-generate-test-runner (-tr)

生成一个用于运行项目中的单元测试的应用程序。

-generate-worker-test-runner (-trw)

生成一个用于在 Worker 线程中运行单元测试的应用程序。

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

生成一个用于运行单元测试的应用程序,而无需显式退出进程。

-include-binary <path> (-ib <path>)

在生成的 klib 文件中打包外部二进制文件。

-library <path> (-l <path>)

与库链接。要了解有关在 Kotlin/native 项目中使用库的信息, 请参见 Kotlin/Native 库

-library-version <version> (-lv)

设置库版本。

-list-targets

列出可用的硬件目标。

-manifest <path>

提供清单附加文件。

-module-name <name>

指定编译模块的名称。 此选项还可用于为导出到 Objective-C 的声明指定名称前缀: 如何为 Kotlin 框架指定自定义的 Objective-C 前缀/名称?

-native-library <path>(-nl <path>)

包含 Native Bitcode 库。

-no-default-libs

禁止将用户代码与编译器一起分发的默认平台库链接。

-nomain

假定要由外部库提供的 main 入口点。

-nopack

不要将库打包到 klib 文件中。

-linker-option

在二进制构建过程中,将参数传递给链接器。这可用于链接到某些 Native 库。

-linker-options <args>

在二进制构建过程中,将多个参数传递给链接器。用空格分隔参数。

-nostdlib

不要与标准库链接。

-opt

启用编译优化。

-output <name> (-o <name>)

设置输出文件的名称。

-entry <name> (-e <name>)

指定限定的入口点名称。

-produce <output> (-p)

指定输出文件的种类:

  • program
  • static
  • dynamic
  • framework
  • library
  • bitcode

-repo <path> (-r <path>)

库搜索路径。有关更多信息,请参见库搜索顺序

-target <target>

设置硬件目标。要查看可用目标的列表,请使用 -list-targets 选项。