Kotlin/Native — what is it, native code compiler and features

What is Kotlin/Native?

Kotlin/Native is a technology for compiling Kotlin code into native machine code, developed by JetBrains. The main difference from Kotlin/JVM is the absence of need for a virtual machine — the resulting executable file contains only machine code and a minimal runtime. This allows running Kotlin applications on devices and systems where JVM is not supported, including iPhone, Apple Watch, and embedded systems.

The history of Kotlin/Native began with a project — an experimental compiler that was integrated into the main Kotlin branch in 2017. In 2019, at KotlinConf, support for iOS as a target platform was announced, which became a turning point for mobile development. Since Kotlin 1.9.20, the Kotlin/Native compiler has achieved stability and is included in Kotlin Multiplatform by default.

The key feature of Kotlin/Native is the use of a common intermediate representation IR, which is compiled into machine code for each platform separately. This provides a unified compilation frontend for all Kotlin backends: JVM, JS, and Native.

How the Kotlin/Native Compiler Works

Compilation in Kotlin/Native goes through several transformation stages. The Kotlin source code is first converted into an internal representation, then optimized and passed to the LLVM backend for machine code generation. The final stage is linking with runtime libraries and creating an executable file or dynamic library.

The architecture includes three key components: frontend (parsing and type checking), IR generator (building intermediate representation), and LLVM backend (machine code generation). This scheme is similar to the approach used in Clang compilers for C++ and Rust.

// Kotlin/Native compilation via command line
kotlinc-native hello.kt -o hello -opt

// Build for iOS arm64 via Kotlin Multiplatform
./gradlew :shared:linkDebugFrameworkIosArm64

For memory management, Kotlin/Native uses its own Memory Manager, based on reference counting with a cycle detector. Since Kotlin 1.7.20, the new memory manager works by default and does not require @ThreadLocal or @SharedImmutable annotations. The garbage collector operates without suspending threads, which is critical for iOS, where the system can forcibly terminate an application during prolonged blocking of the main thread.

Stages of Kotlin/Native Compilation

The compilation process is divided into five stages: parsing (source code analysis), semantic analysis (type checking and name resolution), IR generation (building intermediate representation), optimization (simplification and dead code elimination), and code generation via LLVM. Each stage can be executed in parallel for different modules, which speeds up the build of large projects.

Supported Kotlin/Native Platforms

Kotlin/Native supports 13 target platforms, divided into categories. For mobile development, iOS (arm64), Android (arm32, arm64, x86_64), and watchOS are available. Desktop platforms include macOS (x64, arm64), Windows (mingw x64), and Linux (x64, arm64, arm32). For server and embedded development, WebAssembly and Kotlin/Native on LLVM without OS (standalone) are available. Each platform requires a separate framework or library as output.

Platforms for Mobile Development

For iOS, Kotlin/Native generates a universal framework (.framework) that can be connected to an Xcode project. For Android NDK, native .so libraries are created that can be called via JNI. watchOS is supported since Kotlin 1.6.0, and tvOS since version 1.7.0. Each architecture requires a separate build, but Kotlin Multiplatform automates this process through the Gradle plugin.

Desktop and Server Platforms

macOS and Linux are used for developing native desktop applications in Kotlin using the Compose Multiplatform framework. Windows (MinGW) has been supported since Kotlin 1.3.70 and allows creating Windows applications without installing JVM. For server development, Kotlin/Native can be used in environments where JVM is not available, such as Docker containers with a minimal image based on scratch or Alpine.

Kotlin/Native for iOS Development

iOS is the primary target platform for Kotlin/Native in the context of KMM. The compiler creates an iOS framework containing all shared code, which is then connected to an Xcode project. The framework supports both static and dynamic linking. Kotlin/Native generates Objective-C wrappers for Kotlin classes and functions, providing direct integration with Swift and Objective-C code.

Integration with iOS requires configuring Xcode to connect the generated framework. Kotlin Multiplatform automates this process using the embedAndSignAppleFrameworkForXcode task, which is invoked from Xcode Build Phases. For debugging, Kotlin/Native supports breakpoints in shared module code when running the application on the iOS simulator.

// Kotlin code compiled into iOS framework
package com.itsectr.shared

class GreetingProvider {
    fun createGreeting(): String {
        return "Hello from Kotlin/Native!"
    }

    fun formatVersion(major: Int, minor: Int): String {
        return "v$major.$minor"
    }
}

Objective-C and Swift Interop

Interop with iOS code works in both directions. Kotlin/Native generates Objective-C headers for Kotlin classes, which automatically become accessible from Swift. Reverse communication is provided using the @ObjCName annotation for exporting Kotlin functions under a specified Objective-C name. Kotlin collections are automatically converted to NSArray and NSDictionary, and Kotlin coroutines are wrapped into Combine publishers via the SKIE library. For working with iOS frameworks from Kotlin, cinterop is used — a tool for generating Kotlin bindings to Objective-C headers.

Code Examples: Setup and Compilation

To get started with Kotlin/Native, you need to configure build.gradle.kts with the Kotlin Multiplatform plugin and target platforms. Let's look at a minimal configuration for a KMM project with iOS and Android support.

plugins {
    kotlin("multiplatform") version "2.0.21"
}

kotlin {
    iosArm64()
    iosSimulatorArm64()

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
        iosMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
    }
}

After setting up the build, you can add platform-specific code. Kotlin/Native provides access to iOS functions through Kotlin wrappers. For example, getting the device UUID on iOS requires calling NSUUID from Foundation.

import platform.Foundation.NSUUID

fun getDeviceId(): String {
    return NSUUID().UUIDString()
}

fun currentTimestampMillis(): Long {
    return (platform.Foundation.NSDate().timeIntervalSince1970 * 1000).toLong()
}

Building an iOS Framework

To generate an iOS framework, the Gradle task linkDebugFrameworkIosArm64 or linkReleaseFrameworkIosArm64 for production is used. After the build, the framework is located in build/bin/iosArm64/debugFramework/. Connecting to an Xcode project is done via Pods Podfile or by adding the framework in General → Frameworks, Libraries and Embedded Content.

// Build release framework for iOS arm64
./gradlew :shared:linkReleaseFrameworkIosArm64

// Build universal framework x86_64 + arm64
./gradlew :shared:linkReleaseFrameworkIosX64 \
    :shared:linkReleaseFrameworkIosArm64

// Create XCFramework for App Store
./gradlew :shared:assembleReleaseXCFramework

Kotlin/Native vs Kotlin/JVM: Comparison

Kotlin/Native and Kotlin/JVM differ in architecture, performance, and scope of application. Kotlin/JVM compiles code into bytecode executed on the JVM, which provides access to a vast ecosystem of Java libraries but requires an installed virtual machine. Kotlin/Native generates an executable file with no external dependencies, but with a more limited library ecosystem.

Startup time performance is higher for Kotlin/Native since no JVM loading is required. According to JetBrains benchmarks, a Hello World application on Kotlin/Native starts in 0.003 seconds, while Kotlin/JVM requires 0.5–1 second to load the virtual machine. However, the executable file size of Kotlin/Native can be 2–3 times larger due to the included runtime.

The choice between Kotlin/Native and Kotlin/JVM depends on the target platform. If the project targets iOS or requires minimal resource consumption, Kotlin/Native is the only option. For Android development, Kotlin/JVM remains the standard, although Kotlin/Native is used for NDK components where native performance is needed. In multiplatform projects, Kotlin Multiplatform combines both approaches: shared code is compiled via Kotlin/Native for iOS and via Kotlin/JVM for Android.