Posted by: Pavlo Stavytskyi

Kotlin Symbol Processing (KSP) is a new API from Google for creating lightweight Kotlin compiler plugins that do annotation processing.

The benefit of KSP is that it provides an idiomatic way of processing Kotlin code by understanding Kotlin-specific features, such as extension functions, local functions, declaration-site variance, and others. According to its creators, annotation processors that use KSP can run up to 2x faster compared to KAPT.

In this tutorial, we will go through each step of creating annotation processors with KSP, so that you will have an understanding of how to use it for your needs. No prior experience with annotation processing is required.

You can find the complete source code for this tutorial below.

Our processor will generate the following Kotlin function.

In this tutorial we will be focusing on generating function signatures, so their bodies will be pretty simple — just printing some message.

Project structure

We will create a Gradle project that consists of the following modules.

• processor — is our Kotlin symbol processor.
• annotations —includes annotations that our processor will use.
• main-project — is the test project where we will apply our processor.

Project setup overview

In this section, we will do an overview of the Gradle project setup, so that it is ready to work with KSP.

First, you need to create an empty Gradle JVM project using either CLI or IntelliJ IDEA.

Make sure you’re using Gradle of version 7 or above in this tutorial. In order to update Gradle in your project, run this command from its root directory:

./gradlew wrapper --gradle-version=7.1.1

Alternatively, you can clone the GitHub repository and use start directory as your project root. It contains the basic project setup that will get you ready for work with symbol processing.

We will need 3 Gradle modules described in the previous section. Their build.gradle.kts files should have the following configuration.

annotations

This is the simplest module that requires only Kotlin language configuration.

processor

This is the most important module of the project. It should depend on the annotations module as well as ksp-api artifact.

main-project

This module is the consumer of our processor that will help to see the code generation in action.

Finally, we need to specify versions of Kotlin and KSP plugins in the pluginManagement section of settings.gradle.kts file (in the root project directory). After that, specify the list of repositories for the project in the dependencyResolutionManagement section.

Now, everything is ready for the most interesting part.

Creating the processor

Step 1

In order to create the processor, we must implement a SymbolProcessorinterface.

Under the processor/src/main/kotlin/com/morfly directory create a FunctionProcessor class that implements SymbolProcessor interface.

A SymbolProcessor interface requires us to implement a process function. This will be the place where we will have all the processing logic. Let’s leave it blank for now.

Step 2

We must also create a class that implements SymbolProcessorProviderinterface. This class is responsible for instantiating the processor.

Under the processor/src/main/kotlin/com/morfly directory create a FunctionProcessorProvider class that implements SymbolProcessorProvider.

As you can see, the FunctionProcessor takes 3 constructor arguments:

• codeGenerator: CodeGenerator — entity that is responsible for creating files with the code generated by the processor.
• logger: KSPLogger — logger that performs.. well.. logging for the processor.
• options: Map<String, String> — a collection of key-value options that are passed to the processor. We will see how it works later in this tutorial.

All these arguments are taken from the SymbolProcessingEnvironmentinstance that is provided for us by KSP in FunctionProcessorProvider.create function.

Step 3

Finally, we need to register the processor we’ve just created.

Create a processor/src/main/resources/META_INF/servies directory and put there a file with the following name: com.google.devtools.ksp.processing.SymbolProcessorProvider.

Open it and register the processor provider by adding its fully qualified name:

com.morfly.FunctionProcessorProvider

Here is the structure of the processor Gradle module so far:

Creating the annotation

We need to create a custom @Function annotation, so that our processor will resolve all symbols annotated with it.

Under the annotations/src/main/kotlin/com/morfly directory create a Function.kt file with the following code:

In the snippet above, we are using resolver to retrieve all the class declarations annotated with our annotation com.morfly.Function.

In case there are no symbols that can be processed — exit.

Note. Since symbols is a Sequence but not List we don’t know its size in advance. That is why we use its iterator in order to check if its empty or not.

Now, let’s continue implementing the proceess function with the code below.

All our functions will be generated into a single file under the com.morflypackage. Using codeGenerator we generate a file that could be found at build/generated/ksp/main/kotlin/com/morfly/GeneratedFunctions.kt

