kapt compiler plugin

Gradle

To use kapt in Gradle, follow these steps:

1. Apply the kapt Gradle plugin in your build script file build.gradle(.kts):

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

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

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

   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, the kapt plugin processes them as well.

   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 extend kapt, so you can provide the kapt dependency, and it will be available both for production sources and tests.

Maven

You can set up kapt using either the <extensions> option to simplify setup or manually to get full control over kapt's execution.

CLI

kapt is available as a standalone CLI tool in the binary distribution of the Kotlin compiler.

To run kapt from the command line, use:

For example:

• See the full list of kapt-specific compiler options.

• You can also pass all valid Kotlin compiler options. Run kotlinc -help to see them.

Configure processor classpath and discovery

You can disable the discovery of annotation processors that aren't included in kapt's processor path. This excludes unnecessary annotation processors from the compile classpath.

Inherit annotation processors from superconfigurations

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 MapStruct, in your build.gradle(.kts) file, use the following configuration:

In this example, the commonAnnotationProcessors Gradle configuration is the 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 MapStruct annotation processor. Therefore, kapt includes the MapStruct annotation processor in its configuration for annotation processing.

Keep Java compiler's annotation processors

By default, kapt runs all annotation processors and disables annotation processing by javac. However, you may need javac to run some annotation processors, such as Lombok.

In the Gradle build file, use the option keepJavacAnnotationProcessors:

If you use Maven, configure the plugin explicitly. See this example of setting up the Lombok compiler plugin.

Run kapt tasks in parallel

kapt uses the Gradle Worker API to run annotation processing tasks. Using the Worker API lets Gradle run independent annotation processing tasks from a single project in parallel, which in some cases significantly decreases the execution time.

If you set the custom JDK version in the Kotlin Gradle plugin, kapt task workers use only the processIsolation() mode.

If you want to provide additional JVM arguments for a kapt worker process, use the input kaptProcessJvmArgs of the KaptWithoutKotlincTask:

Use Gradle build cache safely

Gradle caches kapt annotation processing tasks by default. However, annotation processors can run arbitrary code. This may result in unnecessary transformations of task inputs into outputs, or accessing and modifying files that Gradle doesn't track.

When annotation processors used in the build can't be properly cached, you can disable caching to prevent false-positive hits for kapt tasks. To do this, use the useBuildCache property in the build script:

Cache annotation processors' classloaders

Caching for annotation processors' classloaders helps kapt perform faster if you run many Gradle tasks consecutively.

To enable this feature, use the following properties in your gradle.properties file:

If you run into any problems with caching for annotation processors, disable caching for them:

Use incremental annotation processing

With Gradle, kapt supports incremental annotation processing by default so that only the changed files are re-processed.

Currently, incremental annotation processing works only if:

• Incremental compilation is enabled.

• All annotation processors in the build are incremental.

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

Measure the performance of annotation processors

To get performance statistics on the annotation processors execution, use the showProcessorStats option. An example output:

You can dump this report to a file with the dumpProcessorStats option. For example, the following CLI command runs kapt and dumps the statistics to the ap-perf-report.file file:

Track the number of generated files

The kapt plugin can report statistics on the number of generated files for each annotation processor.

This helps track whether any unused annotation processors are included in the build. You can use the generated report to find modules that trigger unnecessary annotation processors and update the modules to avoid that.

To enable statistics reporting:

1. In your Gradle build file, set the showProcessorStats option to true:

   // build.gradle(.kts) kapt { showProcessorStats = true }

2. In your gradle.properties file, set the verbose compiler option to true:

   # gradle.properties kapt.verbose=true

The statistics appear in the logs with the info level. You can see the Annotation processor stats: line followed by statistics on the execution time of each annotation processor. After these lines, there is the Generated files report: line followed by statistics on the number of generated files for each annotation processor. For example:

Annotation processor configuration

Output directory options

Behavioral options

Diagnostics and statistics options