Kotlin/Native 二进制选项

本页面列出了有用的 Kotlin/Native 二进制选项，你可以使用它们来配置 Kotlin/Native 最终二进制文件，以及在项目中设置二进制选项的方式。

如何启用

你可以在 gradle.properties 文件、你的构建文件中启用二进制选项，或者将它们作为编译器实参传递。

在 Gradle 属性中

你可以在项目的 gradle.properties 文件中使用 kotlin.native.binary 属性设置二进制选项。例如：

kotlin.native.binary.gc=cms
kotlin.native.binary.latin1Strings=true

在你的构建文件中

你可以在 build.gradle.kts 文件中为你的项目设置二进制选项：

• 对于特定的二进制文件，使用 binaryOption 属性。例如：

  kotlin {
      iosArm64 {
          binaries {
              framework {
                  binaryOption("smallBinary", "true")
              }
          }
      }
  }

• 作为 -Xbinary=$option=$value 编译器选项，在 freeCompilerArgs 属性中。例如：

  kotlin {
      iosArm64 {
          compilations.configureEach {
              compilerOptions.configure {
                  freeCompilerArgs.add("-Xbinary=smallBinary=true")
              }
          }
      }
  }

在命令行编译器中

你可以在执行 Kotlin/Native 编译器时，在命令行中直接传递 -Xbinary=$option=$value 作为二进制选项。例如：

kotlinc-native main.kt -Xbinary=enableSafepointSignposts=true

二进制选项

此表格并非所有现有选项的详尽列表，仅包含最值得注意的选项。

选项	值	描述	状态
smallBinary	true false (默认)	减小发行版二进制文件的大小。	自 2.2.20 起为实验性的
stackProtector	yes strong all no (默认)	启用栈金丝雀：`yes` 用于易受攻击的函数，`all` 用于所有函数，`strong` 用于更强的启发式方法。	自 2.2.20 起可用
pagedAllocator	true (默认) false	控制分配的（缓冲）分页。当为 `false` 时，内存分配器会按对象预留内存。	自 2.2.0 起为实验性的
latin1Strings	true false (默认)	控制对 Latin-1 编码字符串的支持，以减小应用程序二进制文件大小并调整内存消耗。	自 2.2.0 起为实验性的
mmapTag	UInt	控制内存标记，对于 Apple 平台上的内存消耗跟踪是必需的。可用值 `240`-`255`（默认为 `246`）；`0` 禁用标记。	自 2.2.0 起可用
disableMmap	true false (默认)	控制默认分配器。当为 `true` 时，使用 `malloc` 内存分配器而不是 `mmap`。	自 2.2.0 起可用
gc	pmcs (默认) stwms cms noop	控制垃圾回收行为： pmcs 使用并行标记并发清除 stwms 使用简单的全停顿标记清除 cms 启用并发标记，有助于减少 GC 暂停时间 noop 禁用垃圾回收	cms 自 2.0.20 起为实验性的
gcMarkSingleThreaded	true false (默认)	禁用垃圾回收中标记阶段的并行化。在大型堆上可能会增加 GC 暂停时间。	自 1.7.20 起可用
enableSafepointSignposts	true false (默认)	在项目中启用 GC 相关暂停的跟踪，以便在 Xcode Instruments 中进行调试。	自 2.0.20 起可用
preCodegenInlineThreshold	UInt	配置 Kotlin IR 编译器中的内联优化过程，该过程在实际代码生成阶段之前（默认为禁用）。 建议的 token 数量（由编译器解析的代码单元）为 40。	自 2.1.20 起为实验性的
objcDisposeOnMain	true (默认) false	控制 Swift/Objective-C 对象的去初始化。当为 `false` 时，去初始化发生在特殊的 GC 线程而不是主线程上。	自 1.9.0 起可用
appStateTracking	enabled disabled (默认)	控制应用程序在后台运行时，基于计时器调用垃圾回收器。 当 `enabled` 时，仅当内存消耗过高时才调用 GC。	自 1.7.20 起为实验性的
bundleId	String	在 `Info.plst` 文件中设置 bundle ID (`CFBundleIdentifier`)。	自 1.7.20 起可用
bundleShortVersionString	String	在 `Info.plst` 文件中设置短 bundle 版本 (`CFBundleShortVersionString`)。	自 1.7.20 起可用
bundleVersion	String	在 `Info.plst` 文件中设置 bundle 版本 (`CFBundleVersion`)。	自 1.7.20 起可用
sourceInfoType	libbacktrace coresymbolication (Apple targets) noop (默认)	将文件位置和行号添加到异常栈追踪中。 `coresymbolication` 仅适用于 Apple [目标平台](...)，并且在调试模式下为 macOS 和 Apple 模拟器默认启用。	自 1.6.20 起为实验性的

关于稳定性级别的更多信息，请参见文档。

接下来

了解如何构建最终的原生二进制文件。