KSPクイックスタート

クイックスタートとして、独自のプロセッサを作成するか、サンプルを入手できます。

プロセッサの追加

プロセッサを追加するには、KSP Gradleプラグインを含め、プロセッサへの依存関係を追加する必要があります。

1. KSP Gradleプラグイン com.google.devtools.ksp を build.gradle(.kts) ファイルに追加します。

   plugins {
       id("com.google.devtools.ksp") version "2.1.21-2.0.1"
   }

   plugins {
       id 'com.google.devtools.ksp' version '2.1.21-2.0.1'
   }

:::

2. プロセッサへの依存関係を追加します。 この例ではDaggerを使用しています。追加したいプロセッサに置き換えてください。

   dependencies {
       implementation("com.google.dagger:dagger-compiler:2.51.1")
       ksp("com.google.dagger:dagger-compiler:2.51.1")
   }

   dependencies {
       implementation 'com.google.dagger:dagger-compiler:2.51.1'
       ksp 'com.google.dagger:dagger-compiler:2.51.1'
   }

:::

3. ./gradlew build を実行します。生成されたコードは build/generated/ksp ディレクトリで見つけることができます。

完全な例を以下に示します。

Kotlin

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

repositories {
    mavenCentral()
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation("com.google.dagger:dagger-compiler:2.51.1")
    ksp("com.google.dagger:dagger-compiler:2.51.1")
}

Groovy

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

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:2.1.21'
    implementation 'com.google.dagger:dagger-compiler:2.51.1'
    ksp 'com.google.dagger:dagger-compiler:2.51.1'
}

独自のプロセッサを作成する

1. 空のGradleプロジェクトを作成します。

2. ルートプロジェクトで、他のプロジェクトモジュールで使用するために、Kotlinプラグインのバージョン 2.1.21 を指定します。

   plugins {
       kotlin("jvm") version "2.1.21" apply false
   }
   
   buildscript {
       dependencies {
           classpath(kotlin("gradle-plugin", version = "2.1.21"))
       }
   }

   plugins {
       id 'org.jetbrains.kotlin.jvm' version '2.1.21' apply false
   }
   
   buildscript {
       dependencies {
           classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21'
       }
   }

:::

3. プロセッサをホストするためのモジュールを追加します。

4. モジュールのビルドスクリプトで、Kotlinプラグインを適用し、KSP APIを dependencies ブロックに追加します。

   plugins {
       kotlin("jvm")
   }
   
   repositories {
       mavenCentral()
   }
   
   dependencies {
       implementation("com.google.devtools.ksp:symbol-processing-api:2.1.21-2.0.1")
   }

   plugins {
       id 'org.jetbrains.kotlin.jvm' version '2.1.21'
   }
   
   repositories {
       mavenCentral()
   }
   
   dependencies {
       implementation 'com.google.devtools.ksp:symbol-processing-api:2.1.21-2.0.1'
   }

:::

5. com.google.devtools.ksp.processing.SymbolProcessor と com.google.devtools.ksp.processing.SymbolProcessorProvider を実装する必要があります。 SymbolProcessorProvider の実装は、実装した SymbolProcessor をインスタンス化するためのサービスとしてロードされます。 以下に注意してください：
   • SymbolProcessor を作成するには、SymbolProcessorProvider.create() を実装します。プロセッサが必要とする依存関係（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
   • 独自のプロセッサを記述した後、そのプロセッサプロバイダの完全修飾名を src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider に含めることで パッケージに登録します。

プロジェクトで独自のプロセッサを使用する

1. プロセッサを試したいワークロードを含む別のモジュールを作成します。

   pluginManagement { 
       repositories { 
           gradlePluginPortal()
       }
   }

   pluginManagement {
       repositories {
           gradlePluginPortal()
       }
   }
    ```
:::

2. モジュールのビルドスクリプトで、`com.google.devtools.ksp` プラグインを指定したバージョンで適用し、
   プロセッサを依存関係のリストに追加します。

   ::: code-group
```kotlin [Kotlin]
   plugins {
       id("com.google.devtools.ksp") version "2.1.21-2.0.1"
   }
   
   dependencies {
       implementation(kotlin("stdlib-jdk8"))
       implementation(project(":test-processor"))
       ksp(project(":test-processor"))
   }

   plugins {
       id 'com.google.devtools.ksp' version '2.1.21-2.0.1'
   }
   
   dependencies {
       implementation 'org.jetbrains.kotlin:kotlin-stdlib:2.1.21'
       implementation project(':test-processor')
       ksp project(':test-processor')
   }

:::

3. ./gradlew build を実行します。生成されたコードは build/generated/ksp の下にあります。

ワークロードにKSPプラグインを適用するサンプルビルドスクリプトは以下の通りです。

Kotlin

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

repositories {
    mavenCentral()
}

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

Groovy

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

repositories {
    mavenCentral()
}

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

プロセッサへのオプションの受け渡し

SymbolProcessorEnvironment.options のプロセッサオプションは、Gradleビルドスクリプトで指定されます。

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

IDEに生成されたコードを認識させる

NOTE

生成されたソースファイルはKSP 1.8.0-1.0.9以降、自動的に登録されます。

KSP 1.0.9以降を使用しており、生成されたリソースをIDEに認識させる必要がない場合は、

このセクションをスキップしても問題ありません。

デフォルトでは、IntelliJ IDEAやその他のIDEは生成されたコードについて認識しません。そのため、生成されたシンボルへの参照を解決できないものとしてマークします。IDEが生成されたシンボルを推論できるようにするには、以下のパスを生成されたソースルートとしてマークします。

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

IDEがリソースディレクトリをサポートしている場合は、以下のディレクトリもマークしてください。

build/generated/ksp/main/resources/

これらのディレクトリをKSPコンシューマーモジュールのビルドスクリプトで設定する必要がある場合もあります。

Kotlin

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

Groovy

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

IntelliJ IDEAとGradleプラグインでKSPを使用している場合、上記のコードスニペットは以下の警告を表示します。

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.

この場合、代わりに以下のスクリプトを使用してください。

Kotlin

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

Groovy

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