Kotlin/Native 二进制选项

本页列出了有助于配置 Kotlin/Native 最终二进制文件的 Kotlin/Native 二进制选项，以及在项目中设置二进制选项的方法。

如何启用

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

在 Gradle 属性中

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

none

kotlin.native.binary.latin1Strings=true

在构建文件中

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

使用 binaryOption 属性为特定二进制文件设置。例如：

kotlin

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

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

kotlin

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

在命令行编译器中

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

bash

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

二进制选项

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

选项	值	描述	状态
`objcExportBlockExplicitParameterNames`	`true` `false (默认)`	为导出的 Objective-C 头文件中的函数类型添加显式形参名称。	自 2.2.20 起处于实验性阶段
`smallBinary`	`true` `false` (默认)	减小发布二进制文件的二进制文件大小。	自 2.2.20 起处于实验性阶段
`stackProtector`	`yes` `strong` `all` `no` (默认)	启用栈保护 (stack canaries)：对易受攻击的函数使用 `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`	`cms` (默认) `pmcs` `stwms` `noop`	控制垃圾回收行为： `cms` 使用并发标记清除 (concurrent mark and sweep) `pmcs` 使用并行标记并发清除 (parallel mark concurrent sweep) `stwms` 使用简单的 Stop-The-World 标记清除 (simple stop-the-world mark and sweep) `noop` 禁用垃圾回收	`cms` 自 2.4.0 起为默认设置
`gcMarkSingleThreaded`	`true` `false` (默认)	禁用垃圾回收中标记阶段的并行化。在大堆上可能会增加垃圾回收暂停时间。	自 1.7.20 起可用
`enableSafepointSignposts`	`true` `false` (默认)	在项目中启用跟踪与垃圾回收相关的暂停，以便在 Xcode Instruments 中进行调试。	自 2.0.20 起可用
`preCodegenInlineThreshold`	`UInt`	在 Kotlin IR 编译器中配置内联优化传递，该步骤在实际的代码生成阶段之前执行（默认禁用）。建议的令牌（编译器解析的代码单元）数量为 40。	自 2.1.20 起处于实验性阶段
`objcDisposeOnMain`	`true` (默认) `false`	控制 Swift/Objective-C 对象的去初始化。当为 `false` 时，去初始化发生在特殊的垃圾回收线程上，而不是主线程上。	自 1.9.0 起可用
`appStateTracking`	`enabled` `disabled` (默认)	当应用在后台运行时，控制基于定时器的垃圾回收器调用。当设置为 `enabled` 时，仅在内存消耗过高时才调用垃圾回收。	自 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 目标) `noop` (默认)	向异常堆栈跟踪中添加文件位置和行号。 `coresymbolication` 仅适用于 Apple 目标，并在调试模式下默认对 macOS 和 Apple 模拟器启用。	自 1.6.20 起处于实验性阶段

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

下一步

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

Kotlin/Native 二进制选项 ​

如何启用 ​

在 Gradle 属性中 ​

在构建文件中 ​

在命令行编译器中 ​

二进制选项 ​

下一步 ​