# Kotlin/Native 二进制文件选项

本章列出了实用的 Kotlin/Native 二进制文件选项, 可以用来配置 Kotlin/Native [最终二进制文件](multiplatform-build-native-binaries.html), 还介绍了在项目中设置二进制文件选项的方法.

## 如何启用

你可以在 `gradle.properties` 文件或构建文件中, 启用二进制文件选项, 也可以将这些选项传递为编译器参数.

### 在 Gradle 属性文件中

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

```PROPERTIES
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 编译器](native-get-started.html#using-the-command-line-compiler) 时, 在命令行中, 以 `-Xbinary=$option=$value` 的形式, 直接传递二进制文件选项. 例如:

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

## 二进制文件选项

> **Note:**
> 这里列出的并不是现有选项的完整列表, 只列出了最值得关注的选项.

| 选项 | 值 | 说明 | 状态 |
| --- | --- | --- | --- |
| [enableReleaseBinaryCache](native-improving-compilation-time.html) |      * `true`    * `false` (默认值)    | 允许编译器在发布模式中使用缓存, 能够加快构建速度, 但会损失一部分编译器优化. | 从 2.4.20 开始, 为实验性功能 |
| [objcExportBlockExplicitParameterNames](native-objc-interop.html#explicit-parameter-names-in-objective-c-block-types) |      * `true`    * `false (默认值)`    | 为导出的 Objective-C 头文件中的函数类型, 添加明确的参数名称. | 从 2.2.20 开始, 为实验性功能 |
| [smallBinary](whatsnew2220.html#smaller-binary-size-for-release-binaries) |      * `true`    * `false` (默认值)    | 减小发布版本二进制文件的大小. | 从 2.2.20 开始, 为实验性功能 |
| [stackProtector](whatsnew2220.html#support-for-stack-canaries-in-binaries) |      * `yes`    * `strong`    * `all`    * `no` (默认值)    | 启用栈金丝雀(Stack Canary): 对易受攻击的函数使用 `yes`, 对所有函数使用 `all`, 使用 `strong` 采用更强的启发式算法. | 从 2.2.20 开始可用 |
| [pagedAllocator](native-memory-manager.html#disable-allocator-paging) |      * `true` (默认值)    * `false`    | 控制分配(缓冲)的分页. 当值为 `false` 时, 内存分配器按对象为单位预留内存. | 从 2.2.0 开始, 为实验性功能 |
| [latin1Strings](native-memory-manager.html#enable-support-for-latin-1-strings) |      * `true`    * `false` (默认值)    | 控制对 Latin-1 编码字符串的支持, 以减小应用程序二进制文件大小, 并调整内存消耗. | 从 2.2.0 开始, 为实验性功能 |
| [mmapTag](native-memory-manager.html#track-memory-consumption-on-apple-platforms) | `UInt` | 控制内存标记, 在 Apple 平台上跟踪内存消耗需要这个功能. 可用值为 `240`-`255`(默认值为 `246`); `0` 禁用内存标记. | 从 2.2.0 开始可用 |
| `disableMmap` |      * `true`    * `false` (默认值)    | 控制默认的内存分配器. 当值为 `true` 时, 使用 `malloc` 内存分配器, 而不是 `mmap`. | 从 2.2.0 开始可用 |
| [gc](native-memory-manager.html#garbage-collector) |      * `cms` (默认值)    * `pmcs`    * `stwms`    * [noop](native-memory-manager.html#disable-garbage-collection)    | 控制垃圾收集行为:     * `cms` 使用并发的标记和清除    * `pmcs` 使用并行的标记和并发的清除    * `stwms` 使用简单的完全停顿标记和清除    * `noop` 禁用垃圾收集    | 从 2.4.0 开始, 默认值为 `cms` |
| [gcMarkSingleThreaded](native-memory-manager.html#garbage-collector) |      * `true`    * `false` (默认值)    | 禁用垃圾收集中标记阶段的并行化. 在大尺寸的堆上, 可能会增加 GC 暂停时间. | 从 1.7.20 开始可用 |
| [enableSafepointSignposts](native-memory-manager.html#monitor-gc-performance) |      * `true`    * `false` (默认值)    | 启用对项目中 GC 相关暂停的跟踪, 用于在 Xcode Instruments 中调试. | 从 2.0.20 开始可用 |
| `preCodegenInlineThreshold` | `UInt` |    在 Kotlin IR 编译器中配置内联优化过程, 这个过程在实际代码生成阶段之前执行(默认为禁用).     推荐的 token 数量(编译器解析的代码单元)为 40.    | 从 2.1.20 开始, 为实验性功能 |
| [objcDisposeOnMain](native-arc-integration.html#deinitializers) |      * `true` (默认值)    * `false`    | 控制 Swift/Objective-C 对象的反初始化. 当值为 `false` 时, 反初始化在特殊的 GC 线程上进行, 而不是在主线程上. | 从 1.9.0 开始可用 |
| [appStateTracking](native-arc-integration.html#support-for-background-state-and-app-extensions) |      * `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 目标平台)    * `noop` (默认值)    |    向异常的堆栈跟踪(Stack Trace)添加文件位置和行号信息.     `coresymbolication` 只能用于 Apple 目标平台, 并且在调试模式下, 对 macOS 和 Apple 模拟器默认启用.    | 从 1.6.20 开始, 为实验性功能 |

> **Tip:**
> 关于稳定性级别, 详情请参见 [相关文档](components-stability.html#stability-levels-explained).

## 下一步做什么?

了解如何 [构建最终的原生二进制文件](multiplatform-build-native-binaries.html).