Build final native binaries (Experimental DSL)

Kotlin/Native targets are compiled to the *.klib library artifacts, which can be consumed by Kotlin/Native itself as a dependency but cannot be used as a native library.

To declare final native binaries, use the new binaries format with the kotlinArtifacts DSL. It represents a collection of native binaries built for this target in addition to the default *.klib artifact and provides a set of methods for declaring and configuring them.

Kotlin artifact DSL can help you to solve a common issue: when you need to access multiple Kotlin modules from your app. Since the usage of several Kotlin/Native artifacts is limited, you can export multiple Kotlin modules into a single artifact with new DSL.

Declare binaries

kotlinArtifacts {} is the top-level block for artifact configuration in the Gradle build script. Use the following kinds of binaries to declare elements of the kotlinArtifacts {} DSL:

Factory method	Binary kind	Available for
`sharedLib`	Shared native library	All native targets, except for `WebAssembly`
`staticLib`	Static native library	All native targets, except for `WebAssembly`
`framework`	Objective-C framework	macOS, iOS, watchOS, and tvOS targets only
`fatFramework`	Universal fat framework	macOS, iOS, watchOS, and tvOS targets only
`XCFramework`	XCFramework framework	macOS, iOS, watchOS, and tvOS targets only

Inside the kotlinArtifacts element, you can write the following blocks:

Native.Library
Native.Framework
Native.FatFramework
Native.XCFramework

The simplest version requires the target (or targets) parameter for the selected build type. Currently, two build types are available:

DEBUG – produces a non-optimized binary with debug information
RELEASE – produces an optimized binary without debug information

In the modes parameter, you can specify build types for which you want to create binaries. The default value includes both DEBUG and RELEASE executable binaries:

kotlinArtifacts {
    Native.Library {
        target = iosX64 // Define your target instead
        modes(DEBUG, RELEASE)
        // Binary configuration
    }
}

kotlinArtifacts {
    it.native.Library {
        target = iosX64 // Define your target instead
        modes(DEBUG, RELEASE)
        // Binary configuration
    }
}

You can also declare binaries with custom names:

kotlinArtifacts {
    Native.Library("mylib") {
        // Binary configuration
    }
}

kotlinArtifacts {
    it.native.Library("mylib") {
        // Binary configuration
    }
}

The argument sets a name prefix, which is the default name for the binary file. For example, for Windows the code produces the mylib.dll file.

Configure binaries

For the binary configuration, the following common parameters are available:

Name	Description
`isStatic`	Optional linking type that defines the library type. By default, it's `false` and the library is dynamic.
`modes`	Optional build types, `DEBUG` and `RELEASE`.
`kotlinOptions`	Optional compiler options applied to the compilation. See the list of available compiler options.
`addModule`	In addition to the current module, you can add other modules to the resulting artifact.
`setModules`	You can override the list of all modules that will be added to the resulting artifact.
`target`	Declares a particular target of a project. The names of available targets are listed in the Targets section.

Libraries and frameworks

When building an Objective-C framework or a native library (shared or static), you may need to pack not just the classes of the current project but also the classes of any other multiplatform module into a single entity and export all these modules to it.

Library

kotlinArtifacts {
    Native.Library("myslib") {
        target = linuxX64
        isStatic = false
        modes(DEBUG)
        addModule(project(":lib"))
        kotlinOptions {
            verbose = false
            freeCompilerArgs += "-Xmen=pool"
        }
    }
}

kotlinArtifacts {
    it.native.Library("myslib") {
        target = linuxX64
        it.static = false
        modes(DEBUG)
        addModule(project(":lib"))
        kotlinOptions {
            verbose = false
            freeCompilerArgs += "-Xmen=pool"
        }
    }
}

The registered Gradle task is assembleMyslibSharedLibrary that assembles all types of registered "myslib" into a dynamic library.

Framework

kotlinArtifacts {
    Native.Framework("myframe") {
        modes(DEBUG, RELEASE)
        target = iosArm64
        isStatic = false
        kotlinOptions {
            verbose = false
        }
    }
}

kotlinArtifacts {
    it.native.Framework("myframe") {
        modes(DEBUG, RELEASE)
        target = iosArm64
        it.static = false
        kotlinOptions {
            verbose = false
        }
    }
}

The registered Gradle task is assembleMyframeFramework that assembles all types of registered "myframe" framework.

Fat frameworks

By default, an Objective-C framework produced by Kotlin/Native supports only one platform. However, you can merge such frameworks into a single universal (fat) binary. This especially makes sense for 32-bit and 64-bit iOS frameworks. In this case, you can use the resulting universal framework on both 32-bit and 64-bit devices.

kotlinArtifacts {
    Native.FatFramework("myfatframe") {
        targets(iosX32, iosX64)
        kotlinOptions {
            suppressWarnings = false
        }
    }
}

kotlinArtifacts {
    it.native.FatFramework("myfatframe") {
        targets(iosX32, iosX64)
        kotlinOptions {
            suppressWarnings = false
        }
    }
}

The registered Gradle task is assembleMyfatframeFatFramework that assembles all types of registered "myfatframe" fat framework.

XCFrameworks

All Kotlin Multiplatform projects can use XCFrameworks as an output to gather logic for all the target platforms and architectures in a single bundle. Unlike universal (fat) frameworks, you don't need to remove all unnecessary architectures before publishing the application to the App Store.

kotlinArtifacts {
    Native.XCFramework("sdk") {
        targets(iosX64, iosArm64, iosSimulatorArm64)
        setModules(
            project(":shared"),
            project(":lib")
        )
    }
}

kotlinArtifacts {
    it.native.XCFramework("sdk") {
        targets(iosX64, iosArm64, iosSimulatorArm64)
        setModules(
            project(":shared"), 
            project(":lib")
        )
    }
}

The registered Gradle task is assembleSdkXCFramework that assembles all types of registered "sdk" XCFrameworks.

Last modified: 25 September 2024