When we create a new file using createNewFile it returns an instance of type OutputStream to which we will append all the file content.

Let’s implement a += operator for OutputStream, for convenience. In FunctionProcessor class above the process function, add the following code.

Finally, complete process implementation by adding the final piece of code:

This is the most important part where we traverse the symbol tree using our custom Visitor that we will create further.

Don’t forget to close OutputStream and return symbols that can’t be processed during the current round. KSP will try to run them through another round later.

Here is the complete process function implementation:

Creating a Visitor

We still have one compilation error, as Visitor(file) is unresolved currently. Let’s implement it.

In order to traverse and visit each symbol, we must implement a KSVisitorwith 2 generic type arguments, D and R.

The visitor contains a function for each type of symbol, where D is data that is getting passed or accumulated through visiting each symbol, while R is a result that each visit must return.

We will not pass the data D or return results R during the traversal for our processor. Therefore, we will use KSVisitor<Unit, Unit>.

Moreover, we don’t need to implement all the available visiting functions. Luckily, there is a KSVisitorVoid that contains empty implementations for each of the visiting functions, so we will override only those that we need.

Inside the FunctionProcessor class below the process create a Visitorclass that extends KSVisitorVoid.

Run the program using the main function.

Open main-project/build/generated/ksp/main/kotlin/com/morfly directory. If everything is done correctly, it should contain a GeneratedFucnctions.ktfile with the specified package statement.

package com.morfly

How to work with a Visitor?

Before implementing the Visitor class let’s see why and how do we need to use visitors while working with KSP.

Let’s step aside from Kotlin for a moment and take a look at a simple code snippet of some abstract programming language where we assign the result of addition to the variable.

sum = 5 + 4

In the beginning, the language compiler or interpreter sees the code as a string. Therefore, it needs to convert it to something more meaningful.

The parsing process starts with a lexer that deconstructs the code into a bunch of components called tokens: sum, =, 5, +, 4.

After that, a parser comes into action where its goal is to organize tokensinto a meaningful data structure and order, according to the language grammar. As the output, it produces an abstract syntax tree that will be used by further compilation stages.

Based on this, the example above can be represented with the following syntax tree, where each node is represented by the specific class.

Now, if we go back to Kotlin and the symbol processing API in particular, we can see that it operates with similar concepts.

Let’s consider an example of the interface, that our processor is going to process:

We can split it into the following list of components: MyAwesomeFunction, arg1, String, arg2, Map, String, List, *.

If we turn them into a tree data structure, it will look like the diagram below.

This is not the complete tree, as in practice each node would have more children. However, these are the nodes, that will be sufficient for our processor.

Each node of the symbol tree in KSP implements the base KSNode interface.

The KSNode itself implements a visitor pattern by having accept function that takes KSVisitor as an argument.

Basically, what this function does, it calls back the visitor’s visit function with the right argument type. Let’s see the KSPropertyDeclarationImpl class from KSP source code as an example.

This is how, inside theFunctionProcessor.process function, we’ve started symbol processing using our custom Visitor.

symbols.forEach { it.accept(Visitor(file), Unit) }

In general KSClassDeclaration describes all types of classes such as class, data class, interface and others. Therefore, we need to make sure, that the annotated class is actually an interface by checking the classKindproperty. Otherwise, we will stop processing.

Next, we need to get @Function annotation from the class declaration. In Kotlin, interfaces may be annotated with multiple annotations, as we know. Therefore, we need to find the right one by its name.

Next, we need to get the information from annotation arguments. In our example, we need to find out the name of the generated function by identifying the value of the name argument of the annotation.

After that, we can do the actual generation.

Continue implementing visitClassDeclaration function with the code below.

First, we need to identify all the properties that annotated interface has. These will be the arguments of a generated function.

Then, we start generating the signature of the function by delegating argument generation to the visitPropertyDeclaration function.

Finally, when the function signature is generated, we add a simple body that prints Hello from <function_name> message.

Step 2. Processing property declarations

Let’s see how visitPropertyDeclaration is implemented.

