# Kotlin Symbol Processing API

Welcome to KSP!

Kotlin Symbol Processing (KSP) is an API that you can use to develop
lightweight compiler plugins. KSP provides a simplified compiler plugin
API that leverages the power of Kotlin while keeping the learning curve at
a minimum. Compared to KAPT, annotation processors that use KSP can run up to 2x faster.

Most of the documentation of KSP can be found
on [kotlinlang.org](https://kotlinlang.org/docs/ksp-overview.html). Here are some handy links:

* [Overview](https://kotlinlang.org/docs/ksp-overview.html)
* [Quickstart](https://kotlinlang.org/docs/ksp-quickstart.html)
* [Libraries that support KSP](https://kotlinlang.org/docs/ksp-overview.html#supported-libraries)
* [Examples](https://kotlinlang.org/docs/ksp-examples.html)
* [How KSP models Kotlin code](https://kotlinlang.org/docs/ksp-additional-details.html)
* [Reference for Java annotation processor authors](https://kotlinlang.org/docs/ksp-reference.html)
* [Incremental processing notes](https://kotlinlang.org/docs/ksp-incremental.html)
* [Multiple round processing notes](https://kotlinlang.org/docs/ksp-multi-round.html)
* [KSP on multiplatform projects](https://kotlinlang.org/docs/ksp-multiplatform.html)
* [Running KSP from command line](https://kotlinlang.org/docs/ksp-command-line.html)
* [FAQ](https://kotlinlang.org/docs/ksp-faq.html)

For debugging and testing processors, as well as KSP itself, please
check [DEVELOPMENT.md](DEVELOPMENT.md)

---

## KSP Gradle Configurations Reference

This section contains a reference of Gradle configurations for KSP.
If you have not used KSP before, or this section seems unclear,
please read the documentation on the Kotlin lang website which is linked above.

When applying KSP in your Gradle project, place symbol processor dependencies into the appropriate
configuration inside the `dependencies { ... }` block of your `build.gradle.kts` (or `build.gradle`)
file based on your target platforms, source sets, and build variants.

### Single-Platform (JVM & Android)

| Configuration Name / Pattern | Project Type / Target       | Source Set / Scope                         | Usage Example (`build.gradle.kts`)          | Details & Behavior                                                                                                                                  |
|------------------------------|-----------------------------|--------------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `ksp`                        | Single-target JVM / Android | Main source set (`src/main`)               | `ksp("com.example:processor:1.0")`          | Applied to default JVM compilation and single-platform Android main source set. Deprecated in KMP unless `ksp.allow.all.target.configuration=true`. |
| `kspTest`                    | Single-target JVM / Android | Unit tests (`src/test`)                    | `kspTest("com.example:test-processor:1.0")` | Runs symbol processing exclusively for unit test sources.                                                                                           |
| `ksp<SourceSet>`             | Single-target JVM           | Custom JVM source set                      | `add("kspIntegrationTest", "...")`          | Generates sources for custom source sets like `integrationTest`.                                                                                    |
| `ksp<BuildType>`             | Android (Single-platform)   | Specific build type (e.g., debug, release) | `add("kspDebug", "...")`                    | Runs processor only when compiling the specified Android build variant.                                                                             |
| `ksp<Flavor>`                | Android (Single-platform)   | Product flavor (e.g., free, paid)          | `add("kspFree", "...")`                     | Runs processor for all build variants matching the specified flavor.                                                                                |
| `ksp<Flavor><BuildType>`     | Android (Single-platform)   | Flavor + Build Type combination            | `add("kspFreeDebug", "...")`                | Targeted execution for a specific flavor + build type variant.                                                                                      |
| `kspTest<Flavor><BuildType>` | Android (Single-platform)   | Local Unit Tests for variant/flavor        | `add("kspTestDebug", "...")`                | Runs processing on unit test code in `src/testDebug`.                                                                                               |
| `kspAndroidTest<Variant>`    | Android (Single-platform)   | Instrumentation Tests (`src/androidTest`)  | `add("kspAndroidTestDebug", "...")`         | Runs processing on Android instrumentation test code (`src/androidTest`).                                                                           |

### Kotlin Multiplatform (KMP)

| Configuration Name / Pattern | Project Type / Target | Source Set / Scope                                  | Usage Example (`build.gradle.kts`)                                                                                                                                                         | Details & Behavior                                                                                            |
|------------------------------|-----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| `ksp<Target>`                | Kotlin Multiplatform  | KMP target main compilation (JVM, JS, Native, Wasm) | `add("kspJvm", "...")`<br>`add("kspJs", "...")`<br>`add("kspIosArm64", "...")`<br>`add("kspAndroid", "...")`<br>`add("kspAndroidHostTest", "...")`<br>`add("kspAndroidDeviceTest", "...")` | Target-specific configuration. Omits the Main suffix (e.g., target `jvm` becomes `kspJvm`, not `kspJvmMain`). |
| `ksp<Target>Test`            | Kotlin Multiplatform  | KMP target test compilation                         | `add("kspJvmTest", "...")`<br>`add("kspJsTest", "...")`                                                                                                                                    | Target-specific test configuration.                                                                           |
| `kspCommonMainMetadata`      | Kotlin Multiplatform  | Common Main metadata compilation                    | `add("kspCommonMainMetadata", "...")`                                                                                                                                                      | Target-specific configuration for KMP `commonMain` metadata processing.                                       |

## KSP Gradle Properties Reference

This section provides a reference of Gradle properties for KSP.
These properties can be set in your project's `gradle.properties` file or passed via command line
options (`-Pproperty=value` or `-Dproperty=value`).

### Reference Table

| Property Key                                | Type      | Default | Description                                                                                                                                                                                                                                     | Documentation                                                                                                             |
|:--------------------------------------------|:----------|:--------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------|
| `ksp.incremental`                           | `Boolean` | `true`  | Enables or disables incremental symbol processing in KSP.                                                                                                                                                                                       | [Incremental Processing](https://kotlinlang.org/docs/ksp-incremental.html)                                                |
| `ksp.incremental.log`                       | `Boolean` | `false` | Enables verbose log output detailing incremental processing decisions and symbol changes.                                                                                                                                                       | [Incremental Logging](https://kotlinlang.org/docs/ksp-incremental.html#reporting-bugs)                                    |
| `ksp.incremental.log.graph.origin`          | `String?` | `null`  | Filters incremental log tracing to a specific symbol origin class/package. The value should be of the form `com.example.MyClass`.                                                                                                               | [Incremental Dependency Graph](https://kotlinlang.org/docs/ksp-incremental.html#visualizing-the-symbol-dependency-graph)  |
| `ksp.allow.all.target.configuration`        | `Boolean` | `false` | Permits the legacy global `ksp` configuration in both single-platform and Kotlin Multiplatform (KMP) projects with a warning instead of an error.                                                                                               | [`ksp` Configuration](https://kotlinlang.org/docs/ksp-multiplatform.html#avoid-the-ksp-configuration-on-ksp-1-0-1)        |
| `ksp.project.isolation.enabled`             | `Boolean` | `false` | Enables Gradle Project Isolation compatible codepaths for output directory registration. **NOTE:** KSP also enables this whenever Gradle's own Isolated Projects feature is active, e.g. through `org.gradle.isolated-projects=true` or `--isolated-projects`. Setting this to `true` forces the codepath on even when Isolated Projects is off.    | [Gradle Isolated Projects](https://docs.gradle.org/current/userguide/isolated_projects.html)                              |
| `ksp.experimental.psi.resolution`           | `Boolean` | `false` | Enables experimental PSI-based resolution inside the KSP compiler engine. Enabling this may improve build times, but expect crashes. Feel free to open a bug report if you encounter a crash.                                                   | None                                                                                                                      |
| `ksp.experimental.metadata.own.sources.only` | `Boolean` | `false` | In KMP projects, makes metadata (shared source set) compilations process only their own source sets, matching what the Kotlin compiler compiles. Upstream source sets remain resolvable through their klibs but are no longer returned by `Resolver.getAllFiles()`, so an intermediate source set such as `webMain` no longer regenerates code already generated for `commonMain`. | [#2814](https://github.com/google/ksp/issues/2814)                                                                        |
| `ksp.ksp2.profiling.mode`                   | `Boolean` | `false` | Enables performance profiling for KSP2 task execution. This is mostly for developing KSP itself.                                                                                                                                                | None                                                                                                                      |
| `ksp.classloader.cache.processors`          | `Boolean` | `false` | Reuses symbol processor classloaders across modules within a single build, instead of constructing one per KSP task. This can substantially reduce build time in large multi-module projects that share the same processors. Off by default because a shared classloader also extends the lifetime of any static state held by processors. | None                                                                                                                      |
| `kotlin.native.enableKlibsCrossCompilation` | `Boolean` | `true`  | Enables running symbol processing tasks for other targets than the host machine in KMP projects, i.e., cross-compilation. This property is not created by the KSP Gradle plugin. It is owned by the Kotlin compiler but KSP uses this property. | [Kotlin Cross Compilation](https://kotlinlang.org/docs/whatsnew21.html#ability-to-publish-kotlin-libraries-from-any-host) |

---

## Nightly Builds

Nightly builds of KSP for the latest Kotlin stable releases are published here:

```
maven("https://central.sonatype.com/repository/maven-snapshots/")
```

## Feedback and Bug Reporting

[Please let us know what you think about KSP by filing a Github issue](https://github.com/google/ksp/issues)
or connecting with our team in the `#ksp` channel in the
[Kotlin Slack workspace](https://kotlinlang.slack.com/)!

If you are interested in sending PRs, please also check out
the [Contributor guide](CONTRIBUTING.md).

## Ongoing and Future Work

Here are some planned features that have not yet been completely implemented:

* Improve support to multiplatform. E.g., running KSP on a subset of targets / sharing computations
  between targets
* Improve performance. There are a bunch of optimizations to be done!
* Keep fixing bugs!

## A Note on KSP1

KSP 1.x has been removed and is no longer supported.