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

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

Выполните следующие действия:

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

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

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

   В качестве альтернативы, вы можете использовать синтаксис apply plugin:

   apply plugin: 'kotlin-kapt'
   

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

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, например, повторяемых аннотаций, включите поддержку бета-версии JVM-бекенда с помощью следующего параметра в вашем 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», когда необходимо повторно запустить обработку аннотаций.

Использование в командной строке

Плагин компилятора 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 параметры командной строки принимают закодированную карту параметров.
Вот как можно закодировать параметры самостоятельно:

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.