Kotlin Symbol Processors
Kotlin Symbol Processing (KSP) is a library built by our friends at Google, which provides an API to build lightweight compiler plugins. KSP provides a simplified compiler plugin API that leverages the power of Kotlin while keeping the learning curve to a minimum. Compared to KAPT, annotation processors that use KSP can run up to 2x faster, offer direct access to Kotlin language constructs, and support multiplatform targets. And it is now Stable!
The KSP API processes Kotlin programs idiomatically. KSP understands Kotlin-specific features, such as extension functions, declaration-site variance, and local functions. It also models types explicitly and provides basic type checking, such as equivalence and assign compatibility.
Notionally, it is similar to KType in Kotlin reflection on the one hand – the API allows processors to navigate from class declarations to corresponding types with specific type arguments and vice-versa. On the other hand, we can think of KSP as a preprocessor framework of Kotlin programs. Unlike a full-fledged compiler plugin, processors cannot modify the code. KSP treats the source programs as read-only.
KSP makes creating lightweight compiler plugins easier. It hides compiler changes, minimizing maintenance efforts for processors that use it. KSP is not tied to the JVM, so it can be adapted to other platforms, like Kotlin/Native or Kotlin/JS, more easily in the future. For some processors, such as Glide, KSP reduces total compilation times by up to 25% compared to KAPT. KSP improves the build speed for Kotlin developers drastically (up to 2x faster for Room’s Kotlin test app).
What about KAPT?
KAPT is an excellent solution that makes many Java annotation processors work for Kotlin programs out-of-the-box.
KAPT is critical infrastructure for many projects, so it will be maintained for the foreseeable future. There is no roadmap for KAPT because we aren’t planning any new features for it. All new feature development related to all kinds of “annotation processing” in Kotlin will be focused on KSP and other Kotlin compiler plugins in general. However, we’ll make sure that KAPT stays compatible with the most recent versions of Kotlin and Java, and the bugs will be prioritized and fixed.
The significant advantages of KSP over KAPT are its improved build performance, not being tied to the JVM, more idiomatic Kotlin API, and the ability to understand Kotlin-only symbols.
You can learn more about KSP vs. KAPT in the documentation.
What about IDE support?
IDEs are currently unable to detect KSP-generated declarations on the fly, so KSP functions the same way as KAPT.
How to get started
To start using KSP, first get a sample processor to check out.
And then, depending on your goals, follow the instructions: to create a processor of your own, to use your processor in a project, to pass options to processors, and to make your IDE aware of generated code.
What to read:
- Accelerated Kotlin build times with Kotlin Symbol Processing 1.0
- Kotlin Symbol Processing API
- The Dark Secrets of Fast Compilation for Kotlin | The Kotlin Blog