Kotlin Symbol Processing API
Kotlin Symbol Processing(KSP)は、Kotlin向けのソースコード生成フレームワークです。KSP APIを使用すると、ソースコードに関する静的情報を検査し、それをもとに新しいコードを生成するプロセッサーを作成できます。最も一般的なユースケースは、アノテーションに基づいたコード生成です。
KSPは、軽量なコンパイラープラグインの作成を簡素化することを目的としています。KSPで構築されたコンパイラープラグインは、シンボルプロセッサー(symbol processor)、または略してプロセッサーと呼ばれます。KSPの明確に定義されたAPIがコンパイラーの内部変更を隠蔽するため、プロセッサーのメンテナンスに多くの労力を費やす必要がありません。ただし、このアプローチにはトレードオフもあります。例えば、KSPベースのプロセッサーは式や文を検査することはできず、ソースコード自体を変更することもできません。
KSPベースのプラグインの代表的なユースケースには、以下のようなものがあります。
最初のKSPベースのプロセッサーを作成する方法については、KSP入門を参照してください。
必要条件
最新のKSPバージョン(2.3.12)は、以下の依存関係バージョンをサポートしています:
| 依存関係 | 最小および最大バージョン |
|---|---|
| Kotlin Gradleプラグイン (KGP) | 2.3.20–2.4.x |
| Android Gradleプラグイン (AGP) | 8.13.0以降 |
| Gradle | 8.13以降。AGP 9.0以降の場合はGradle 9.xを使用。 |
| JDK | 17以降 |
コンパイル時のKSPの動作
KSPは、Kotlin文法に基づいてKotlinソースコードをシンボルの階層として表現します。プロセッサーはこれらのシンボルを使用して、クラス、関数、プロパティ、型などの宣言を検査します。
KSPは宣言と型情報をモデル化しますが、プロセッサーに式や関数本体へのアクセスは提供しません。
KSPはコンパイルプロセスにおいて以下のように動作します:
KSPプロセッサーがソースコードとリソースを解析します。
プロセッサーがソースファイルやその他の出力を生成します。
Kotlinコンパイラーが、元のソースコードを生成されたコードと一緒にコンパイルします。
KSPの詳細については、こちらの動画をご覧ください:
KSPによるプロセッサーの実行方法
KSPは、SymbolProcessorインスタンスを作成するためのエントリーポイントとしてSymbolProcessorProviderの実装を使用します:
interface SymbolProcessorProvider {
fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}SymbolProcessorインターフェースには処理ロジックが含まれます。KSPはprocess()関数を呼び出し、プロセッサーがソースコード内のシンボルにアクセスするために使用するResolverを提供します:
interface SymbolProcessor {
fun process(resolver: Resolver): List<KSAnnotated>
fun finish() {}
fun onError() {}
}プロセッサーの実装および登録方法に関するステップバイステップのガイドについては、KSP入門を参照してください。
サポートされているライブラリ
以下の表は、Androidの主要なライブラリと、それぞれのKSPサポート状況を示しています:
| ライブラリ | ステータス |
|---|---|
| Room | 公式サポート |
| Moshi | 公式サポート |
| RxHttp | 公式サポート |
| Kotshi | 公式サポート |
| Lyricist | 公式サポート |
| Lich SavedState | 公式サポート |
| gRPC Dekorator | 公式サポート |
| EasyAdapter | 公式サポート |
| Koin Annotations | 公式サポート |
| Glide | 公式サポート |
| Micronaut | 公式サポート |
| Epoxy | 公式サポート |
| Paris | 公式サポート |
| Auto Dagger | 公式サポート |
| SealedX | 公式サポート |
| Ktorfit | 公式サポート |
| Mockative | 公式サポート |
| Kotest | 公式サポート |
| DeeplinkDispatch | airbnb/DeepLinkDispatch#323によりサポート |
| Dagger | Alpha |
| Motif | Alpha |
| Hilt | 対応中 |
| Auto Factory | 未サポート |
