0Pricing
Kotlin Academy · Lesson

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 — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

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.ksp plugin; add processor with ksp() 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 via environment.options
  • Use Dependencies with createNewFile() for accurate incremental rebuilds
  • Works with Android (variant configs) and Kotlin Multiplatform

Frequently asked questions

Is the “Integrating KSP Processors into a Gradle Build” lesson free?

Yes — the full text of “Integrating KSP Processors into a Gradle Build” is free to read here on the web, and the Kotlin Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Kotlin Academy course, upgrade to CoddyKit PRO.

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; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

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

  1. KSP vs KAPT: Why KSP Is Faster
  2. Writing Your First SymbolProcessor
  3. Generating Kotlin Source Files with KotlinPoet
  4. Integrating KSP Processors into a Gradle Build
← Back to Kotlin Academy