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

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

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

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

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

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

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

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

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

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

plugins {
    kotlin("jvm")
}

repositories {
    mavenCentral()
}

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

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

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.google.devtools.ksp:symbol-processing-api:1.7.10-1.0.6'
}

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.7.10-1.0.6"
}

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

plugins {
    id 'com.google.devtools.ksp' version '1.7.10-1.0.6'
}

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.7.10-1.0.6"
    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.7.10-1.0.6'
    id 'org.jetbrains.kotlin.jvm' version '1.7.20'
}

repositories {
    mavenCentral()
}

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