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

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

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

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

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

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

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

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

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

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

plugins {
    kotlin("jvm")
}

repositories {
    mavenCentral()
}

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

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

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.google.devtools.ksp:symbol-processing-api:1.6.10-1.0.2'
}

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.6.10-1.0.2"
}

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

plugins {
    id 'com.google.devtools.ksp' version '1.6.10-1.0.2'
}

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.6.10-1.0.2"
    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.6.10-1.0.2'
    id 'org.jetbrains.kotlin.jvm' version '1.6.20'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.6.20'
    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')
   }
}