Annotation Processing

kapt is a Kotlin plugin that lets old Java annotation-processing tools (like Dagger or Room) work on Kotlin code. It does this by first turning Kotlin into simple Java placeholder files those tools can read.

kapt first turns your Kotlin into fake Java code so old Java tools can read it, which is slow. KSP reads your Kotlin code directly, skipping that extra step, so the build is faster.

KSP is Kotlin's tool for reading code at compile time and generating new source files. You write a SymbolProcessor that does the work, and a SymbolProcessorProvider that creates it.

Apply the kotlin-kapt plugin, then add the processor with the kapt(...) line instead of implementation(...). If the processor needs options, pass them in a kapt { arguments { arg(...) } } block.

Call resolver.getSymbolsWithAnnotation("com.example.MyAnnotation") to get a sequence of annotated symbols, then filter to the kind you want, for example keeping only KSClassDeclaration or KSFunctionDeclaration.

Call codeGenerator.createNewFile(...) to get an output stream and write Kotlin code into it. The Dependencies argument tells KSP which input files the generated file came from, so incremental builds know when to regenerate it.

Recent Dagger/Hilt versions support KSP, so they can move the compilers from kapt(...) to ksp(...). Hilt also needs its own Gradle plugin applied, regardless of kapt or KSP.

For compile-time adapters you add Moshi plus its codegen artifact on the ksp(...) configuration and mark classes @JsonClass(generateAdapter = true). The reflection approach instead adds moshi-kotlin and needs no processor at all.

Before processing, kapt makes kotlinc produce extra Java placeholder files for your whole codebase. Generating those files runs an additional, expensive compilation pass, which makes builds noticeably slower.

First check that each library you use offers a KSP version of its processor. If it does, swap the Gradle plugin and change kapt(...) to ksp(...) for that library. If a library only has a kapt processor, you must keep kapt for it.

kapt needs a Java compiler, which only exists on the JVM, so it can't run for iOS or JavaScript targets. KSP is a pure Kotlin compiler plugin, so it runs on every Kotlin platform.

Room and Moshi codegen have supported KSP for a while; Dagger/Hilt were kapt-only for years but modern versions added KSP. Today you wire all three via ksp(...) and only fall back to kapt for processors that still lack KSP.

correctErrorTypes tells kapt to recover the real types of code that is itself still being generated. Without it, those types show up as a meaningless 'error' placeholder and processors break. It is off by default.

Older Kotlin annotation processing first turned Kotlin into fake Java classes (stubs) so Java tools could read them. KSP skips that and reads Kotlin directly through its own model, so it's faster and sees real Kotlin features.

Some generated code creates new things other processors must then look at. So processing runs in repeated rounds until nothing new appears. In KSP, a processor returns the symbols it couldn't fully handle yet, and they're retried in the next round.

KSP runs process() several times (rounds). If a symbol can't be handled yet because the types it needs don't exist yet, you return it so KSP tries again next round, after more code has been generated.

You must keep kapt when a library only provides an old Java-style annotation processor and no KSP version. kapt works with those because it runs the standard Java processing pipeline; KSP can't run them.

You pass processor options through the ksp { arg(...) } block in the module (for example Room's schema directory), and you keep versions aligned by centralizing them in a version catalog or a shared convention plugin so every module uses the same KSP and processor versions.

Check which of your annotation processors have a faster KSP version. Migrate those module-by-module, keep kapt only for the few processors that have no KSP option, and measure build-time improvement before and after.