kapt

Active contributors: Alexander Udalov, Dmitriy Novozhilov, Ilmir Usmanov

plugins/kapt/ is the Kotlin Annotation Processing Tool: a compiler plugin that lets Java annotation processors (Dagger, Hilt, Glide, AutoValue, Room, ...) work on Kotlin sources. It does this by emitting Java "stub" files that mimic the Kotlin classes, then handing those stubs to a regular Java annotation processor.

Purpose

Bridge the gap between Kotlin and the Java annotation-processor ecosystem. Many widely used Java libraries rely on javax.annotation.processing.Processor to generate code at compile time; without kapt, that whole ecosystem would be inaccessible from Kotlin.

Directory layout

plugins/kapt/
├── kapt-cli/                   CLI layer
├── kapt-base/                  Shared base classes
├── kapt-compiler/              The compiler plugin (K1 path)
├── kapt-runtime/               Tiny runtime jar
├── kapt-stubs-generator/       Java stub generator
├── kapt-tests/                 Tests
└── ChangeLog.md

How it works

graph LR
    Kotlin[".kt sources"] --> Compile1["Kotlin frontend (resolve only)"]
    Compile1 --> Stubs["Java stub generator"]
    Stubs -->|.java stubs| Javac["javac + annotation processors"]
    Javac --> Generated["Generated .java files"]
    Generated --> Compile2["Kotlin compile (full)"]
    Kotlin --> Compile2
    Compile2 --> Cls["class files"]

1. The Kotlin compiler runs the frontend only to learn enough about each Kotlin class to emit a Java stub.
2. The stubs generator (kapt-stubs-generator/) writes Java source files that look like the Kotlin classes — same names, same signatures (with type erasure baked in). Bodies are intentionally minimal.
3. javac runs over the stubs with the configured annotation processors. Processors generate Java sources as usual.
4. The Kotlin compiler runs again over the original Kotlin sources plus the generated Java sources, producing the final class files.

kapt vs. KSP

kapt is a Java-stub-based tool. KSP (Kotlin Symbol Processing) is a Kotlin-native alternative that lives in a separate repository (google/ksp). KSP is faster (no stub generation) and Kotlin-aware (sees Kotlin types directly), but kapt is still the only path for the long tail of processors that have not migrated to KSP.

KGP integration

libraries/tools/kotlin-gradle-plugin/.../kapt/ exposes kapt to Gradle:

plugins {
    kotlin("kapt")
}
dependencies {
    kapt("com.google.dagger:dagger-compiler:...")
}

kapt 4 / FIR-based

The plugin has been working toward a FIR-driven implementation (sometimes called kapt 4) to share the K2 frontend's improved performance. The K1 code in kapt-compiler/ remains the production path; FIR-based work runs alongside.

Tests

plugins/kapt/kapt-tests/ runs annotation processors over Kotlin sources and verifies generated output matches expectations.

Integration points

• Consumed by: any Kotlin project that uses Java annotation processors.
• Backed by: the in-tree Kotlin compiler plus a javac invocation.
• Co-traveler: KGP kotlin("kapt"), libraries/kotlin-maven-allopen/ etc. for non-kapt plugins (kapt has its own Maven hookup).

Where to start

For a stub-shape bug: plugins/kapt/kapt-stubs-generator/. For overall flow control: plugins/kapt/kapt-compiler/. For configuration handed in by users: plugins/kapt/kapt-cli/.

See plugins/index.md for the broader plugin landscape.