Kotlin Tooling Native Build Performance Agent Skill

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/project

It is read-only and prints file:line findings (disabled caches, broad

local tasks, transitiveExport, broad KSP configuration, missing CI

.konan cache), 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 --scan or --profile work 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 ~/.konan warm 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, narrow

export(...), 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 iosX64 work 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=true once 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 assembleXCFramework untouched; note that explicitly in the

report.

Verify

• [ ] Re-run the exact baseline command; compare warm build against warm

build, not warm against cold.

• [ ] Second run with the configuration cache reports it is being reused.
• [ ] The local development log no longer contains linkRelease*,

*ReleaseXCFramework, or removed generator tasks.

• [ ] CI still produces every required release artifact, unchanged.
• [ ] Tests pass and the app still runs from Xcode.
• [ ] scripts/audit-native-build.sh reports no findings you have not

consciously accepted and documented.

Report Your Changes

Close with a short performance note:

• The slow scenario (local/CI, debug/release, cold/warm) and the measured

evidence — or a statement that the analysis was static.

• Each change, and why it is safe for release behavior.
• The before/after commands the user can run to confirm the win.
• Remaining tradeoffs: experimental flags enabled, targets removed under a

policy assumption, worker limits, or generated-code work deferred.

• Links to the relevant official documentation below.

Official Documentation

| Topic | Link |

|---|---|

| Improving Kotlin/Native compilation time | https://kotlinlang.org/docs/native-improving-compilation-time.html |

| Kotlin Gradle plugin compilation and caches | https://kotlinlang.org/docs/gradle-compilation-and-caches.html |

| iOS integration methods | https://kotlinlang.org/docs/multiplatform-ios-integration-overview.html |

| Direct integration with Xcode | https://kotlinlang.org/docs/multiplatform/multiplatform-direct-integration.html |

| Building final native binaries and XCFrameworks | https://kotlinlang.org/docs/multiplatform/multiplatform-build-native-binaries.html |

| Kotlin/Native binary options | https://kotlinlang.org/docs/native-binary-options.html |

| KSP with Kotlin Multiplatform | https://kotlinlang.org/docs/ksp-multiplatform.html |