Tips for improving compilation time

This way, you always get the latest performance improvements. The most recent Kotlin version is 2.1.20.

Try to avoid huge classes that take a long time to compile and load during execution.

When compiling projects, Kotlin/Native downloads the required components and caches some results of its work to the $USER_HOME/.konan directory. The compiler uses this directory for subsequent compilations, making them take less time to complete.

When building in containers (such as Docker) or with continuous integration systems, the compiler may have to create the ~/.konan directory from scratch for each build. To avoid this step, configure your environment to preserve ~/.konan between builds. For example, redefine its location using the kotlin.data.dir Gradle property.

Alternatively, you can use the -Xkonan-data-dir compiler option to configure your custom path to the directory via the cinterop and konanc tools.

To increase the Gradle heap size, add org.gradle.jvmargs=-Xmx3g to your gradle.properties file.

If you use parallel builds, you might need to choose the right number of workers with the org.gradle.workers.max property or the --max-workers command-line option. The default value is the number of CPU processors.

Don't run Gradle tasks that build the whole project, such as build or assemble, unless you really need to. These tasks build the same code more than once, increasing the compilation times. In typical cases, such as running tests from IntelliJ IDEA or starting the app from Xcode, the Kotlin tooling avoids executing unnecessary tasks.

If you have a non-typical case or build configuration, you might need to choose the task yourself:

• linkDebug*. To run your code during development, you usually need only one binary, so running the corresponding linkDebug* task should be enough.

• embedAndSignAppleFrameworkForXcode. Since iOS simulators and devices have different processor architectures, it's a common approach to distribute a Kotlin/Native binary as a universal (fat) framework.

  However, during local development, it's faster to build the .framework file only for the platform you're using. To build a platform-specific framework, use the embedAndSignAppleFrameworkForXcode task.

Similarly to the recommendation above, don't build a binary for all native platforms at once. For example, compiling an XCFramework (using an *XCFramework task) builds the same code for all targets, which takes proportionally more time than building for a single target.

If you do need XCFrameworks for your setup, you can reduce the number of targets. For example, you don't need iosX64 if you don't run this project on iOS simulators on Intel-based Macs.

tip

Binaries for different targets are built with linkDebug*$Target and linkRelease*$Target Gradle tasks. You can look for the executed tasks in the build log or in the Gradle build scan by running a Gradle build with the --scan option.

Kotlin/Native supports two build modes, debug and release. Release is highly optimized, and this takes a lot of time: compilation of release binaries takes an order of magnitude more time than debug binaries.

Apart from an actual release, all these optimizations might be unnecessary in a typical development cycle. If you use a task with Release in its name during the development process, consider replacing it with Debug. Similarly, instead of running assembleXCFramework, you can run assembleSharedDebugXCFramework, for example.

tip

Release binaries are built with linkRelease* Gradle tasks. You can check for them in the build log or in the Gradle build scan by running a Gradle build with the --scan option.

Don't disable the Gradle daemon without having a good reason. By default, Kotlin/Native runs from the Gradle daemon. When it's enabled, the same JVM process is used, and there is no need to warm it up for each compilation.

Using transitiveExport = true disables dead code elimination in many cases, so the compiler has to process a lot of unused code. It increases the compilation time. Instead, use the export method explicitly for exporting the required projects and dependencies.

Try to avoid unnecessary module export. Each exported module negatively affects compilation time and binary size.

Enable the Gradle build cache feature:

• Local build cache. For local caching, add org.gradle.caching=true to your gradle.properties file or run the build with the --build-cache option in the command line.

• Remote build cache. Learn how to configure the remote build cache for continuous integration environments.

To use the Gradle configuration cache, add org.gradle.configuration-cache=true to your gradle.properties file.

note

Configuration cache also enables running link* tasks in parallel which could heavily load the machine, specifically with a lot of CPU cores. This issue will be fixed in KT-70915.

There are Kotlin/Native properties that disable the Gradle daemon and compiler caches:

• kotlin.native.disableCompilerDaemon=true

• kotlin.native.cacheKind=none

• kotlin.native.cacheKind.$target=none, where $target is a Kotlin/Native compilation target, for example iosSimulatorArm64.

If you had issues with these features before and added these lines to your gradle.properties file or Gradle arguments, remove them and check whether the build completes successfully. It is possible that these properties were added previously to work around issues that have already been fixed.

With incremental compilation, if only a part of the klib artifact produced by the project module changes, just a part of klib is further recompiled into a binary.

This feature is Experimental. To enable it, add the kotlin.incremental.native=true option to your gradle.properties file. If you face any problems, create an issue in YouTrack.