Kotlin Compiler Plugins & KSP: Building Code Generation Tools

Kotlin Compiler Plugins and KSP are tools that aid in building code generation tools for large Kotlin applications. These tools help automate repetitive code for tasks such as serialization, dependency injection, and API models. This tutorial explores Kotlin Symbol Processing (KSP), its relationship with compiler plugins, and how to create an annotation-driven generator.

KSP is used for inspecting Kotlin symbols and generating source code, while compiler plugins operate deeper in the compilation pipeline and can perform transformations at a lower level. KSP is ideal for annotation processing, source generation, symbol inspection, and generating adapters and registrations. Compiler plugins are more suitable for deeper transformations like Kotlin IR, compiler-generated behavior, language-level extensions, and bytecode-related transformations.

To create an annotation, developers can define it using the `@Target` and `@Retention` annotations. In the example, the `@AutoMapper` annotation is applied to the `User` data class. The processor then automatically generates mapping code for the annotated classes.

A typical processor project includes a `processor/` directory with `AutoMapperProcessor.kt` and `AutoMapperProcessorProvider.kt` files, as well as an `app/` directory containing the source models. The `AutoMapperProcessorProvider` class extends `SymbolProcessorProvider` and implements the `create` function to return an instance of the `AutoMapperProcessor`.

The `AutoMapperProcessor` class processes symbols carrying the `@AutoMapper` annotation. It retrieves symbols with the annotation using the `Resolver` class and filters them to only include class declarations. The processor then generates mapping code for each class declaration using the `CodeGenerator` class.

KSP provides the `CodeGenerator` interface for generating source files. Developers can use KotlinPoet for larger generators to simplify safe Kotlin source generation. The generated output could look like an `UserMapper` object with a `map` function that converts a `User` object to a `UserDto` object.

To optimize large builds, a good processor should have predictable inputs, generate predictable outputs, avoid unnecessary file-system scanning, and clearly define dependencies. This helps prevent unrelated source changes from triggering expensive regeneration. Additionally, providing good diagnostics, such as error messages for incorrect usage, is crucial for developers using custom build tools.

Generated source code should be readable and maintainable. It is recommended to generate separate files for each mapped class rather than a single massive file containing unrelated code. When deeper compiler behavior is required, compiler plugins offer additional power but also introduce greater complexity and maintenance requirements.

For testing, small source examples should be used to verify both the generated Kotlin code and the successful compilation of the final output. Following design principles, a good code-generation tool should be deterministic, fast, incremental, testable, version-aware, and independent of runtime business logic.