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

Gradle

Чтобы использовать kapt в Gradle, выполните следующие действия:

1. Примените плагин Gradle kapt в файле сценария сборки build.gradle(.kts):

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

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

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, и она будет доступна как для исходного кода приложения, так и для тестов.

Maven

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

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <extensions>true</extensions>
    <configuration>
        <annotationProcessorPaths>
            <!-- Specify your annotation processors here -->
            <annotationProcessorPath>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</plugin>

<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>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

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

CLI

kapt доступен как автономный инструмент CLI в бинарном дистрибутиве компилятора Kotlin.

Чтобы запустить kapt из командной строки, используйте:

kapt <options> <source files>

Например:

kapt -Kapt-mode=stubsAndApt \
  -Kapt-sources=build/kapt/sources \
  -Kapt-classes=build/kapt/classes \
  -Kapt-stubs=build/kapt/stubs \
  -Kapt-classpath=lib/ap.jar \
  -Kapt-classpath=lib/anotherAp.jar \
  src/main/kotlin

• См. полный список параметров компилятора, относящихся к kapt.

• Также можно передать все допустимые параметры компилятора Kotlin. Выполните kotlinc -help, чтобы просмотреть их.

Настройка пути к классам и обнаружения процессоров

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

# gradle.properties
kapt.include.compile.classpath=false

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal>
    </goals>
    <configuration>
        <includeCompileClasspath>false</includeCompileClasspath>
        <sourceDirs>...</sourceDirs>
        <annotationProcessorPaths>...</annotationProcessorPaths>
    </configuration>
</execution>

<properties>
    <kapt.include.compile.classpath>false</kapt.include.compile.classpath>
</properties>

[WARNING] Annotation processors discovery from compile classpath is deprecated.
Set 'kapt.include.compile.classpath=false' to disable discovery.

Наследование процессоров аннотаций из суперкoнфигураций

Можно определить общий набор процессоров аннотаций в отдельной конфигурации Gradle в качестве суперкoнфигурации, а затем расширить ее в конфигурациях kapt для подпроектов.

Например, для подпроекта, использующего MapStruct, добавьте следующую конфигурацию в файл build.gradle(.kts):

val commonAnnotationProcessors by configurations.creating
configurations.named("kapt") { extendsFrom(commonAnnotationProcessors) }

dependencies {
    implementation("org.mapstruct:mapstruct:1.6.3")
    commonAnnotationProcessors("org.mapstruct:mapstruct-processor:1.6.3")
}

В этом примере конфигурация Gradle commonAnnotationProcessors — общая суперкoнфигурация для обработки аннотаций, которую нужно использовать во всех проектах. С помощью метода extendsFrom() конфигурация commonAnnotationProcessors добавляется в качестве суперкoнфигурации. kapt видит, что конфигурация Gradle commonAnnotationProcessors зависит от процессора аннотаций MapStruct. Поэтому kapt включает процессор аннотаций MapStruct в конфигурацию обработки аннотаций.

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

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

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

kapt {
    keepJavacAnnotationProcessors = true
}

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

Параллельный запуск задач kapt

kapt использует Worker API Gradle для выполнения задач обработки аннотаций. Worker API позволяет Gradle параллельно выполнять независимые задачи обработки аннотаций в рамках одного проекта, что в некоторых случаях значительно сокращает время выполнения.

Если в плагине Kotlin Gradle задана пользовательская версия JDK, рабочие процессы задач kapt используют только режим processIsolation().

Если нужно указать дополнительные аргументы JVM для рабочего процесса kapt, используйте входной параметр kaptProcessJvmArgs задачи KaptWithoutKotlincTask:

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

Безопасное использование кэша сборки Gradle

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

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

kapt {
    useBuildCache = false
}

Кэширование загрузчиков классов процессоров аннотаций

Кэширование загрузчиков классов процессоров аннотаций помогает ускорить работу kapt, если вы запускаете несколько задач Gradle подряд.

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

# gradle.properties
#
# Any positive value enables 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]

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

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

В настоящее время инкрементальная обработка аннотаций работает только в том случае, если:

• Инкрементальная компиляция включена.

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

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

kapt.incremental.apt=false

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

Чтобы получить статистику производительности выполнения процессоров аннотаций, используйте параметр showProcessorStats. Пример вывода:

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

Этот отчет можно сохранить в файл с помощью параметра dumpProcessorStats. Например, следующая команда CLI запускает kapt и сохраняет статистику в файл ap-perf-report.file:

kapt -Kapt-mode=stubsAndApt \
  -Kapt-classpath=processor/build/libs/processor.jar \
  -Kapt-dump-processor-stats=ap-perf-report.file \
  sample/src/main/

Отслеживание количества созданных файлов

Плагин kapt может выводить статистику о количестве файлов, созданных каждым процессором аннотаций.

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

Чтобы включить вывод статистики:

1. В файле сборки Gradle задайте для параметра showProcessorStats значение true:

   // build.gradle(.kts)
   kapt {
       showProcessorStats = true
   }
   

2. В файле gradle.properties задайте для параметра компилятора verbose значение true:

   # gradle.properties
   kapt.verbose=true
   

Статистика отображается в журналах с уровнем info. Сначала выводится строка Annotation processor stats:, за которой следует статистика времени выполнения каждого процессора аннотаций. Затем выводится строка Generated files report:, за которой следует статистика количества файлов, созданных каждым процессором аннотаций. Например:

[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

Настройка процессора аннотаций

                    
<aptMode>stubsAndApt</aptMode>
                    
                

                    dependencies {
                        kapt("com.example:processor:1.0")
                    }
                

                    
<annotationProcessorPaths>
    <annotationProcessorPath>...</annotationProcessorPath>
</annotationProcessorPaths>
                    
                

                    kapt {
                        annotationProcessor("com.example.MyProcessor")
                    }
                

                    
<annotationProcessors>
    <annotationProcessor>com.example.MyProcessor</annotationProcessor>
</annotationProcessors>
                    
                

                    kapt {
                        arguments {
                            arg("room.schemaLocation", "$projectDir/schemas")
                        }
                    }
                

                    
<annotationProcessorArgs>
    <annotationProcessorArg>room.schemaLocation=/schemas</annotationProcessorArg>
</annotationProcessorArgs>
                    
                

                    kapt {
                        javacOptions {
                            option("-source", "11")
                        }
                    }
                

                    
<javacOptions>
    <javacOption>-source=11</javacOption>
</javacOptions>
                    
                

                    # gradle.properties
                    kapt.incremental.apt=true
                

Параметры выходных каталогов

Параметры поведения

                    kapt {
                        correctErrorTypes = true
                    }
                

                    
<correctErrorTypes>true</correctErrorTypes>
                    
                

                    kapt {
                        dumpDefaultParameterValues = true
                    }
                

                    kapt {
                        mapDiagnosticLocations = true
                    }
                

                    
<mapDiagnosticLocations>true</mapDiagnosticLocations>
                    
                

                    kapt {
                        strictMode = true
                    }
                

                    kapt {
                        stripMetadata = true
                    }
                

                    # gradle.properties
                    kapt.verbose=true
                

                    kapt {
                        includeCompileClasspath = false
                    }
                

                    
<includeCompileClasspath>false</includeCompileClasspath>
                    
                

Параметры диагностики и статистики

                    kapt {
                        showProcessorStats = true
                    }
                

                    kapt {
                        detectMemoryLeaks = "paranoid"
                    }