Плагин компилятора kapt

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

Следуйте этим шагам:

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

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

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

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

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

   dependencies {
       kapt 'groupId:artifactId:version'
   }
   

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

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

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

Используйте блок 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(.kts) для включения вывода типа ошибки в вызовах:

kapt {
    correctErrorTypes = true
}

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

Добавьте выполнение цели kapt плагина kotlin-maven-plugin перед 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>

Для настройки уровня обработки аннотаций установите одно из следующих значений как aptMode в блоке <configuration>:

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

• apt — выполняется только обработка аннотаций.

• stubsAndApt — (по умолчанию) генерируются вызовы и выполняется обработка аннотаций.

Например:

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

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

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 options encoding.

• javacArguments: Список параметров, передаваемых javac в формате base64. Подробнее см. AP/javac options encoding.

• 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.