KSP & Annotation Processing

Reviewed & published by Brayan K

Kotlin Symbol Processing (KSP) is the modern way to generate code at compile time from annotations — the engine behind Room, Hilt, and Moshi — replacing the slower, Java-stub-based KAPT.

Part of the free Kotlin course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

By the end you'll understand how KSP works, how it differs from KAPT, and how a SymbolProcessor generates sources.

What You'll Learn in This Lesson

• What compile-time code generation is
• KSP vs KAPT and why KSP is faster
• SymbolProcessor and SymbolProcessorProvider
• How Room, Hilt and Moshi use KSP
• The ksp(...) Gradle configuration
• Where generated sources end up

1️⃣ What Compile-Time Code Generation Is

You add an annotation; a processor reads it during compilation and writes new Kotlin source. The generated code is compiled with yours — no runtime reflection, full type safety.

// You annotate your code...
annotation class GenerateBuilder

@GenerateBuilder
data class User(val name: String, val email: String)

// ...and a KSP processor generates new source at COMPILE TIME, e.g.:
//   class UserBuilder {
//       var name: String = ""
//       var email: String = ""
//       fun build() = User(name, email)
//   }
// You never write UserBuilder by hand — KSP emits it for you.

This is exactly how Room turns a @Dao interface into a working implementation behind the scenes.

2️⃣ Wiring KSP in Gradle

Apply the KSP plugin, then register each processor with the ksp(...) configuration — the faster, Kotlin-native replacement for kapt(...).

// build.gradle.kts — apply the KSP plugin and add a processor.

plugins {
    kotlin("jvm")
    id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

dependencies {
    implementation("com.squareup.moshi:moshi:1.15.1")

    // 'ksp(...)' registers the symbol processor (here Moshi's codegen).
    ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.1")
}

KSP understands Kotlin directly instead of generating Java stubs, which is why it builds significantly faster than KAPT.

3️⃣ Inside a SymbolProcessor

A SymbolProcessorProvider is the entry point that creates your SymbolProcessor. Its process() method uses a Resolver to find annotated symbols and a CodeGenerator to emit files.

import com.google.devtools.ksp.processing.*
import com.google.devtools.ksp.symbol.KSAnnotated

// 1) The PROVIDER is the entry point KSP discovers; it builds your processor.
class BuilderProcessorProvider : SymbolProcessorProvider {
    override fun create(env: SymbolProcessorEnvironment): SymbolProcessor =
        BuilderProcessor(env.codeGenerator, env.logger)
}

// 2) The PROCESSOR inspects symbols and generates code.
class BuilderProcessor(
    private val codeGenerator: CodeGenerator,
    private val logger: KSPLogger,
) : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        // Find everything annotated with @GenerateBuilder...
        val symbols = resolver
            .getSymbolsWithAnnotation("com.example.GenerateBuilder")
        // ...then use codeGenerator to write new .kt files. (omitted)
        return emptyList()
    }
}

Your turn. Replace the TODOs, then compare.

// 🎯 YOUR TURN — replace each TODO in build.gradle.kts.

plugins {
    kotlin("jvm")
    // 1) Apply the KSP Gradle plugin.
    TODO                                  // 👉 id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

dependencies {
    implementation("androidx.room:room-runtime:2.6.1")
    // 2) Register Room's annotation processor via KSP.
    TODO("androidx.room:room-compiler:2.6.1")   // 👉 ksp(...)
}

Mini-Challenge: Sketch a Processor

Write a provider and processor that finds annotated symbols and logs how many it found.

// 🎯 MINI-CHALLENGE: sketch a SymbolProcessor.
//
// 1. Write a SymbolProcessorProvider whose create() returns
//    your processor, passing env.codeGenerator and env.logger.
// 2. Write the SymbolProcessor. In process(resolver):
//    - call resolver.getSymbolsWithAnnotation("com.example.AutoToString")
//    - log how many symbols you found with logger.info(...)
//    - return emptyList()
// 3. (Conceptually) for each symbol, you'd use codeGenerator to
//    emit a generated toString() helper file.
//
// ✅ During the build, KSP runs your processor and logs the count.

import com.google.devtools.ksp.processing.*
import com.google.devtools.ksp.symbol.KSAnnotated

// your code here

Common Errors (and the fix)

• Using kapt(...) for a KSP processor — Apply the KSP plugin and switch to the ksp(...) configuration.
• Forgetting the KSP Gradle plugin — Without id("com.google.devtools.ksp"), the ksp(...) configuration won't exist.
• "Generated class not found" — Build once so KSP runs; generated sources live under build/generated.
• Version mismatch — The KSP plugin version is tied to a Kotlin version; keep them aligned.

Pro Tips

• 💡 Prefer KSP over KAPT wherever a library offers it — your builds get noticeably faster.
• 💡 Code generation beats reflection for performance and compile-time safety.
• 💡 Peek at the generated sources under build/generated/ksp when debugging.

📋 Quick Reference — KSP

🎉 Lesson Complete!

• ✅ KSP generates code at compile time from annotations
• ✅ It's faster than KAPT because it reads Kotlin natively, no Java stubs
• ✅ A SymbolProcessorProvider creates a SymbolProcessor
• ✅ Room, Hilt, and Moshi all use annotation processing
• ✅ Register processors with the ksp(...) configuration
• ✅ You've completed the advanced Kotlin track!

Practice quiz

Continue this course

• Previous: Coroutine Exceptions & Cancellation
• Quick reference: Kotlin cheat sheet

Frequently asked questions

What is KSP and what problem does it solve?

KSP — Kotlin Symbol Processing — is an API for writing lightweight compiler plugins that read your code's symbols (classes, functions, properties, annotations) and generate new source files at compile time. The problem it solves is boilerplate: instead of hand-writing repetitive code like Room DAO implementations, dependency-injection wiring, or JSON adapters, you annotate your types and a processor generates that code for you. Because it happens at compile time, the generated code is type-checked and there's no runtime reflection cost.

How is KSP different from KAPT?

KAPT (Kotlin Annotation Processing Tool) lets Kotlin use the older Java annotation processing API. To do that it generates Java stubs of your Kotlin code so Java-based processors can read them, which is slow and a frequent build bottleneck. KSP was built specifically for Kotlin: it understands Kotlin's type system natively — null-safety, extension functions, and so on — without producing Java stubs. The result is significantly faster builds and a cleaner API. Most major libraries now ship KSP processors, and the ecosystem is steadily moving from KAPT to KSP.

How do I write and register a KSP processor?

A processor has two parts. You implement SymbolProcessorProvider, a factory whose create() method returns your processor and receives a SymbolProcessorEnvironment (giving you a CodeGenerator to write files and a KSPLogger to report messages). You implement SymbolProcessor, whose process(resolver) method uses the Resolver to find symbols annotated with your annotation and then emits generated sources. To use any processor, you apply the KSP Gradle plugin and add the processor with the ksp(...) dependency configuration — the analogue of kapt(...) or annotationProcessor(...).

Which libraries use KSP, and where does the generated code go?

Many of the libraries you already use rely on annotation processing and offer KSP support: Room generates the implementations of your @Dao interfaces; Hilt and Dagger generate the dependency-injection graph; Moshi generates reflection-free JSON adapters from @JsonClass types. When KSP runs during the build, it writes the generated .kt files into a build output directory (under build/generated) and adds them to the compilation, so you can reference the generated classes from your own code as if you'd written them yourself. You rarely look at these files directly — you just enjoy the boilerplate being written for you.