Быстрый старт KSP

Создание собственного процессора

1. Создайте пустой проект Gradle.

2. Укажите версию 1.9.0 плагина Kotlin в корневом проекте для использования в других модулях проекта:

plugins {
    kotlin("jvm") version "1.9.0" apply false
}

buildscript {
    dependencies {
        classpath(kotlin("gradle-plugin", version = "1.9.0"))
    }
}

plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.9.0' apply false
}

buildscript {
    dependencies {
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0'
    }
}

3. Добавьте модуль для размещения процессора.

4. В файле конфигурации модуля примените плагин Kotlin и добавьте API KSP в блок dependencies.

plugins {
    kotlin("jvm")
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.google.devtools.ksp:symbol-processing-api:1.9.0-1.0.11")
}

plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.9.0'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.google.devtools.ksp:symbol-processing-api:1.9.0-1.0.11'
}

5. Вам нужно будет реализовать com.google.devtools.ksp.processing.SymbolProcessor и com.google.devtools.ksp.processing.SymbolProcessorProvider. Ваша реализация SymbolProcessorProvider будет загружена как служба для создания экземпляра SymbolProcessor, которую вы реализуете. Обратите внимание на следующее:

   • Реализуйте SymbolProcessorProvider.create(), чтобы создать SymbolProcessor. Передавайте зависимости, необходимые вашему процессору (например, CodeGenerator, параметры процессора) через параметры SymbolProcessorProvider.create().

   • Основная логика должна находиться в методе SymbolProcessor.process().

   • Используйте resolver.getSymbolsWithAnnotation() для получения символов, которые вы хотите обработать, зная полное имя аннотации.

   • Общее применение KSP заключается в реализации настраиваемого посетителя (интерфейс com.google.devtools.ksp.symbol.KSVisitor) для работы с символами. Простой шаблонный посетитель — это com.google.devtools.ksp.symbol.KSDefaultVisitor.

   • Примеры реализации интерфейсов SymbolProcessorProvider и SymbolProcessor см. в следующих файлах образцового проекта.

     • src/main/kotlin/BuilderProcessor.kt

     • src/main/kotlin/TestProcessor.kt

   • После написания собственного процессора зарегистрируйте ваш поставщик процессора в пакете, включив его полное имя в resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider.

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

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

pluginManagement { 
    repositories { 
        gradlePluginPortal()
    }
}

pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

2. В файле конфигурации модуля примените плагин com.google.devtools.ksp с указанной версией и добавьте свой процессор в список зависимостей.

plugins {
    id("com.google.devtools.ksp") version "1.9.0-1.0.11"
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation(project(":test-processor"))
    ksp(project(":test-processor"))
}

plugins {
    id 'com.google.devtools.ksp' version '1.9.0-1.0.11'
}

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version'
    implementation project(':test-processor')
    ksp project(':test-processor')
}

3. Запустите ./gradlew build. Сгенерированный код можно найти по адресу build/generated/source/ksp.

Вот пример файла конфигурации, применяющего плагин KSP к рабочей нагрузке:

plugins {
    id("com.google.devtools.ksp") version "1.9.0-1.0.11"
    kotlin("jvm") 
}

repositories {
    mavenCentral()
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation(project(":test-processor"))
    ksp(project(":test-processor"))
}

plugins {
    id 'com.google.devtools.ksp' version '1.9.0-1.0.11'
    id 'org.jetbrains.kotlin.jvm' version '1.9.0'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.9.0'
    implementation project(':test-processor')
    ksp project(':test-processor')
}

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

Параметры процессора в SymbolProcessorEnvironment.options задаются в файлах конфигурации Gradle:

ksp {
    arg("option1", "value1")
    arg("option2", "value2")
    ...
}

Информирование IDE о сгенерированном коде

По умолчанию IntelliJ IDEA или другие IDE не знают о сгенерированном коде. Поэтому ссылки на сгенерированные символы будут помечены как неразрешимые. Чтобы IDE могла работать с сгенерированными символами, пометьте следующие пути как корни исходных файлов сгенерированного кода:

build/generated/ksp/main/kotlin/
build/generated/ksp/main/java/

Если ваша IDE поддерживает каталоги ресурсов, также пометьте следующие:

build/generated/ksp/main/resources/

Возможно, также потребуется настроить эти каталоги в файле конфигурации модуля-потребителя KSP:

kotlin {
    sourceSets.main {
        kotlin.srcDir("build/generated/ksp/main/kotlin")
    }
    sourceSets.test {
        kotlin.srcDir("build/generated/ksp/test/kotlin")
    }
}

kotlin {
    sourceSets {
        main.kotlin.srcDirs += 'build/generated/ksp/main/kotlin'
        test.kotlin.srcDirs += 'build/generated/ksp/test/kotlin'
    }
}

Если вы используете IntelliJ IDEA и KSP в плагине Gradle, то приведенный выше фрагмент выведет следующее предупреждение:

Execution optimizations have been disabled for task ':publishPluginJar' to ensure correctness due to the following reasons:
Gradle detected a problem with the following location: '../build/generated/ksp/main/kotlin'. 
Reason: Task ':publishPluginJar' uses this output of task ':kspKotlin' without declaring an explicit or implicit dependency.

В этом случае используйте следующий скрипт:

plugins {
    // ...
    idea
}

idea {
    module {
        // Not using += due to https://github.com/gradle/gradle/issues/8749
        sourceDirs = sourceDirs + file("build/generated/ksp/main/kotlin") // or tasks["kspKotlin"].destination
        testSourceDirs = testSourceDirs + file("build/generated/ksp/test/kotlin")
        generatedSourceDirs = generatedSourceDirs + file("build/generated/ksp/main/kotlin") + file("build/generated/ksp/test/kotlin")
    }
}

plugins {
    // ...
    id 'idea'
}

idea {
    module {
        // Not using += due to https://github.com/gradle/gradle/issues/8749
        sourceDirs = sourceDirs + file('build/generated/ksp/main/kotlin') // or tasks["kspKotlin"].destination
        testSourceDirs = testSourceDirs + file('build/generated/ksp/test/kotlin')
        generatedSourceDirs = generatedSourceDirs + file('build/generated/ksp/main/kotlin') + file('build/generated/ksp/test/kotlin')
    }
}