For each property, we need to simply generate function arguments in a format argName: ArgType.

While argName part is straightforward, just getting simpleName property from the property declaration, the ArgType part requires considering 2 additional steps.

Firstly, we not only need to generate the argument type but also make sure it is imported to the file. This means that we need to have the fully qualified name of the type. This can be done in two ways:

1. Using import statement:
   import com.package.ArgType.
2. Using the fully qualified name of the type each time we use it:
   argName: com.package.ArgType.

We will use the second option as it is easier to implement. We won’t need to go back and forth between the import declarations and places in the code where the type is used, during the code generation.

So, how do we get the fully qualified name of the type?

If we use KSPropertyDeclaration.type, we get the object of type KSTypeReference . However, in order to get the information about the type, KSTypeReference must be resolved by calling resolve function that returns the object of the type KSType.

So, when you have an object of type KSType, we can get the fully qualified name by using the code below.

resolvedType.declaration.qualifiedName?.asString

Note. The resolve operation is expensive in terms of computation as the KSP will need to go and find the place where the type is declared. So, it must be used carefully.

Secondly, we must handle cases when the type has generic parameters such as ArgType<String> . This requires us to implement additional functionality.

Step 3. Processing generic type arguments

For each argument type that we resolve in visitPropertyDeclaration we must separately resolve its generic arguments that are declared between angle brackets < >.

In the Visitor class between visitPropertyDeclaration and visitTypeArgument functions declare a helper function called visitTypeArguments (plural) that takes the list of type arguments.

The function above will set up formatting for generic type arguments block and iterate through each one by calling visitTypeArgument function.

Let’s start implementing the visitTypeArgument function.

When working with generics in Kotlin we must also consider a concept in generics called variance. (see the official Kotlin docs to learn more).

There are 4 variance types that we must consider:

• star — Type<*> (we just generate * symbol instead of argument type)
• covariant — Type<out OtherType> (we add out before the actual type)
• contravariant — Type<in OtherType> (we add in before the actual type)
• invariant — Type<OtherType> (just add the argument type itself)

After we handled the type variance, we must identify the actual type of the generic argument.

We apply the same approach as we used to define the property type. First, we resolve KSTypeReference, and then get the fully qualified name from KSType:

resolvedType?.declaration?.qualifiedName?.asString()

Don’t forget to make the argument type nullable by adding ?, if needed.

Finally, we must handle the nested argument types such as Type<OtherType<OtherType>>.

This is a pretty straightforward task as we have all the necessary components for it already implemented. Just call visitTypeArguments(plural) inside visitTypeArgument function for its nested argument types and it will do the work recursively.

Running the processor

This is all we need to implement our processor. Now we can run it and see how it works.

Open main-project/src/main/kotlin/com/morfly/Main.kt file and replace its contents with the code below.

We are almost there…

By default, your IDE knows nothing about the code generated with KSP. In order to help it to recognize generated files, open main-project/build.gradle.kts and add the code below somewhere in the file.

By adding this configuration, we explicitly marked a directory with the generated code as a Kotlin source directory.

Note. Don’t forget to sync Gradle changes.

Now, run the main function in the main-project/.../Main.kt file.

To verify, that the code generation was done successfully, open
main-project/build/generated/ksp/.../GeneratedFunctions.kt file and verify its contents.

We will generate function arguments where their generic type arguments are replaced with *.

To do this we need to add a small change to our processor.

Open processor/.../FunctionProcessor.kt file. Go to the Visitor.visitTypeArgument function and add the following code at the very beginning of the function.

If you remember, we have passed an options: Map<String, String>argument to the FunctionProcessor class constructor.

We can check if it has an option named ignoreGenericArgs and check if it equals to "true".

Note. KSP supports only String values for the options, that is why we check if the option is equal to "true" string instead of boolean true.

Now, open main-project/build.gradle.kts file and pass the argument to our processor.

Note. Don’t forget to sync Gradle changes.

Now, run the main function in the main-project/.../Main.kt file. Open
main-project/build/generated/ksp/.../GeneratedFunctions.kt file and verify its contents.

You can find the complete source code for this tutorial below.