Kotlin/Native 二進制選項

本頁面列出了實用的 Kotlin/Native 二進制選項，您可以用來配置 Kotlin/Native 最終二進制檔案，以及在專案中設定二進制選項的方法。

如何啟用

您可以在 gradle.properties 檔案、您的組建檔案中啟用二進制選項，或者將它們作為編譯器引數傳遞。

在 Gradle 屬性中

您可以使用 kotlin.native.binary 屬性在專案的 gradle.properties 檔案中設定二進制選項。例如：

kotlin.native.binary.latin1Strings=true

在您的組建檔案中

您可以在 build.gradle.kts 檔案中為專案設定二進制選項：

• 使用 binaryOption 屬性針對特定二進制檔案。例如：

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

• 作為 freeCompilerArgs 屬性中的 -Xbinary=$option=$value 編譯器選項。例如：

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

在命令列編譯器中

執行 Kotlin/Native 編譯器時，您可以直接在命令列中以 -Xbinary=$option=$value 形式傳遞二進制選項。 例如：

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) 標記與清除 noop 停用垃圾收集	cms 自 2.4.0 起為預設
gcMarkSingleThreaded	true false (預設)	停用垃圾收集標記階段的平行化。在大堆積上可能會增加 GC 暫停時間。	自 1.7.20 起提供
enableSafepointSignposts	true false (預設)	啟用追蹤專案中與 GC 相關的暫停，以便在 Xcode Instruments 中進行偵錯。	自 2.0.20 起提供
preCodegenInlineThreshold	UInt	在 Kotlin IR 編譯器中配置內嵌最佳化傳遞，這發生在實際程式碼產生階段之前（預設停用）。 建議的語彙單元（由編譯器剖析的程式碼單元）數量為 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 檔案中設定套件 ID (CFBundleIdentifier)。	自 1.7.20 起提供
bundleShortVersionString	String	在 Info.plst 檔案中設定短套件版本號 (CFBundleShortVersionString)。	自 1.7.20 起提供
bundleVersion	String	在 Info.plst 檔案中設定套件版本號 (CFBundleVersion)。	自 1.7.20 起提供
sourceInfoType	libbacktrace coresymbolication (Apple 目標) noop (預設)	在例外堆疊追蹤中加入檔案位置與行號。 coresymbolication 僅可用於 Apple 目標，且在偵錯模式下預設為 macOS 與 Apple 模擬器啟用。	自 1.6.20 起為實驗性

欲了解更多關於穩定性級別的資訊，請參閱文件。

下一步

了解如何組建最終原生二進制檔案。