diff --git a/docs/kr.tree b/docs/kr.tree index 1e993fc6764..eb96b7894ec 100644 --- a/docs/kr.tree +++ b/docs/kr.tree @@ -202,6 +202,7 @@ + diff --git a/docs/topics/native/native-binary-options.md b/docs/topics/native/native-binary-options.md new file mode 100644 index 00000000000..d79a80d67da --- /dev/null +++ b/docs/topics/native/native-binary-options.md @@ -0,0 +1,328 @@ +[//]: # (title: Kotlin/Native binary options) + +This page lists helpful Kotlin/Native binary options that you can use to configure Kotlin/Native [final binaries](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-build-native-binaries.html) +and the ways to set them up 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 `kotlin.native.binary`, for example: + +```none +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 + kotlin { + iosArm64 { + binaries { + framework { + binaryOption("smallBinary", "true") + } + } + } + } + ``` + +* As `-Xbinary=$option=$value` compiler options in the `freeCompilerArgs` attribute, for example: + + ```kotlin + 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](native-get-started.md#using-the-command-line-compiler), +for example: + +```bash +kotlinc-native main.kt -Xbinary=enableSafepointSignposts=true +``` + +## Binary options + +> This table is not an exhaustive list of all the existing options, only the most notable ones. +> +{style="note"} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionValuesDescriptionStatus
smallBinary + +
  • true
    • +
  • false (default)
    • +     +     		Decreases the binary size for iOS targets.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 utilize 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
    mmapTagUIntControls memory tagging, necessary for memory consumption tracking on Apple platforms. Values 240-255 are available (default is 246); 0 disables taggingAvailable 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
    preCodegenInlineThresholdUInt +

    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
    + +> For more information on stability levels, see the [documentation](components-stability.md#stability-levels-explained). +> +{style="tip"} + +## What's next + +Learn how to [build final native binaries](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-build-native-binaries.html).