メインコンテンツまでスキップ

KSP クイックスタート

手早く始めるには、独自のプロセッサを作成するか、サンプルを入手できます。

プロセッサの追加​

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

  1. KSP Gradle Plugin com.google.devtools.kspをbuild.gradle(.kts)ファイルに追加します。
plugins {
    id("com.google.devtools.ksp") version "2.1.10-1.0.31"
}
  1. プロセッサへの依存関係を追加します。 この例ではDaggerを使用します。追加するプロセッサに置き換えてください。
dependencies {
    implementation("com.google.dagger:dagger-compiler:2.51.1")
    ksp("com.google.dagger:dagger-compiler:2.51.1")
}
  1. ./gradlew buildを実行します。生成されたコードはbuild/generated/kspディレクトリにあります。

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

plugins {
    id("com.google.devtools.ksp") version "2.1.10-1.0.31"
    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")
}

独自のプロセッサの作成​

  1. 空のgradleプロジェクトを作成します。
  2. 他のプロジェクトモジュールで使用するために、ルートプロジェクトでKotlinプラグインのバージョン2.1.10を指定します。
plugins {
    kotlin("jvm") version "2.1.10" apply false
}

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

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

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

plugins {
    kotlin("jvm")
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.google.devtools.ksp:symbol-processing-api:2.1.10-1.0.31")
}
  1. 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の一般的なユースケースは、シンボルを操作するためのカスタマイズされたvisitor（インターフェースcom.google.devtools.ksp.symbol.KSVisitor）を実装することです。シンプルなテンプレートvisitorは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()
    }
}
  1. モジュールのビルドスクリプトで、指定されたバージョンのcom.google.devtools.kspプラグインを適用し、 プロセッサを依存関係のリストに追加します。
plugins {
    id("com.google.devtools.ksp") version "2.1.10-1.0.31"
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation(project(":test-processor"))
    ksp(project(":test-processor"))
}
  1. ./gradlew buildを実行します。生成されたコードはbuild/generated/kspにあります。

以下に、KSPプラグインをワークロードに適用するサンプルビルドスクリプトを示します。

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

repositories {
    mavenCentral()
}

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

プロセッサにオプションを渡す​

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

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

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

注記

生成されたソースファイルは、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 {
    sourceSets.main {
        kotlin.srcDir("build/generated/ksp/main/kotlin")
    }
    sourceSets.test {
        kotlin.srcDir("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.

この場合は、代わりに次のスクリプトを使用します。

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