Обработка аннотаций с Kotlin

Обработчики аннотаций (см. JSR 269) поддерживаются в Kotlin с помощью плагина компилятора kapt.

Короче говоря, вы можете использовать библиотеки, такие как Dagger или Data Binding в ваших проектах на Kotlin.

Ниже вы можете прочитать о том, как применить плагин kapt к вашему билду Gradle/Maven.

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

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

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

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

В качестве альтернативы, вы можете использовать синтаксис 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 (с версии 1.2.20)

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

kapt {
    useBuildCache = false
}

Выполнение задач kapt параллельно (с версии 1.2.60)

Для повышения скорости билдов, использующих kapt, можно включить API рабочей области Gradle для задач kapt. Использование API рабочей области позволяет Gradle запускать независимые задачи обработки аннотаций из одного проекта параллельно, что в некоторых случаях значительно уменьшает время выполнения. Однако запуск kapt с включенным API рабочей области Gradle может привести к увеличению потребления памяти из-за параллельного выполнения.

Для использования API рабочей области Gradle для параллельного выполнения задач kapt добавьте эту строку в свой файл gradle.properties:

kapt.use.worker.api=true

Избегание компиляции для kapt (с версии 1.3.20)

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

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

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

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

• Добавьте зависимости обработчика аннотаций в конфигурации kapt* вручную, как описано выше.
• Отключите обнаружение обработчиков аннотаций в пути компиляции, добавив эту строку в свой файл gradle.properties:

kapt.include.compile.classpath=false

Инкрементная обработка аннотаций (с версии 1.3.30)

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

Инкрементная обработка аннотаций включена по умолчанию, начиная с версии 1.3.50. Чтобы отключить инкрементную обработку аннотаций, добавьте эту строку в свой файл 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>

Вы можете найти полный пример проекта, демонстрирующий использование Kotlin, Maven и Dagger в репозитории примеров Kotlin Kotlin examples repository.

Обратите внимание, что 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"], и эти файлы будут скомпилированы вместе с основными источниками.

Вы можете найти полный пример в репозитории kotlin-examples Github kotlin-examples.

Обратите внимание, что 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())
}