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

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

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

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

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

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

apply plugin: 'kotlin-kapt'

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

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

dependencies {
    kapt 'groupId:artifactId:version'
}

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

Если вы используете обработчики аннотаций для своих androidTest или test источников, соответствующие конфигурации kapt называются 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

Для повышения времени выполнения инкрементных сборок с 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.