From 9f571359fbf78851d412e67ffaedba864e296a23 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Wed, 27 Nov 2024 15:03:14 +0100 Subject: [PATCH 01/15] update: replace `packForXcode` in native-improving-compilation-time.md This task is obsolete and superseded with `embedAndSignAppleFrameworkForXcode`. --- .../native/native-improving-compilation-time.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index a1e3aacc956..d8ba047acdc 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -43,18 +43,11 @@ Here are some recommendations for configuring Gradle for better compilation perf * `linkDebug*`: To run your code during development, you usually need only one binary, so running the corresponding `linkDebug*` task should be enough. Keep in mind that compiling a release binary (`linkRelease*`) takes more time than compiling a debug one. - * `packForXcode`: Since iOS simulators and devices have different processor architectures, it's a common approach to + * `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. During local development, it will be faster to build the `.framework` for only the platform you're using. - To build a platform-specific framework, call the `packForXcode` task generated - by the [Kotlin Multiplatform project wizard](https://kmp.jetbrains.com/). - - > Remember that in this case, you will need to clean the build using `./gradlew clean` after switching between the - > device and the simulator. See [this issue](https://youtrack.jetbrains.com/issue/KT-40907) for details. - > - {style="note"} - + To build a platform-specific framework, call the `embedAndSignAppleFrameworkForXcode` task. * **Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html)** without having a good reason to. [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native) From e38dea5c2329ad312567f9ef4283fbc66899cf8a Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Wed, 27 Nov 2024 15:04:47 +0100 Subject: [PATCH 02/15] update: use a single target in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index d8ba047acdc..30f9e93454d 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -49,6 +49,13 @@ Here are some recommendations for configuring Gradle for better compilation perf To build a platform-specific framework, call the `embedAndSignAppleFrameworkForXcode` task. +* **Build only for the target you need**. Similarly to the recommendation above, don't build a binary for all Native + platforms at once. For example, compiling an [XCFramework](multiplatform-build-native-binaries.md#build-xcframeworks) + (e.g., with 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. + * **Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html)** without having a good reason to. [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native) by default. When it's enabled, the same JVM process is used and there is no need to warm it up for each compilation. From 19d202b6c5b1ed598c644856207fa2e9e77e3c21 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Wed, 27 Nov 2024 15:18:00 +0100 Subject: [PATCH 03/15] update: clarify release build in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index 30f9e93454d..9e6a4e3e0d8 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -41,8 +41,7 @@ Here are some recommendations for configuring Gradle for better compilation perf 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. Keep in mind that compiling a release binary (`linkRelease*`) takes more time - than compiling a debug one. + `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. During local development, it will be faster to build the `.framework` for only the platform you're using. @@ -56,6 +55,12 @@ Here are some recommendations for configuring Gradle for better compilation perf * 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. +* **Don't build release binaries unless necessary**. Kotlin/Native supports + [two build modes – debug and release](https://kotlinlang.org/docs/multiplatform-build-native-binaries.html#declare-binaries). + 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. In a typical development cycle, all the optimizations might be unnecessary. So, if + your development cycle uses a task with "Release" in its name, consider replacing it with "Debug". + * **Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html)** without having a good reason to. [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native) by default. When it's enabled, the same JVM process is used and there is no need to warm it up for each compilation. From 74f1a5f2d88c883ed24ef3716514dcdb144c2007 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Wed, 27 Nov 2024 15:08:03 +0100 Subject: [PATCH 04/15] update: clarify export in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index 9e6a4e3e0d8..64b918e900b 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -69,6 +69,9 @@ Here are some recommendations for configuring Gradle for better compilation perf Using transitive export disables dead code elimination in many cases: the compiler has to process a lot of unused code. It increases the compilation time. Use `export` explicitly for exporting the required projects and dependencies. +* **Don't use [export](multiplatform-build-native-binaries.md#export-dependencies-to-binaries) too much**. Any exported + module negatively affects compilation time and binary size. + * **Use the Gradle [build caches](https://docs.gradle.org/current/userguide/build_cache.html)**: * **Local build cache**: Add `org.gradle.caching=true` to your `gradle.properties` or run with `--build-cache` on the command line. * **Remote build cache** in continuous integration environments. Learn how to [configure the remote build cache](https://docs.gradle.org/current/userguide/build_cache.html#sec:build_cache_configure_remote). From 1c872ebf100495de96d89dc1a2e3e0a2346d76bc Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Wed, 27 Nov 2024 15:04:24 +0100 Subject: [PATCH 05/15] update: mention Gradle CC in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index 64b918e900b..abf8d9fc438 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -76,6 +76,14 @@ Here are some recommendations for configuring Gradle for better compilation perf * **Local build cache**: Add `org.gradle.caching=true` to your `gradle.properties` or run with `--build-cache` on the command line. * **Remote build cache** in continuous integration environments. Learn how to [configure the remote build cache](https://docs.gradle.org/current/userguide/build_cache.html#sec:build_cache_configure_remote). +* **Use the Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html)**: + Add `org.gradle.configuration-cache=true` to your `gradle.properties`. + > Configuration cache also enables running `link*` tasks in parallel which could heavily load the machine, + > specifically with a lot of CPU cores. + > To be fixed with [KT-70915](https://youtrack.jetbrains.com/issue/KT-70915/Limit-parallelism-on-KotlinNativeLink-tasks). + > + {style="note"} + * **Enable previously disabled features of Kotlin/Native**. There are properties that disable the Gradle daemon and compiler caches – `kotlin.native.disableCompilerDaemon=true` and `kotlin.native.cacheKind=none`. If you had issues with these features before and added these lines to your `gradle.properties` or Gradle arguments, remove them and check whether From 598710942d49933c67a2c66dc8f619dd38049a78 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Wed, 27 Nov 2024 15:10:56 +0100 Subject: [PATCH 06/15] update: add cache flag names in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index abf8d9fc438..b1de640f7b2 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -85,7 +85,8 @@ Here are some recommendations for configuring Gradle for better compilation perf {style="note"} * **Enable previously disabled features of Kotlin/Native**. There are properties that disable the Gradle daemon and compiler - caches – `kotlin.native.disableCompilerDaemon=true` and `kotlin.native.cacheKind=none`. If you had issues with these + caches – `kotlin.native.disableCompilerDaemon=true`, `kotlin.native.cacheKind=none` and `kotlin.native.cacheKind.$target=none` + (where `$target` is a Kotlin/Native compilation target, e.g. `iosSimulatorArm64`). If you had issues with these features before and added these lines to your `gradle.properties` 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. From fb613e0f1597f34d05701af65ec7de08ea7afaec Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Thu, 28 Nov 2024 10:07:17 +0100 Subject: [PATCH 07/15] update: correct info on dSYM in multiplatform-build-native-binaries.md dSYMs are generated for release frameworks as well as for debug ones. --- .../topics/multiplatform/multiplatform-build-native-binaries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/multiplatform/multiplatform-build-native-binaries.md b/docs/topics/multiplatform/multiplatform-build-native-binaries.md index 4a83970f9e4..2cedd4ca852 100644 --- a/docs/topics/multiplatform/multiplatform-build-native-binaries.md +++ b/docs/topics/multiplatform/multiplatform-build-native-binaries.md @@ -459,7 +459,7 @@ kotlin { When you declare XCFrameworks, the Kotlin Gradle plugin will register several Gradle tasks: * `assembleXCFramework` -* `assembleDebugXCFramework` (additionally debug artifact that contains [dSYMs](native-ios-symbolication.md)) +* `assembleDebugXCFramework` * `assembleReleaseXCFramework` From c708eb2f20894efd77125ed5fcddd13d082e4ec8 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Thu, 28 Nov 2024 10:23:15 +0100 Subject: [PATCH 08/15] fixup! update: use a single target in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index b1de640f7b2..153e2ac0a87 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -54,6 +54,12 @@ Here are some recommendations for configuring Gradle for better compilation perf 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. + > 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 a + > [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) + > by running Gradle with `--scan` flag. + > + {style="tip"} * **Don't build release binaries unless necessary**. Kotlin/Native supports [two build modes – debug and release](https://kotlinlang.org/docs/multiplatform-build-native-binaries.html#declare-binaries). From e30c723663942811267d9bd8a72a4a3283031af9 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Thu, 28 Nov 2024 10:23:41 +0100 Subject: [PATCH 09/15] fixup! update: clarify release build in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index 153e2ac0a87..f6b8d6a2723 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -65,7 +65,13 @@ Here are some recommendations for configuring Gradle for better compilation perf [two build modes – debug and release](https://kotlinlang.org/docs/multiplatform-build-native-binaries.html#declare-binaries). 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. In a typical development cycle, all the optimizations might be unnecessary. So, if - your development cycle uses a task with "Release" in its name, consider replacing it with "Debug". + your development cycle uses a task with "Release" in its name, consider replacing it with "Debug". Similarly, instead + of running `assembleXCFramework`, you can run `assembleXcfDebugXCFramework`, for example. + > Release binaries are built with `linkRelease*` Gradle tasks. You can check for their presence in the build log, + > or using a [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) by running Gradle + > with `--scan` flag. + > + {style="tip"} * **Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html)** without having a good reason to. [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native) From 5e9de4b55cac5821d90fac6fcdb53542d30fb852 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Thu, 28 Nov 2024 11:31:24 +0100 Subject: [PATCH 10/15] fixup! update: replace `packForXcode` in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index f6b8d6a2723..f604e83bc6c 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -46,7 +46,8 @@ Here are some recommendations for configuring Gradle for better compilation perf distribute a Kotlin/Native binary as a universal (fat) framework. During local development, it will be faster to build the `.framework` for only the platform you're using. - To build a platform-specific framework, call the `embedAndSignAppleFrameworkForXcode` task. + To build a platform-specific framework, call the + [embedAndSignAppleFrameworkForXcode](multiplatform-direct-integration.md#connect-the-framework-to-your-project) task. * **Build only for the target you need**. Similarly to the recommendation above, don't build a binary for all Native platforms at once. For example, compiling an [XCFramework](multiplatform-build-native-binaries.md#build-xcframeworks) From 7f2ad54908807b3f98e6deebcdffdcb7bbf0cff9 Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Thu, 28 Nov 2024 11:32:13 +0100 Subject: [PATCH 11/15] fixup! update: clarify release build in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index f604e83bc6c..ab5593d66a8 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -67,7 +67,7 @@ Here are some recommendations for configuring Gradle for better compilation perf 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. In a typical development cycle, all the optimizations might be unnecessary. So, if your development cycle uses a task with "Release" in its name, consider replacing it with "Debug". Similarly, instead - of running `assembleXCFramework`, you can run `assembleXcfDebugXCFramework`, for example. + of running `assembleXCFramework`, you can run `assembleSharedDebugXCFramework`, for example. > Release binaries are built with `linkRelease*` Gradle tasks. You can check for their presence in the build log, > or using a [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) by running Gradle > with `--scan` flag. From dc251d542a8d632d00d486fafa976abac2f4d84e Mon Sep 17 00:00:00 2001 From: Svyatoslav Scherbina Date: Thu, 28 Nov 2024 13:06:06 +0100 Subject: [PATCH 12/15] fixup! update: clarify release build in native-improving-compilation-time.md --- docs/topics/native/native-improving-compilation-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index ab5593d66a8..0babc92afeb 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -63,7 +63,7 @@ Here are some recommendations for configuring Gradle for better compilation perf {style="tip"} * **Don't build release binaries unless necessary**. Kotlin/Native supports - [two build modes – debug and release](https://kotlinlang.org/docs/multiplatform-build-native-binaries.html#declare-binaries). + [two build modes – debug and release](multiplatform-build-native-binaries.md#declare-binaries). 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. In a typical development cycle, all the optimizations might be unnecessary. So, if your development cycle uses a task with "Release" in its name, consider replacing it with "Debug". Similarly, instead From 537257a636899bc264c13de51d3767c9f067f574 Mon Sep 17 00:00:00 2001 From: "Danil.Pavlov" Date: Thu, 28 Nov 2024 16:16:55 +0100 Subject: [PATCH 13/15] update: new structure --- .../native-improving-compilation-time.md | 240 ++++++++++-------- 1 file changed, 141 insertions(+), 99 deletions(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index 0babc92afeb..ab2b6d9e73b 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -1,4 +1,6 @@ -[//]: # (title: Tips for improving Kotlin/Native compilation times) +[//]: # (title: Tips for improving compilation time) + + The Kotlin/Native compiler is constantly receiving updates that improve its performance. With the latest Kotlin/Native compiler and a properly configured build environment, you can significantly improve the compilation times of your projects @@ -8,18 +10,26 @@ Read on for our tips on how to speed up the Kotlin/Native compilation process. ## General recommendations -* **Use the most recent version of Kotlin**. This way you will always have the latest performance improvements. -* **Avoid creating huge classes**. They take a long time to compile and load during execution. -* **Preserve downloaded and cached components between builds**. 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. +### Use the latest version of Kotlin + +This way, you always get the latest performance improvements. The most recent Kotlin version is %kotlinVersion%. + +### Avoid creating huge classes + +Try to avoid huge classes that take a long time to compile and load during execution. + +### Preserve downloaded and cached components between builds + +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. +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. +Alternatively, you can use the `-Xkonan-data-dir` compiler option to configure your custom path to the directory via +the `cinterop` and `konanc` tools. ## Gradle configuration @@ -27,91 +37,123 @@ The first compilation with Gradle usually takes more time than subsequent ones d build caches, and perform additional steps. You should build your project at least twice to get an accurate reading of the actual compilation times. -Here are some recommendations for configuring Gradle for better compilation performance: - -* **Increase the [Gradle heap size](https://docs.gradle.org/current/userguide/performance.html#adjust_the_daemons_heap_size)**. - Add `org.gradle.jvmargs=-Xmx3g` to `gradle.properties`. If you use [parallel builds](https://docs.gradle.org/current/userguide/performance.html#parallel_execution), - 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. - -* **Build only the binaries you need**. 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. During local development, it will be faster to build - the `.framework` for only the platform you're using. - - To build a platform-specific framework, call the - [embedAndSignAppleFrameworkForXcode](multiplatform-direct-integration.md#connect-the-framework-to-your-project) task. - -* **Build only for the target you need**. Similarly to the recommendation above, don't build a binary for all Native - platforms at once. For example, compiling an [XCFramework](multiplatform-build-native-binaries.md#build-xcframeworks) - (e.g., with 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. - > 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 a - > [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) - > by running Gradle with `--scan` flag. - > - {style="tip"} - -* **Don't build release binaries unless necessary**. Kotlin/Native supports - [two build modes – debug and release](multiplatform-build-native-binaries.md#declare-binaries). - 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. In a typical development cycle, all the optimizations might be unnecessary. So, if - your development cycle uses a task with "Release" in its name, consider replacing it with "Debug". Similarly, instead - of running `assembleXCFramework`, you can run `assembleSharedDebugXCFramework`, for example. - > Release binaries are built with `linkRelease*` Gradle tasks. You can check for their presence in the build log, - > or using a [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) by running Gradle - > with `--scan` flag. - > - {style="tip"} - -* **Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html)** without having a - good reason to. [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native) - by default. When it's enabled, the same JVM process is used and there is no need to warm it up for each compilation. - -* **Don't use [transitiveExport = true](multiplatform-build-native-binaries.md#export-dependencies-to-binaries)**. - Using transitive export disables dead code elimination in many cases: the compiler has to process a lot of unused code. It increases the compilation time. - Use `export` explicitly for exporting the required projects and dependencies. - -* **Don't use [export](multiplatform-build-native-binaries.md#export-dependencies-to-binaries) too much**. Any exported - module negatively affects compilation time and binary size. - -* **Use the Gradle [build caches](https://docs.gradle.org/current/userguide/build_cache.html)**: - * **Local build cache**: Add `org.gradle.caching=true` to your `gradle.properties` or run with `--build-cache` on the command line. - * **Remote build cache** in continuous integration environments. Learn how to [configure the remote build cache](https://docs.gradle.org/current/userguide/build_cache.html#sec:build_cache_configure_remote). - -* **Use the Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html)**: - Add `org.gradle.configuration-cache=true` to your `gradle.properties`. - > Configuration cache also enables running `link*` tasks in parallel which could heavily load the machine, - > specifically with a lot of CPU cores. - > To be fixed with [KT-70915](https://youtrack.jetbrains.com/issue/KT-70915/Limit-parallelism-on-KotlinNativeLink-tasks). - > - {style="note"} - -* **Enable previously disabled features of Kotlin/Native**. There are properties that disable the Gradle daemon and compiler - caches – `kotlin.native.disableCompilerDaemon=true`, `kotlin.native.cacheKind=none` and `kotlin.native.cacheKind.$target=none` - (where `$target` is a Kotlin/Native compilation target, e.g. `iosSimulatorArm64`). If you had issues with these - features before and added these lines to your `gradle.properties` 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. - -* **Try incremental compilation of klib artifacts**. 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](components-stability.md#stability-levels-explained). 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](https://kotl.in/issue). - -## Windows OS configuration - -* **Configure Windows Security**. Windows Security may slow down the Kotlin/Native compiler. You can avoid this by adding the `.konan` directory, which is located in `%\USERPROFILE%` by default, to Windows Security exclusions. Learn how to [add exclusions to Windows Security](https://support.microsoft.com/en-us/windows/add-an-exclusion-to-windows-security-811816c0-4dfd-af4a-47e4-c301afe13b26). \ No newline at end of file +Below are some recommendations for configuring Gradle for better compilation performance. + +### Increase Gradle heap size + +To increase the [Gradle heap size](https://docs.gradle.org/current/userguide/performance.html#adjust_the_daemons_heap_size), +add `org.gradle.jvmargs=-Xmx3g` to your `gradle.properties` file. + +If you use [parallel builds](https://docs.gradle.org/current/userguide/performance.html#parallel_execution), +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. + +### Build only necessary binaries + +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](multiplatform-direct-integration.md#connect-the-framework-to-your-project) task. + +### Build only for necessary targets + +Similarly to the recommendation above, don't build a binary for all native +platforms at once. For example, compiling an [XCFramework](multiplatform-build-native-binaries.md#build-xcframeworks) +(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. + +> 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](https://docs.gradle.org/current/userguide/build_scans.html) +> by running a Gradle build with the `--scan` option. +> +{style="tip"} + +### Don't build release binaries + +Kotlin/Native supports two build modes, [debug and release](multiplatform-build-native-binaries.md#declare-binaries). +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. + +In a typical development cycle, all these optimizations might be unnecessary. If your development cycle uses a task with +`Release` in its name, consider replacing it with `Debug`. Similarly, instead +of running `assembleXCFramework`, you can run `assembleSharedDebugXCFramework`, for example. + +> Release binaries are built with `linkRelease*` Gradle tasks. You can check for them in the build log +> or in the [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) by running a Gradle build +> with the `--scan` option. +> +{style="tip"} + +### Don't disable Gradle daemon + +Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html) without having a good reason. By default, [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native). +When it's enabled, the same JVM process is used and there is no need to warm it up for each compilation. + +### Don't use transitive export + +Using [`transitiveExport = true`](multiplatform-build-native-binaries.md#export-dependencies-to-binaries) 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. + +### Don't export modules too much + +Try to avoid unnecessary [module export](multiplatform-build-native-binaries.md#export-dependencies-to-binaries). +Each exported module negatively affects compilation time and binary size. + +### Use Gradle build caching + +Enable the Gradle [build cache](https://docs.gradle.org/current/userguide/build_cache.html) 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](https://docs.gradle.org/current/userguide/build_cache.html#sec:build_cache_configure_remote) + for continuous integration environments. + +### Use Gradle configuration cache + +To use the Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html), +add `org.gradle.configuration-cache=true` to your `gradle.properties` file. + +> 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](https://youtrack.jetbrains.com/issue/KT-70915). +> +{style="note"} + +### Enable previously disabled features + +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. + +### Try incremental compilation of klib artifacts + +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](components-stability.md#stability-levels-explained). 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](https://kotl.in/issue). + +## Windows configuration + +Windows Security may slow down the Kotlin/Native compiler. You can avoid this by adding the `.konan` directory, +which is located in `%\USERPROFILE%` by default, to Windows Security exclusions. Learn how to [add exclusions to Windows Security](https://support.microsoft.com/en-us/windows/add-an-exclusion-to-windows-security-811816c0-4dfd-af4a-47e4-c301afe13b26). \ No newline at end of file From aafb487f77b666c9c97468d0c3c8880af9b31ec8 Mon Sep 17 00:00:00 2001 From: "Danil.Pavlov" Date: Mon, 2 Dec 2024 14:00:43 +0100 Subject: [PATCH 14/15] update: review suggestions --- .../topics/native/native-improving-compilation-time.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/topics/native/native-improving-compilation-time.md b/docs/topics/native/native-improving-compilation-time.md index ab2b6d9e73b..7626ffceaa3 100644 --- a/docs/topics/native/native-improving-compilation-time.md +++ b/docs/topics/native/native-improving-compilation-time.md @@ -81,15 +81,15 @@ For example, you don't need `iosX64` if you don't run this project on iOS simula > {style="tip"} -### Don't build release binaries +### Don't build unnecessary release binaries Kotlin/Native supports two build modes, [debug and release](multiplatform-build-native-binaries.md#declare-binaries). 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. -In a typical development cycle, all these optimizations might be unnecessary. If your development cycle uses a task with -`Release` in its name, consider replacing it with `Debug`. Similarly, instead -of running `assembleXCFramework`, you can run `assembleSharedDebugXCFramework`, for example. +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. > Release binaries are built with `linkRelease*` Gradle tasks. You can check for them in the build log > or in the [Gradle build scan](https://docs.gradle.org/current/userguide/build_scans.html) by running a Gradle build @@ -100,7 +100,7 @@ of running `assembleXCFramework`, you can run `assembleSharedDebugXCFramework`, ### Don't disable Gradle daemon Don't disable the [Gradle daemon](https://docs.gradle.org/current/userguide/gradle_daemon.html) without having a good reason. By default, [Kotlin/Native runs from the Gradle daemon](https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/#kotlin-native). -When it's enabled, the same JVM process is used and there is no need to warm it up for each compilation. +When it's enabled, the same JVM process is used, and there is no need to warm it up for each compilation. ### Don't use transitive export From 2a241fd0cadc45f730c44f598f7545c590ba9327 Mon Sep 17 00:00:00 2001 From: "Danil.Pavlov" Date: Mon, 2 Dec 2024 14:35:56 +0100 Subject: [PATCH 15/15] chore: toc-title --- docs/kr.tree | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/kr.tree b/docs/kr.tree index f4f123d79fd..8d5795b8248 100644 --- a/docs/kr.tree +++ b/docs/kr.tree @@ -233,7 +233,7 @@ - +