Kotlin Academy · Урок

Интеграция процессоров KSP в сборку Gradle

Настройте KSP в Gradle, добавьте сгенерированные исходники и отладьте вывод процессора.

«Интеграция процессоров KSP в сборку Gradle» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Структура из нескольких модулей

Типичная настройка KSP включает как минимум два модуля: :annotation (содержит классы аннотаций) и :processor (содержит SymbolProcessor). Модуль-потребитель подключает плагин KSP и объявляет зависимости ksp и implementation.

Применение плагина KSP

В модуле-потребителе build.gradle.kts:

plugins {
    kotlin("jvm")  // or android, multiplatform
    id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

Объявление зависимости ksp

Используйте конфигурацию ksp (а не implementation), чтобы добавить процессор KSP. Процессор выполняется только во время сборки и не включается в итоговый артефакт:

dependencies {
    implementation(project(":annotation"))
    ksp(project(":processor"))
}

Каталоги сгенерированного исходного кода

KSP записывает сгенерированные файлы в build/generated/ksp/<sourceSet>/kotlin/. Плагин KSP автоматически добавляет эти каталоги в набор исходного кода Kotlin, поэтому сгенерированные классы видны вашему коду без ручной настройки.

Передача параметров процессору

Передавайте параметры сборки из Gradle процессору через ksp { arg("key", "value") }. Считывайте их в процессоре через environment.options["key"]:

// build.gradle.kts (consumer)
ksp {
    arg("generateMocks", "true")
    arg("outputPackage", "com.example.generated")
}

Чтение параметров в процессоре

В методе SymbolProcessorProvider.create() получайте параметры из окружения:

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
        val genMocks = environment.options["generateMocks"] == "true"
        return MyProcessor(environment.codeGenerator, environment.logger, genMocks)
    }
}

Инкрементальные сборки

KSP отслеживает зависимости между входными и выходными данными. Связывайте каждый сгенерированный файл с исходными символами при вызове codeGenerator.createNewFile(). После этого KSP пропускает повторную обработку, если ни один из отслеживаемых входных элементов не изменился.

val deps = Dependencies(aggregating = false, *symbols.map { it.containingFile!! }.toTypedArray())
codeGenerator.createNewFile(deps, packageName, fileName)

KSP для Android

В проектах Android замените kapt на ksp и в объявлении плагина, и в объявлении зависимостей. Используйте конфигурации с учетом варианта сборки, например kspDebug или kspRelease, если поведение процессора должно различаться для разных типов сборки.

KSP для Kotlin Multiplatform

В проекте KMP примените плагин KSP и используйте add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) или сокращенные варианты kspCommonMainMetadata, kspJvmMain и т. д. — в зависимости от того, какие цели поддерживает ваш процессор.

Просмотр сгенерированных файлов

После запуска ./gradlew build (или kspKotlin / kspDebugKotlin для Android) просмотрите содержимое build/generated/ksp/. IntelliJ и Android Studio помечают эти папки как каталоги сгенерированного исходного кода и позволяют переходить от мест использования к сгенерированным объявлениям.

Отладка процессора

Запустите задачу Gradle с параметром --debug или добавьте jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") в конфигурацию ksp, чтобы подключить удаленный отладчик к JVM обработки аннотаций.

Быстрая проверка

Какая конфигурация Gradle используется для добавления процессора KSP, который выполняется во время сборки, но не включается в путь к классам времени выполнения?

Повторение: интеграция KSP в сборку Gradle

Ключевые выводы:

Подключите плагин com.google.devtools.ksp; добавьте процессор с помощью зависимости ksp()
Сгенерированный исходный код помещается в build/generated/ksp/ и автоматически добавляется в набор исходного кода
Передавайте параметры из Gradle через ksp { arg() }; считывайте их через environment.options
Используйте Dependencies вместе с createNewFile() для точных инкрементальных пересборок
Поддерживаются Android (конфигурации вариантов) и Kotlin Multiplatform

Часто задаваемые вопросы

Урок «Интеграция процессоров KSP в сборку Gradle» бесплатный?

Да — полный текст урока «Интеграция процессоров KSP в сборку Gradle» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Интеграция процессоров KSP в сборку Gradle»?

Настройте KSP в Gradle, добавьте сгенерированные исходники и отладьте вывод процессора. Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Интеграция процессоров KSP в сборку Gradle»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

KSP и KAPT: почему KSP быстрее
Написание первого SymbolProcessor
Генерация исходных файлов Kotlin с KotlinPoet
Интеграция процессоров KSP в сборку Gradle

← Назад к Kotlin Academy