Использование kapt

Использование в Gradle

Выполните следующие шаги:

1. Примените плагин kotlin-kapt Gradle:

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

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

2. Добавьте соответствующие зависимости, используя конфигурацию kapt в вашем блоке dependencies:

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

   dependencies {
       kapt 'groupId:artifactId:version'
   }
   

3. Если вы ранее использовали поддержку Android для обработчиков аннотаций, замените использования конфигурации annotationProcessor на kapt. Если в вашем проекте есть Java-классы, kapt также позаботится о них.

   Если вы используете обработчики аннотаций для ваших androidTest или test источников, соответствующие конфигурации kapt называются kaptAndroidTest и kaptTest. Обратите внимание, что kaptAndroidTest и kaptTest расширяют kapt, поэтому вы можете просто указать зависимость kapt и она будет доступна как для источников производства, так и для тестов.

4. Чтобы использовать самые новые функции Kotlin с kapt, например, повторяемые аннотации, включите поддержку бекенда IR с помощью следующего параметра в вашем gradle.properties:

   kapt.use.jvm.ir=true
   

Аргументы обработчика аннотаций

Используйте блок arguments {} для передачи аргументов обработчикам аннотаций:

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

Поддержка кеша сборки Gradle

Задачи обработки аннотаций kapt по умолчанию кэшируются в Gradle. Однако обработчики аннотаций выполняют произвольный код, который может не обязательно преобразовывать входные данные задачи в выходные данные, могут получать доступ к файлам и изменять их, которые не отслеживаются Gradle и т.д. Если обработчики аннотаций, используемые в сборке, не могут быть должным образом кэшированы, можно полностью отключить кэширование для kapt, добавив следующие строки в скрипт сборки, чтобы избежать ложноположительных попаданий в кэш для задач kapt:

kapt {
    useBuildCache = false
}

Улучшение скорости сборок, использующих kapt

tasks.withType<org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask>()
    .configureEach {
        kaptProcessJvmArgs.add("-Xmx512m")
    }

tasks.withType(org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask.class)
    .configureEach {
        kaptProcessJvmArgs.add('-Xmx512m')
    }

# positive value will enable caching
# use the same value as the number of modules that use kapt
kapt.classloaders.cache.size=5

# disable for caching to work
kapt.include.compile.classpath=false

# specify annotation processors' full names to disable caching for them
kapt.classloaders.cache.disableForProcessors=[annotation processors full names]

Kapt Annotation Processing performance report:
com.example.processor.TestingProcessor: total: 133 ms, init: 36 ms, 2 round(s): 97 ms, 0 ms
com.example.processor.AnotherProcessor: total: 100 ms, init: 6 ms, 1 round(s): 93 ms

kotlinc -cp $MY_CLASSPATH \
-Xplugin=kotlin-annotation-processing-SNAPSHOT.jar -P \
plugin:org.jetbrains.kotlin.kapt3:aptMode=stubsAndApt,\
plugin:org.jetbrains.kotlin.kapt3:apclasspath=processor/build/libs/processor.jar,\
plugin:org.jetbrains.kotlin.kapt3:dumpProcessorTimings=ap-perf-report.file \
-Xplugin=$JAVA_HOME/lib/tools.jar \
-d cli-tests/out \
-no-jdk -no-reflect -no-stdlib -verbose \
sample/src/main/

[INFO] Annotation processor stats:
[INFO] org.mapstruct.ap.MappingProcessor: total: 290 ms, init: 1 ms, 3 round(s): 289 ms, 0 ms, 0 ms
[INFO] Generated files report:
[INFO] org.mapstruct.ap.MappingProcessor: total sources: 2, sources per round: 2, 0, 0

Избежание компиляции для kapt

Для повышения скорости инкрементных сборках с kapt, можно использовать Gradle избежание компиляции. При включённом избежании компиляции, Gradle может пропустить обработку аннотаций при пересобирании проекта. В частности, обработка аннотаций пропускается, когда:

• Исходные файлы проекта не изменены.

• Изменения в зависимостях совместимы по ABI. Например, единственные изменения — в телах методов.

Однако, избежание компиляции не может использоваться для обработчиков аннотаций, обнаруженных в пути компиляции, так как любые изменения в них требуют выполнения задач обработки аннотаций.

Для запуска kapt с избежанием компиляции:

• Добавьте зависимости обработчиков аннотаций в kapt* конфигурации вручную, как описано выше.

