Kotlin/Nativeのバイナリオプション

このページでは、Kotlin/Nativeの最終バイナリ (final binaries)の設定に使用できる便利なKotlin/Nativeバイナリオプションと、プロジェクトでバイナリオプションを設定する方法について説明します。

有効化する方法

バイナリオプションは、gradle.properties ファイル、ビルドファイルで設定するか、コンパイラ引数として渡すことで有効にできます。

Gradleプロパティでの設定

プロジェクトの gradle.properties ファイルで kotlin.native.binary プロパティを使用して、バイナリオプションを設定できます。例：

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より実験的 (Experimental)
smallBinary	true false (デフォルト)	リリースバイナリのバイナリサイズを削減します。	2.2.20より実験的 (Experimental)
stackProtector	yes strong all no (デフォルト)	スタックカナリア (stack canaries) を有効にします：脆弱な関数には yes、すべての関数には all を使用し、より強力なヒューリスティックを使用するには strong を使用します。	2.2.20より利用可能
pagedAllocator	true (デフォルト) false	アロケーションのページング（バッファリング）を制御します。false の場合、メモリアロケータはオブジェクトごとにメモリを確保します。	2.2.0より実験的 (Experimental)
latin1Strings	true false (デフォルト)	アプリケーションのバイナリサイズを削減し、メモリ消費を調整するために、Latin-1エンコードされた文字列のサポートを制御します。	2.2.0より実験的 (Experimental)
mmapTag	UInt	メモリタグ付けを制御します。Appleプラットフォームでのメモリ消費量の追跡に必要です。240〜255 の値が使用可能です（デフォルトは 246）。0 はタグ付けを無効にします。	2.2.0より利用可能
disableMmap	true false (デフォルト)	デフォルトのアロケータを制御します。true の場合、mmap の代わりに malloc メモリアロケータを使用します。	2.2.0より利用可能
gc	cms (デフォルト) pmcs stwms noop	ガベージコレクションの動作を制御します： cms はコンカレントマーク・アンド・スイープ (concurrent mark and sweep) を使用します pmcs は並列マーク・コンカレントスイープ (parallel mark concurrent sweep) を使用します stwms は単純なストップ・ザ・ワールド・マーク・アンド・スイープ (stop-the-world mark and sweep) を使用します noop はガベージコレクションを無効にします	2.4.0より cms がデフォルト
gcMarkSingleThreaded	true false (デフォルト)	ガベージコレクションにおけるマークフェーズの並列化を無効にします。大きなヒープではGCの停止時間が増加する可能性があります。	1.7.20より利用可能
enableSafepointSignposts	true false (デフォルト)	Xcode Instrumentsでのデバッグ用に、プロジェクト内のGC関連の停止の追跡を有効にします。	2.0.20より利用可能
preCodegenInlineThreshold	UInt	実際のコード生成フェーズの前に行われる、Kotlin IRコンパイラでのインライニング最適化パスを設定します（デフォルトでは無効）。 推奨されるトークン数（コンパイラによって解析されるコード単位）は40です。	2.1.20より実験的 (Experimental)
objcDisposeOnMain	true (デフォルト) false	Swift/Objective-Cオブジェクトのデニシャライズ（deinitialization）を制御します。false の場合、デニシャライズはメインスレッドではなく特別なGCスレッドで行われます。	1.9.0より利用可能
appStateTracking	enabled disabled (デフォルト)	アプリケーションがバックグラウンドで実行されているときの、タイマーベースのガベージコレクタの呼び出しを制御します。 enabled の場合、メモリ消費が高くなったときにのみGCが呼び出されます。	1.7.20より実験的 (Experimental)
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より実験的 (Experimental)

安定性レベルの詳細については、ドキュメントを参照してください。

次のステップ

最終的なネイティブバイナリを構築する方法を確認してください。