kotlin-tooling-native-build-performance
Diagnoses and fixes slow Kotlin/Native compilation and linking in Kotlin Multiplatform projects that target iOS. Use when the user reports slow iOS or shared-framework builds, long linkDebug*/linkRelease* or XCFramework tasks, cold CI builds that re-download the Kotlin/Native toolchain, KSP or other generated code on the native path, transitiveExport usage, or asks for a local-development versus CI build performance plan.
Kotlin · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-native-build-performance技能说明
name: kotlin-tooling-native-build-performance description: > Diagnoses and fixes slow Kotlin/Native compilation and linking in Kotlin Multiplatform projects that target iOS. Use when the user reports slow iOS or shared-framework builds, long linkDebug*/linkRelease* or XCFramework tasks, cold CI builds that re-download the Kotlin/Native toolchain, KSP or other generated code on the native path, transitiveExport usage, or asks for a local-development versus CI build performance plan. license: Apache-2.0 metadata: author: JetBrains version: "1.0.0" tested_models: "openai/gpt-5.5, openai/gpt-5.4-mini" last_eval: "2026-07-06"
Kotlin/Native Build Performance
Turn "the iOS build is slow" into a measured diagnosis and a small set of safe fixes. Two rules apply throughout:
- Never trade away required release behavior. A faster local loop must not change what CI publishes.
- Measure before and after with the same command and the same build state. An unmeasured fix is a guess.
Step 0: Classify the Slow Scenario
Establish four facts before editing anything: where (local or CI), what (debug feedback loop or release/distribution artifact), state (first build, clean, warm, or no-op), and phase (which tasks dominate the log). Then match the dominant symptom:
| Symptom in the build log | Likely cause | Read |
|---|---|---|
linkRelease* or *ReleaseXCFramework tasks in a local development loop | Building distribution artifacts for development | artifacts-and-targets |
| Kotlin/Native compiler distribution downloaded on every CI run | ~/.konan not preserved between runs | caching-and-gradle |
| Long pause before the first task starts | Configuration phase, no configuration cache | caching-and-gradle |
| All iOS targets build when only one simulator is needed | Broad task (build, assemble, assemble*XCFramework) or unused targets | artifacts-and-targets |
ksp* tasks ahead of compileKotlinIos* | Generated-code work on the native path | exports-and-generated-code |
| Small source edit recompiles and relinks everything | Compiler caches disabled, or missing incrementality | caching-and-gradle, experimental |
Machine overloaded while several link* tasks run at once | Parallel native linking | caching-and-gradle, worker-limit caveat |
Step 1: Audit and Measure
-
Run the static audit from the project root:
scripts/audit-native-build.sh /path/to/projectIt is read-only and prints
file:linefindings (disabled caches, broad local tasks,transitiveExport, broad KSP configuration, missing CI.konancache), each pointing at the reference file with the fix. Findings are leads, not verdicts — confirm each against project policy. -
Find the command the user actually waits for: a script, a CI step, or the Gradle invocation inside an Xcode build phase. Optimize that command, not a task you picked yourself.
-
Run it twice when practical. The first build downloads Kotlin/Native components and fills caches; only the second and later runs are representative. Attribute time per task before blaming the compiler:
kotlin.build.report.output=file # writes build/reports/kotlin-build/Gradle's
--scanor--profilework too. -
If you cannot run the build (no macOS host, no Xcode), analyze logs, build scans, or checked-in metrics instead — and state explicitly that the conclusion is static.
Step 2: Fix in Safe Order
Apply fixes one at a time, re-measuring as you go:
- Restore healthy defaults — remove cache/daemon workarounds, enable
Gradle build and configuration caches, keep
~/.konanwarm in CI, update Kotlin: references/caching-and-gradle.md - Build only what the feedback loop needs — one specific task per loop, correct integration method, justified target matrix: references/artifacts-and-targets.md
- Cut export and generated-code cost — drop
transitiveExport, narrowexport(...), scope KSP work to the native compilations that need it: references/exports-and-generated-code.md - Experimental switches last, with the user's agreement: references/experimental.md
Worked Example
A developer on an Apple Silicon Mac complains that "every shared-module
change costs 12 minutes". Their loop runs ./gradlew :shared:assembleXCFramework.
A build scan of the second (warm) run shows:
:shared:linkReleaseFrameworkIosArm64 348s
:shared:linkReleaseFrameworkIosX64 341s
:shared:compileKotlinIosX64 96s
:shared:linkDebugFrameworkIosSimulatorArm64 41s
:shared:compileKotlinIosSimulatorArm64 38s
configuration phase 64s
Reasoning chain:
- The loop is local + debug + warm, but ~690s goes to
linkRelease*— release linking is an order of magnitude slower than debug and only CI needs it. Replace the local command with:shared:linkDebugFrameworkIosSimulatorArm64(or the Xcode embed task if Xcode drives the build). (artifacts-and-targets) - All
iosX64work serves Intel simulators; ask whether the team still supports them before removing the target. (artifacts-and-targets) - 64s of configuration on every run disappears behind
org.gradle.configuration-cache=trueonce trialed. (caching-and-gradle) - Expected loop after the change: ~40s compile + ~40s link on warm builds — confirm by re-running the new command twice and comparing.
- CI keeps `assembleXCFra