Integrating KSP Processors into a Gradle Build
Configure KSP in Gradle, add generated sources, and debug processor output.
Integrating KSP Processors into a Gradle Build is a free Kotlin Academy lesson on CoddyKit. This is lesson 4 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, and your progress syncs across the web and the CoddyKit app. The Kotlin Academy course includes 4 lessons in total.
Multi-Module Structure
A typical KSP setup has at least two modules: :annotation (contains your annotation classes) and :processor (contains the SymbolProcessor). The consumer module applies the KSP plugin and declares ksp and implementation dependencies.
Applying the KSP Plugin
In the consuming module's build.gradle.kts:
plugins {
kotlin("jvm") // or android, multiplatform
id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}Declaring the ksp Dependency
Use the ksp configuration (not implementation) to add a KSP processor. The processor runs at build time only and is not included in the final artifact:
dependencies {
implementation(project(":annotation"))
ksp(project(":processor"))
}Generated Source Directories
KSP writes generated files under build/generated/ksp/<sourceSet>/kotlin/. The KSP plugin automatically adds these directories to the Kotlin source set, so generated classes are visible to your code without manual configuration.
Passing Options to the Processor
Pass build-time options from Gradle to your processor via ksp { arg("key", "value") }. Read them in the processor via environment.options["key"]:
// build.gradle.kts (consumer)
ksp {
arg("generateMocks", "true")
arg("outputPackage", "com.example.generated")
}Reading Options in the Processor
In the SymbolProcessorProvider.create() method, access options from the environment:
class MyProcessorProvider : SymbolProcessorProvider {
override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
val genMocks = environment.options["generateMocks"] == "true"
return MyProcessor(environment.codeGenerator, environment.logger, genMocks)
}
}Incremental Builds
KSP tracks input-output dependencies. Associate each generated file with its source symbols when calling codeGenerator.createNewFile(). KSP then skips reprocessing when none of the tracked inputs changed.
val deps = Dependencies(aggregating = false, *symbols.map { it.containingFile!! }.toTypedArray())
codeGenerator.createNewFile(deps, packageName, fileName)KSP with Android
For Android projects, replace kapt with ksp in both the plugin and dependency declarations. Use variant-aware configurations like kspDebug or kspRelease if you need processor behavior to differ between build types.
KSP with Kotlin Multiplatform
In a KMP project, apply the KSP plugin and use add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) or the shorthand kspCommonMainMetadata, kspJvmMain, etc., depending on which targets your processor supports.
Viewing Generated Files
After running ./gradlew build (or kspKotlin / kspDebugKotlin for Android), inspect build/generated/ksp/. IntelliJ and Android Studio mark these folders as generated sources and allow navigation from usages to generated declarations.
Debugging a Processor
Run the Gradle task with --debug or add jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") to the ksp configuration to attach a remote debugger to the annotation processing JVM.
Quick Check
Which Gradle configuration is used to add a KSP processor that runs at build time but is not included in the runtime classpath?
Recap: Integrating KSP into a Gradle Build
Key takeaways:
- Apply
com.google.devtools.kspplugin; add processor withksp()dependency - Generated sources land in
build/generated/ksp/and are auto-added to the source set - Pass options from Gradle via
ksp { arg() }; read them viaenvironment.options - Use
DependencieswithcreateNewFile()for accurate incremental rebuilds - Works with Android (variant configs) and Kotlin Multiplatform
Learn Kotlin with an AI tutor — free
Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.
- Courses
- 51
- Lessons
- 203
Frequently Asked Questions
Is the “Integrating KSP Processors into a Gradle Build” lesson free?
Yes — any 3 lessons of the Kotlin Academy learning path, including “Integrating KSP Processors into a Gradle Build”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Kotlin Academy course includes 4 lessons in total.
What will I learn in “Integrating KSP Processors into a Gradle Build”?
Configure KSP in Gradle, add generated sources, and debug processor output. You practise Kotlin Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Kotlin Academy?
No prior experience is required. Kotlin Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.
How long does the “Integrating KSP Processors into a Gradle Build” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Kotlin Academy lesson?
Yes. Every Kotlin Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- KSP vs KAPT: Why KSP Is Faster
- Writing Your First SymbolProcessor
- Generating Kotlin Source Files with KotlinPoet
- Integrating KSP Processors into a Gradle Build