Annotation Processing with Kotlin

    In a nutshell, you can use libraries such as Dagger or in your Kotlin projects.

    Please read below about how to apply the kapt plugin to your Gradle/Maven build.

    Apply the Gradle plugin:

    1. plugins {
    2.     kotlin("kapt") version "1.4.21"
    3. }

    Alternatively, you can use the apply plugin syntax:

    1. apply plugin: 'kotlin-kapt'

    Then add the respective dependencies using the kapt configuration in your dependencies block:

    1. dependencies {
    2.     kapt 'groupId:artifactId:version'
    3. }
    1. dependencies {
    2.     kapt("groupId:artifactId:version")
    3. }

    If you previously used the Android support for annotation processors, replace usages of the annotationProcessor configuration with kapt. If your project contains Java classes, kapt will also take care of them.

    If you use annotation processors for your androidTest or test sources, the respective kapt configurations are named kaptAndroidTest and kaptTest. Note that kaptAndroidTest and kaptTest extends kapt, so you can just provide the kapt dependency and it will be available both for production sources and tests.

    Annotation processor arguments

    Use arguments {} block to pass arguments to annotation processors:

    Gradle build cache support (since 1.2.20)

    The kapt annotation processing tasks are by default. However, annotation processors run arbitrary code that may not necessarily transform the task inputs into the outputs, might access and modify the files that are not tracked by Gradle etc. If the annotation processors used in the build cannot be properly cached, it is possible to disable caching for kapt entirely by adding the following lines to the build script, in order to avoid false-positive cache hits for the kapt tasks:

    1. kapt {
    2.     useBuildCache = false
    3. }

    Running kapt tasks in parallel (since 1.2.60)

    To use the Gradle worker API for parallel execution of kapt tasks, add this line to your gradle.properties file:

      To improve the times of incremental builds with kapt, it can use the Gradle . With compile avoidance enabled, Gradle can skip annotation processing when rebuilding a project. Particularly, annotation processing is skipped when:

      • The project’s source files are unchanged.
      • The changes in dependencies are ABI compatible. For example, the only changes are in method bodies.

      However, compile avoidance can’t be used for annotation processors discovered in the compile classpath since any changes in them require running the annotation processing tasks.

      To run kapt with compile avoidance:

      • Add the annotation processor dependencies to the kapt* configurations manually as described .
      • Turn off the discovery of annotation processors in the compile classpath by adding this line to your gradle.properties file:
      1. kapt.include.compile.classpath=false

      Incremental annotation processing (since 1.3.30)

      Starting from version 1.3.30, kapt supports incremental annotation processing as an experimental feature. Currently, annotation processing can be incremental only if all annotation processors being used are incremental.

      Incremental annotation processing is enabled by default starting from version 1.3.50. To disable incremental annotation processing, add this line to your gradle.properties file:

      1. kapt.incremental.apt=false

      Note that incremental annotation processing requires to be enabled as well.

      Java compiler options

      Kapt uses Java compiler to run annotation processors.
      Here is how you can pass arbitrary options to javac:

      Non-existent type correction

      Some annotation processors (such as AutoFactory) rely on precise types in declaration signatures. By default, Kapt replaces every unknown type (including types for the generated classes) to NonExistentClass, but you can change this behavior. Add the additional flag to the build.gradle file to enable error type inferring in stubs:

      1. kapt {
      2.     correctErrorTypes = true
      3. }
      1. <execution>
      2.     <id>kapt</id>
      3.     <goals>
      4.         <goal>kapt</goal>
      5.     </goals>
      6.     <configuration>
      7.         <sourceDirs>
      8.             <sourceDir>src/main/kotlin</sourceDir>
      9.             <sourceDir>src/main/java</sourceDir>
      10.         </sourceDirs>
      11.         <annotationProcessorPaths>
      12.             <!-- Specify your annotation processors here. -->
      13.             <annotationProcessorPath>
      14.                 <groupId>com.google.dagger</groupId>
      15.                 <artifactId>dagger-compiler</artifactId>
      16.                 <version>2.9</version>
      18.     </configuration>
      19. </execution>

      You can find a complete sample project showing the use of Kotlin, Maven and Dagger in the Kotlin examples repository.

      Please note that kapt is still not supported for IntelliJ IDEA’s own build system. Launch the build from the “Maven Projects” toolbar whenever you want to re-run the annotation processing.

      Using in CLI

      Kapt compiler plugin is available in the binary distribution of the Kotlin compiler.

      You can attach the plugin by providing the path to its JAR file using the Xplugin kotlinc option:

      1. -Xplugin=$KOTLIN_HOME/lib/kotlin-annotation-processing.jar

      Here is a list of the available options:

      • sources (required): An output path for the generated files.
      • classes (required): An output path for the generated class files and resources.
      • stubs (required): An output path for the stub files. In other words, some temporary directory.
      • incrementalData: An output path for the binary stubs.
      • apclasspath (repeatable): A path to the annotation processor JAR. Pass as many apclasspath options as many JARs you have.
      • apoptions: A base64-encoded list of the annotation processor options. See AP/javac options encoding for more information.
      • javacArguments: A base64-encoded list of the options passed to javac. See for more information.
      • processors: A comma-specified list of annotation processor qualified class names. If specified, kapt does not try to find annotation processors in apclasspath.
      • verbose: Enable verbose output.
      • aptMode (required)
        • stubs – only generate stubs needed for annotation processing;
        • apt – only run annotation processing;
        • stubsAndApt – generate stubs and run annotation processing.
      • correctErrorTypes: See below. Disabled by default.

      The plugin option format is: -P plugin:<plugin id>:<key>=<value>. Options can be repeated.

      An example:

      1. -P plugin:org.jetbrains.kotlin.kapt3:sources=build/kapt/sources
      2. -P plugin:org.jetbrains.kotlin.kapt3:classes=build/kapt/classes
      3. -P plugin:org.jetbrains.kotlin.kapt3:stubs=build/kapt/stubs
      5. -P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/ap.jar
      6. -P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/anotherAp.jar

      Generating Kotlin sources

      Kapt can generate Kotlin sources. Just write the generated Kotlin source files to the directory specified by processingEnv.options["kapt.kotlin.generated"], and these files will be compiled together with the main sources.

      You can find the complete sample in the kotlin-examples Github repository.

      AP/Javac options encoding

      and javacArguments CLI options accept an encoded map of options.
      Here is how you can encode options by yourself: