KSP 入門
このガイドでは、以下の内容について説明します。
- プロジェクトに KSP ベースのアノテーションプロセッサを追加する方法。
- KSP API を使用して独自のアノテーションプロセッサを作成する方法。
- プロセッサによって生成されたコードの確認場所。
プロジェクトに KSP ベースのプロセッサを追加する
プロジェクトで外部プロセッサを使用するには、build.gradle(.kts) ファイルの plugins {} ブロック に KSP を追加します。プロセッサが特定のモジュールでのみ必要な場合は、代わりにそのモジュールの build.gradle(.kts) ファイルに追加します。
// build.gradle.kts
plugins {
kotlin("jvm") version "2.4.21"
id("com.google.devtools.ksp") version "2.3.12"
}// build.gradle
plugins {
id 'org.jetbrains.kotlin.jvm' version '2.4.21'
id 'com.google.devtools.ksp' version '2.3.12'
}KSP の最新バージョンについては、GitHub の Releases を確認してください。
トップレベルの dependencies {} ブロックで、使用したいプロセッサを追加します。この例では Moshi を使用していますが、他のプロセッサでも同様の手順となります。
// build.gradle.kts
dependencies {
ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.2")
}// build.gradle
dependencies {
ksp 'com.squareup.moshi:moshi-kotlin-codegen:1.15.2'
}ksp(...) 設定は、アプリケーションのソースにのみプロセッサを適用します。テストソースを処理するには、kspTest(...) 設定でプロセッサを追加してください。
ksp(...) 設定はシングルプラットフォームプロジェクトでのみ利用可能です。 個々の Kotlin Multiplatform ターゲットおよびコンパイルに対してプロセッサを設定する方法については、Kotlin Multiplatform での KSP を参照してください。
独自のプロセッサを作成する
以下の手順に従って、helloWorld() 関数を生成するシンプルなアノテーションプロセッサを作成します。実際にはあまり実用的ではありませんが、独自のプロセッサやアノテーションを作成する基本を学ぶことができます。
プロジェクトに KSP を追加する
新しい Kotlin プロジェクトを作成し、KSP プラグインを追加します。
IntelliJ IDEA で、File | New | Project を選択します。
左側のリストで Kotlin を選択します。
ビルドシステムとして Gradle を選択し、Create をクリックします。

build.gradle(.kts)ファイルに KSP プラグインを追加します。kotlin// build.gradle.kts plugins { kotlin("jvm") version "2.4.21" id("com.google.devtools.ksp") version "2.3.12" apply false }groovy// build.gradle plugins { id 'org.jetbrains.kotlin.jvm' version '2.4.21' id 'com.google.devtools.ksp' version '2.3.12' apply false }
アノテーションを作成する
プロジェクトのルートに新しいモジュールを作成し、アノテーションを宣言します。
File | New | Module を選択します。
左側のリストで Kotlin を選択します。
以下の項目を指定し、Create をクリックします。
- Name: annotations
- Build system: Gradle

モジュール内に
HelloWorldAnnotation.ktファイルを作成し、HelloWorldAnnotationという名前のアノテーションを宣言します。kotlin// annotations/src/main/kotlin/com/example/annotations/HelloWorldAnnotation.kt package com.example.annotations annotation class HelloWorldAnnotation
プロセッサを作成して登録する
プロジェクトのルートに processor という名前の別のモジュールを作成します。
モジュールの
build.gradle(.kts)ファイルに、KSP API と先ほど宣言したアノテーションを依存関係として追加します。kotlin// processor/build.gradle.kts plugins { kotlin("jvm") } dependencies { implementation(project(":annotations")) implementation("com.google.devtools.ksp:symbol-processing-api:2.3.6") }groovy// processor/build.gradle plugins { id 'org.jetbrains.kotlin.jvm' } dependencies { implementation project ':annotations' implementation 'com.google.devtools.ksp:symbol-processing-api:2.3.6' }processor モジュール内に
HelloWorldProcessor.ktファイルを作成し、以下のコードを追加します。kotlin// processor/src/main/kotlin/HelloWorldProcessor.kt class HelloWorldProcessor(val codeGenerator: CodeGenerator) : SymbolProcessor { // 1️⃣ process() 関数 override fun process(resolver: Resolver): List<KSAnnotated> { resolver .getSymbolsWithAnnotation("com.example.annotations.HelloWorldAnnotation") .filter { it.validate() } .filterIsInstance<KSFunctionDeclaration>() .forEach { it.accept(HelloWorldVisitor(), Unit) } return emptyList() } // 2️⃣ Visitor inner class HelloWorldVisitor : KSVisitorVoid() { override fun visitFunctionDeclaration(function: KSFunctionDeclaration, data: Unit) { createNewFileFrom(function).use { file -> file.write( """ fun helloWorld(): Unit { println("Hello world from function generated by KSP") } """.trimIndent() ) } } } // 3️⃣ createNewFileFrom() 関数 private fun createNewFileFrom(function: KSFunctionDeclaration): OutputStream { return codeGenerator.createNewFile( dependencies = createDependencyOn(function), packageName = "", fileName = "GeneratedHelloWorld" ) } // 3️⃣ createDependencyOn() 関数 private fun createDependencyOn(function: KSFunctionDeclaration): Dependencies { return Dependencies(aggregating = false, function.containingFile!!) } } // 文字列を OutputStream に書き込むためのユーティリティ関数 fun OutputStream.write(string: String): Unit { this.write(string.toByteArray()) }IDE から提案されたインポートを追加します。
ResolverクラスとDependenciesクラスは必ずcom.google.devtools.ksp.processingからインポートしてください。または、以下の行をHelloWorldProcessor.ktの先頭にコピーしてください。インポート文 {...}
kotlin// processor/src/main/kotlin/HelloWorldProcessor.kt import com.google.devtools.ksp.processing.CodeGenerator import com.google.devtools.ksp.processing.Dependencies import com.google.devtools.ksp.processing.Resolver import com.google.devtools.ksp.processing.SymbolProcessor import com.google.devtools.ksp.symbol.KSAnnotated import com.google.devtools.ksp.symbol.KSFunctionDeclaration import com.google.devtools.ksp.symbol.KSVisitorVoid import com.google.devtools.ksp.validate import java.io.OutputStreamコードの内容を確認してみましょう。
1️⃣
process()関数には、プロセッサのメインロジックが含まれています。HelloWorldAnnotationでアノテーションされたすべてのシンボルを取得し、それぞれに対してHelloWorldVisitorを呼び出します。process()関数は、以降のラウンドで処理するための未処理シンボルのリストを返します。この例では、安全にemptyList()を返しています。詳細については、複数ラウンド処理 を参照してください。2️⃣ プロセッサは、ビジターを使用して KSP が提供する Kotlin の抽象構文木(AST)のビューを巡回します。
HelloWorldProcessorクラス内では、HelloWorldVisitorクラスがビジターとなります。HelloWorldAnnotationは関数に対してのみ使用されるため、visitFunctionDeclaration()のみがオーバーライドされています。KSVisitorVoidは、オーバーライドしてカスタマイズできる KSP 提供のビジタークラスの 1 つです。 また、KSVisitor<D, R>インターフェース を実装して独自のビジターを作成することもできます。3️⃣
createNewFileFrom()は、KSP がコードを生成するファイルを作成します。createDependencyOn()は、生成される出力ファイルをアノテーションが使用されているソースファイルに依存させます。KSP がファイルを作成・管理する方法の詳細については、
CodeGeneratorインターフェース のソースコードを参照してください。
HelloWorldProcessorProvider.ktファイルを作成します。その中で、SymbolProcessorProviderを継承するHelloWorldProcessorProviderクラスを宣言します。kotlin// processor/src/main/kotlin/HelloWorldProcessorProvider.kt import com.google.devtools.ksp.processing.SymbolProcessor import com.google.devtools.ksp.processing.SymbolProcessorEnvironment import com.google.devtools.ksp.processing.SymbolProcessorProvider class HelloWorldProcessorProvider : SymbolProcessorProvider { override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor { return HelloWorldProcessor(environment.codeGenerator) } }プロセッサプロバイダを登録します。
resources/META-INF/servicesディレクトリにcom.google.devtools.ksp.processing.SymbolProcessorProviderという名前のファイルを作成し、プロバイダの完全修飾名を追加します。text## processor/src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider HelloWorldProcessorProvider
プロセッサを使用する
これで、プロセッサをテストする準備が整いました。以下の手順に従ってクライアントモジュールを作成し、アノテーションが付与された要素に基づいてプロセッサにコードを生成させます。
プロジェクトのルートに
appというモジュールを作成します。そのモジュールの
build.gradle(.kts)ファイルで以下を行います。plugins {}ブロックに KSP プラグインを追加します。dependencies {}ブロックにプロセッサとアノテーションを追加します。
例:
kotlin// app/build.gradle.kts plugins { kotlin("jvm") id("com.google.devtools.ksp") } dependencies { implementation(project(":annotations")) ksp(project(":processor")) }groovy// app/build.gradle plugins { id 'com.google.devtools.ksp' } dependencies { implementation project (':annotations') ksp project (':processor') }プロジェクトレベルの
settings.gradle(.kts)ファイルで、すべてのサブモジュールが自動的にインクルードされていることを確認します。kotlin// settings.gradle.kts include("annotations") include("app") include("processor")groovy// settings.gradle include 'processor' include 'annotations' include 'app'appモジュール内にMain.ktファイルを作成し、以下のコードを追加します。kotlin// app/src/main/kotlin/Main.kt import com.example.annotations.HelloWorldAnnotation @HelloWorldAnnotation fun main() { helloWorld() }helloWorld()関数はまだ存在しないにもかかわらず、main()関数から呼び出されています。IDE ではhelloWorld()が未定義の参照としてハイライトされますが、これは想定通りの挙動です。プロジェクトをビルドして実行すると、KSP がhelloWorld()関数を生成します。プログラムを実行します。コンソールに
helloWorld()関数の出力が表示されます。textHello world from function generated by KSPKSP は
GeneratedHelloWorld.ktファイル内にコードを生成します。textapp/build/generated/ksp/main/kotlin/GeneratedHelloWorld.kt
プロジェクト構造を確認する
プロジェクトの最終的なファイル構造は以下のようになります。
プロジェクト構造 {...}
.
├── app
│ ├── build.gradle.kts
│ └── src
│ └── main
│ └── kotlin
│ └── Main.kt
├── annotations
│ ├── build.gradle.kts
│ └── src
│ └── main
│ └── kotlin
| └── com
| └── example
| └── annotations
| └── HelloWorldAnnotation.kt
├── processor
│ ├── build.gradle.kts
│ └── src
│ └── main
│ ├── kotlin
│ │ ├── HelloWorldProcessor.kt
│ │ └── HelloWorldProcessorProvider.kt
│ └── resources/META-INF/services
| └── com.google.devtools.ksp.processing.SymbolProcessorProvider
├── build.gradle.kts
└── settings.gradle.kts追加のファイルやディレクトリが存在する場合もあります。
次のステップ
- このサンプルの完全なコードは KSP リポジトリ で確認できます。
- より複雑で実践的なサンプルは KSP リポジトリ を参照してください。
- KSP 対応ライブラリ一覧 をご覧ください。
