Incremental Annotation Processing in KSP2

---
title: "KSP2 Incremental Processing: Get 500-Module KMP Builds Under 90 Seconds"
published: true
description: "A hands-on guide to KSP2's dirty-set propagation, Gradle convention plugin isolation, and the specific APIs that stop annotation processing from killing your build times."
tags: kotlin, android, architecture, performance
canonical_url: https://blog.nickel.is/ksp2-incremental-processing-500-module-kmp-builds-under-90s
---

## What We Will Build

By the end of this tutorial, you will have a Gradle convention plugin that wires KSP2 processors per source set with full classpath isolation, and you will understand exactly which KSP2 APIs to call — and which to avoid — to keep incremental annotation processing fast in a large KMP monorepo.

Let me show you a pattern I use in every project with more than a handful of modules. It is the difference between waiting 112 seconds and waiting 33 seconds on every incremental build.

## Prerequisites

- Kotlin 1.9+ with KSP2 enabled
- A KMP project (even a small multi-module setup works for following along)
- Gradle 8.x with configuration cache support
- Familiarity with writing a basic `SymbolProcessor`

## Step 1: Understand Where Your Time Actually Goes

Before optimizing anything, run `--scan` on your build. Here is what a typical 500-module KMP monorepo looks like:

| Build Phase | Full Build | Incremental (Naive KSP) | Incremental (Optimized KSP2) |
|---|---|---|---|
| Configuration | 8s | 8s | 3.2s (cache-hit) |
| Dependency Resolution | 12s | 4s | 4s |
| Kotlin Compilation | 45s | 9s | 9s |
| Annotation Processing (KSP) | 110s | 85s | 11s |
| Linking / Packaging | 15s | 6s | 6s |
| **Total** | **190s** | **112s** | **33.2s** |

Look at that annotation processing row. Naive KSP drops from 110s to only 85s on incremental builds. Optimized KSP2 drops to 11s. That gap is everything. Most teams obsess over Kotlin compilation speed while ignoring what is actually slow.

## Step 2: Use the Right Resolver API

Here is the gotcha that will save you hours. KSP1 called your processor with **all** symbols on every round. KSP2 gives you a dirty set — only symbols whose source files changed or whose dependencies changed. But it only works if your processor declares its inputs correctly.

kotlin
class MyProcessorProvider : SymbolProcessorProvider {
override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
return MyProcessor(environment)
}
}

class MyProcessor(private val env: SymbolProcessorEnvironment) : SymbolProcessor {
override fun process(resolver: Resolver): List {
// CORRECT: Only process new/changed files
val newFiles = resolver.getNewFiles()
val symbols = newFiles
.flatMap { it.declarations }
.filterIsInstance()
.filter { it.annotations.any { a -> a.shortName.asString() == "MyAnnotation" } }

    // Process only dirty symbols
    symbols.forEach { generateCode(it) }

    return emptyList() // No deferrals
}

}

The critical mistake: calling `resolver.getAllFiles()` instead of `resolver.getNewFiles()`. That single API choice is the difference between 11s and 85s. Every call to `getAllFiles()` tells KSP2 your processor depends on the entire source set, and incrementality dies.

## Step 3: Avoid Multi-Round Invalidation Traps

Multi-round processing introduces another invalidation vector. When Round 1 generates code that Round 2's processor depends on, KSP2 tracks cross-round dependencies. If your Round 1 output changes, Round 2 re-runs — but **only** for the affected outputs.

The pattern that breaks this: generating files with content derived from aggregated state across all symbols. That creates an implicit dependency on every source file. Split into per-file generators instead.

## Step 4: Wire Classpath Isolation With a Convention Plugin

In a 500-module KMP monorepo, KSP processors often conflict at the classpath level. Module A uses your custom processor v2, Module B still needs v1. Without isolation, Gradle merges these onto a single classpath and you get mysterious symbol resolution failures.

Here is the minimal setup to get this working:

kotlin
// build-logic/convention/src/main/kotlin/kmp-ksp-convention.gradle.kts
plugins {
id("com.google.devtools.ksp")
}

kotlin {
sourceSets {
commonMain {
dependencies {
// Scoped to commonMain only
}
}
}
}

dependencies {
// Per-target processor wiring
add("kspAndroid", project(":processors:android-specific"))
add("kspIosArm64", project(":processors:ios-specific"))
add("kspCommonMainMetadata", project(":processors:shared"))
}

ksp {
arg("ksp.incremental", "true")
arg("ksp.incremental.log", "true") // You'll want this for debugging
}

This keeps each processor's classpath isolated per source set, preventing conflicts where `com.example.Generated` from one processor shadows another.

KSP2 supports Gradle configuration cache, but only if your `SymbolProcessorProvider` captures no Project references. Store configuration in KSP arguments (`environment.options`), never in captured lambdas. The docs do not mention this, but this alone cut the configuration phase from 8s to 3.2s on cache-hit builds across 500 modules.

## Gotchas

| Anti-pattern | Time Cost Per Build | Fix |
|---|---|---|
| `getAllFiles()` in processor | +60–80s | Switch to `getNewFiles()` |
| Aggregating processors | +30–50s | Split into per-file generators |
| Missing classpath isolation | +15–25s | Convention plugin per source set |
| Configuration cache miss | +5–8s | Remove Project captures from providers |
| Deferred symbol re-resolution | +10–20s | Return empty list from `process()` when possible |

The biggest one: **audit every `getAllFiles()` call first.** Replace them with `getNewFiles()` in every processor. This single change typically delivers 60–80% of incremental build time savings in KSP-heavy projects.

Also, enable `ksp.incremental.log` and actually read it. The log tells you exactly which files triggered reprocessing and why. Without it, you are optimizing blind. Run `--scan` alongside it to correlate KSP rounds with actual wall-clock time.

On a related note, long build cycles mean long stretches at your desk. I keep [HealthyDesk](https://play.google.com/store/apps/details?id=com.healthydesk) running during builds to remind me to stretch — those 90-second compile windows are perfect for a quick guided exercise.

## Conclusion

Getting 500-module KMP projects under 90 seconds is not magic. It is disciplined use of KSP2's incremental APIs, strict classpath boundaries, and convention plugins that enforce both. Start with the build scan, follow the data, and fix the processors that lie about their inputs. The payoff is immediate and compounding — every developer on your team gets those minutes back on every single build.