• Отключите обнаружение обработчиков аннотаций в пути компиляции, добавив эту строку в свой gradle.properties файл:

kapt.include.compile.classpath=false

Инкрементная обработка аннотаций

kapt поддерживает инкрементную обработку аннотаций, которая включена по умолчанию. В настоящее время обработка аннотаций может быть инкрементной только если все используемые обработчики аннотаций являются инкрементными.

Чтобы отключить инкрементную обработку аннотаций, добавьте эту строку в свой gradle.properties файл:

kapt.incremental.apt=false

Обратите внимание, что инкрементная обработка аннотаций требует, чтобы инкрементная компиляция также была включена.

Параметры Java-компилятора

kapt использует Java-компилятор для запуска обработчиков аннотаций.
Вот как вы можете передать произвольные параметры в javac:

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

Коррекция несуществующего типа

Некоторые обработчики аннотаций (например, AutoFactory) полагаются на точные типы в сигнатурах объявлений. По умолчанию kapt заменяет каждый неизвестный тип (включая типы сгенерированных классов) на NonExistentClass, но вы можете изменить это поведение. Добавьте параметр в build.gradle файл, чтобы включить вывод ошибок при определении типов в вызовах:

kapt {
    correctErrorTypes = true
}

Использование в Maven

Добавьте выполнение цели kapt от плагина kotlin-maven-plugin перед compile:

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal>
    </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>

Обратите внимание, что kapt всё ещё не поддерживается собственной системой сборки IntelliJ IDEA. Запускайте сборку из инструментальной панели «Maven Projects», когда необходимо повторно выполнить обработку аннотаций.

Использование в CLI

Плагин компилятора kapt доступен в двоичном распространении компилятора Kotlin.

Вы можете подключить плагин, указав путь к его JAR-файлу, используя опцию Xplugin kotlinc:

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

Вот список доступных опций:

• sources (обязательно): Путь вывода для сгенерированных файлов.

• classes (обязательно): Путь вывода для сгенерированных файлов классов и ресурсов.

• stubs (обязательно): Путь вывода для файлов-заглушек. Другими словами, временная директория.

• incrementalData: Путь вывода для двоичных заглушек.

• apclasspath (повторяется): Путь к JAR-файлу обработчика аннотаций. Передайте столько опций apclasspath, сколько у вас JAR-файлов.

• apoptions: Список обработчиков аннотаций в формате base64. Смотрите AP/javac параметры кодирования для получения дополнительной информации.

• javacArguments: Список параметров, передаваемых в javac, в формате base64. Смотрите AP/javac параметры кодирования для получения дополнительной информации.

• processors: Запятая, отделённый список квалифицированных имён классов обработчиков аннотаций. Если указано, kapt не пытается найти обработчики аннотаций в apclasspath.

• verbose: Включить подробный вывод.

• aptMode (обязательно)

  • stubs — генерировать только необходимые для обработки аннотаций заглушки;

  • apt — выполнить только обработку аннотаций;

  • stubsAndApt — сгенерировать заглушки и выполнить обработку аннотаций.

• correctErrorTypes: Смотрите ниже. Отключено по умолчанию.

Формат опций плагина: -P plugin:<plugin id>:<key>=<value>. Опции могут быть повторены.

Пример:

-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

Генерация Kotlin-источников

kapt может генерировать Kotlin-источники. Просто запишите сгенерированные Kotlin-файлы в директорию, указанную в processingEnv.options["kapt.kotlin.generated"], и эти файлы будут скомпилированы вместе с основными источниками.

Обратите внимание, что kapt не поддерживает несколько раундов для сгенерированных Kotlin-файлов.

AP/Javac кодирование параметров

apoptions и javacArguments опции CLI принимают закодированную карту параметров.
Вот как вы можете закодировать параметры самостоятельно:

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())
}

Сохранение обработчиков аннотаций Java-компилятора

По умолчанию, kapt запускает все обработчики аннотаций и отключает обработку аннотаций в javac. Однако, вам может потребоваться, чтобы некоторые обработчики аннотаций javac работали (например, Lombok).

В файле сборки Gradle используйте параметр keepJavacAnnotationProcessors:

kapt {
    keepJavacAnnotationProcessors = true
}

Если вы используете Maven, вам необходимо указать конкретные настройки плагина. Посмотрите этот пример настроек плагина компилятора Lombok.