kapt compiler plugin

Follow these steps:

1. Apply the kotlin-kapt Gradle plugin:

   Kotlin

   Groovy

   plugins {
       kotlin("kapt") version "2.1.20"
   }

   plugins {
       id "org.jetbrains.kotlin.kapt" version "2.1.20"
   }

2. Add the respective dependencies using the kapt configuration in your dependencies block:

   Kotlin

   Groovy

   dependencies {
       kapt("groupId:artifactId:version")
   }

   dependencies {
       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.

warning

Support for K2 in the kapt compiler plugin is Experimental. Opt-in is required (see details below), and you should use it only for evaluation purposes.

From Kotlin 1.9.20, you can try using the kapt compiler plugin with the K2 compiler, which brings performance improvements and many other benefits. To use the K2 compiler in your Gradle project, add the following option to your gradle.properties file:

kapt.use.k2=true

If you use the Maven build system, update your pom.xml file:

<configuration>
   ...
   <args>
      <arg>-Xuse-k2-kapt</arg>
   </args>
</configuration>

tip

To enable the kapt plugin in your Maven project, see Use in Maven.

If you encounter any issues when using kapt with the K2 compiler, please report them to our issue tracker.

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

kapt {
    arguments {
        arg("key", "value")
    }
}

The kapt annotation processing tasks are cached in Gradle 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:

kapt {
    useBuildCache = false
}

To improve the times of incremental builds with kapt, it can use the Gradle compile avoidance. 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 above.

• Turn off the discovery of annotation processors in the compile classpath by adding this line to your gradle.properties file:

kapt.include.compile.classpath=false

kapt supports incremental annotation processing that is enabled by default. Currently, annotation processing can be incremental only if all annotation processors being used are incremental.

To disable incremental annotation processing, add this line to your gradle.properties file:

kapt.incremental.apt=false

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

You can define a common set of annotation processors in a separate Gradle configuration as a superconfiguration and extend it further in kapt-specific configurations for your subprojects.

As an example, for a subproject using Dagger, in your build.gradle(.kts) file, use the following configuration:

val commonAnnotationProcessors by configurations.creating
configurations.named("kapt") { extendsFrom(commonAnnotationProcessors) }

dependencies {
    implementation("com.google.dagger:dagger:2.48.1")
    commonAnnotationProcessors("com.google.dagger:dagger-compiler:2.48.1")
}

In this example, the commonAnnotationProcessors Gradle configuration is your common superconfiguration for annotation processing that you want to be used for all your projects. You use the extendsFrom() method to add commonAnnotationProcessors as a superconfiguration. kapt sees that the commonAnnotationProcessors Gradle configuration has a dependency on the Dagger annotation processor. Therefore, kapt includes the Dagger annotation processor in its configuration for annotation processing.

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

kapt {
    javacOptions {
        // Increase the max count of errors from annotation processors.
        // Default is 100.
        option("-Xmaxerrs", 500)
    }
}

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 option to the build.gradle(.kts) file to enable error type inferring in stubs:

kapt {
    correctErrorTypes = true
}

Add an execution of the kapt goal from kotlin-maven-plugin before compile:

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal> <!-- You can skip the <goals> element
        if you enable extensions for the plugin -->
    </goals>
    <configuration>
        <sourceDirs>
            <sourceDir>src/main/kotlin</sourceDir>
            <sourceDir>src/main/java</sourceDir>
        </sourceDirs>
        <annotationProcessorPaths>
            <!-- Specify your annotation processors here -->
            <annotationProcessorPath>
                <groupId>com.google.dagger</groupId>
                <artifactId>dagger-compiler</artifactId>
                <version>2.9</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

To configure the level of annotation processing, set one of the following as the aptMode in the <configuration> block:

• stubs – only generate stubs needed for annotation processing.

• apt – only run annotation processing.

• stubsAndApt – (default) generate stubs and run annotation processing.

For example:

<configuration>
   ...
   <aptMode>stubs</aptMode>
</configuration>

To enable the kapt plugin with the K2 compiler, add the -Xuse-k2-kapt compiler option:

<configuration>
   ...
   <args>
      <arg>-Xuse-k2-kapt</arg>
   </args>
</configuration>

kapt is 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.

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:

-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 the number of JARs that 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 AP/javac options encoding 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: For more information, see Non-existent type correction. Disabled by default.

• dumpFileReadHistory: An output path to dump for each file a list of classes used during annotation processing.

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

An example:

-P plugin:org.jetbrains.kotlin.kapt3:sources=build/kapt/sources
-P plugin:org.jetbrains.kotlin.kapt3:classes=build/kapt/classes
-P plugin:org.jetbrains.kotlin.kapt3:stubs=build/kapt/stubs

-P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/ap.jar
-P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/anotherAp.jar

-P plugin:org.jetbrains.kotlin.kapt3:correctErrorTypes=true

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.

Note that kapt does not support multiple rounds for the generated Kotlin files.

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

fun encodeList(options: Map<String, String>): String {
    val os = ByteArrayOutputStream()
    val oos = ObjectOutputStream(os)

    oos.writeInt(options.size)
    for ((key, value) in options.entries) {
        oos.writeUTF(key)
        oos.writeUTF(value)
    }

    oos.flush()
    return Base64.getEncoder().encodeToString(os.toByteArray())
}

By default, kapt runs all annotation processors and disables annotation processing by javac. However, you may need some of javac's annotation processors working (for example, Lombok).

In the Gradle build file, use the option keepJavacAnnotationProcessors:

kapt {
    keepJavacAnnotationProcessors = true
}

If you use Maven, you need to specify concrete plugin settings. See this example of settings for the Lombok compiler plugin.