Kotlin/Native binary options

This page lists helpful Kotlin/Native binary options that you can use to configure Kotlin/Native final binaries and the ways to set up binary options in your project.

How to enable

You can enable binary options in the gradle.properties file, your build file, or pass them as compiler arguments.

In Gradle properties

You can set binary options in your project's gradle.properties file using the kotlin.native.binary property. For example:

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

In your build file

You can set binary options for your project in your build.gradle.kts file:

For specific binaries using the binaryOption attribute. For example:
kotlin { iosArm64 { binaries { framework { binaryOption("smallBinary", "true") } } } }
As -Xbinary=$option=$value compiler options in the freeCompilerArgs attribute. For example:
kotlin { iosArm64 { compilations.configureEach { compilerOptions.configure { freeCompilerArgs.add("-Xbinary=smallBinary=true") } } } }

In the command-line compiler

You can pass binary options as -Xbinary=$option=$value directly in the command line when executing the Kotlin/Native compiler. For example:

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

Binary options

Option	Values	Description	Status
`smallBinary`	`true` `false` (default)	Decreases the binary size for release binaries.	Experimental since 2.2.20
`stackProtector`	`yes` `strong` `all` `no` (default)	Enables stack canaries: use `yes` for vulnerable functions, `all` for all functions, and `strong` to use a stronger heuristic.	Available since 2.2.20
`pagedAllocator`	`true` (default) `false`	Controls paging of allocations (buffering). When `false`, the memory allocator reserves memory on a per-object basis.	Experimental since 2.2.0
`latin1Strings`	`true` `false` (default)	Controls support for Latin-1-encoded strings to reduce application binary size and adjust memory consumption.	Experimental since 2.2.0
`mmapTag`	`UInt`	Controls memory tagging, necessary for memory consumption tracking on Apple platforms. Values `240`-`255` are available (default is `246`); `0` disables tagging.	Available since 2.2.0
`disableMmap`	`true` `false` (default)	Controls the default allocator. When `true`, uses the `malloc` memory allocator instead of `mmap`.	Available since 2.2.0
`gc`	`pmcs` (default) `stwms` `cms` `noop`	Controls garbage collection behavior: `pmcs` uses parallel mark concurrent sweep `stwms` uses simple stop-the-world mark and sweep `cms` enables concurrent marking that helps decrease GC pause time `noop` disables garbage collection	`cms` is Experimental since 2.0.20
`gcMarkSingleThreaded`	`true` `false` (default)	Disables parallelization of the mark phase in garbage collection. May increase GC pause time on large heaps.	Available since 1.7.20
`enableSafepointSignposts`	`true` `false` (default)	Enables tracking GC-related pauses in the project for debugging in Xcode Instruments.	Available since 2.0.20
`preCodegenInlineThreshold`	`UInt`	Configures inlining optimization pass in the Kotlin IR compiler, which comes before the actual code generation phase (disabled by default). The recommended number of tokens (code units parsed by the compiler) is 40.	Experimental since 2.1.20
`objcDisposeOnMain`	`true` (default) `false`	Controls deinitialization of Swift/Objective-C objects. When `false`, deinitialization happens on a special GC thread instead of the main one.	Available since 1.9.0
`appStateTracking`	`enabled` `disabled` (default)	Controls timer-based invocation of the garbage collector when the application runs in the background. When `enabled`, GC is called only when memory consumption becomes too high.	Experimental since 1.7.20
`bundleId`	`String`	Sets bundle ID (`CFBundleIdentifier`) in the `Info.plst` file.	Available since 1.7.20
`bundleShortVersionString`	`String`	Sets short bundle version (`CFBundleShortVersionString`) in the `Info.plst` file.	Available since 1.7.20
`bundleVersion`	`String`	Sets bundle version (`CFBundleVersion`) in the `Info.plst` file.	Available since 1.7.20
`sourceInfoType`	`libbacktrace` `coresymbolication` (Apple targets) `noop` (default)	Adds file locations and line numbers to exception stack traces. `coresymbolication` is only available for Apple targets and enabled by default for macOS and Apple simulators in debug mode.	Experimental since 1.6.20

What's next

Learn how to build final native binaries.

19 August 2025