Skip to content

Kotlin Symbol Processing API ​

Kotlin Symbol Processing(KSP)は、Kotlin向けのソースコード生成フレームワークです。KSP APIを使用すると、ソースコードに関する静的情報を検査し、それをもとに新しいコードを生成するプロセッサーを作成できます。最も一般的なユースケースは、アノテーションに基づいたコード生成です。

KSPは、軽量なコンパイラープラグインの作成を簡素化することを目的としています。KSPで構築されたコンパイラープラグインは、シンボルプロセッサー(symbol processor)、または略してプロセッサーと呼ばれます。KSPの明確に定義されたAPIがコンパイラーの内部変更を隠蔽するため、プロセッサーのメンテナンスに多くの労力を費やす必要がありません。ただし、このアプローチにはトレードオフもあります。例えば、KSPベースのプロセッサーは式や文を検査することはできず、ソースコード自体を変更することもできません。

KSPベースのプラグインの代表的なユースケースには、以下のようなものがあります。

  • 依存性注入 (Dagger)
  • シリアライゼーション (Moshi)
  • データベース管理 (Room)

最初のKSPベースのプロセッサーを作成する方法については、KSP入門を参照してください。

必要条件 ​

最新のKSPバージョン(2.3.12)は、以下の依存関係バージョンをサポートしています:

依存関係最小および最大バージョン
Kotlin Gradleプラグイン (KGP)2.3.20–2.4.x
Android Gradleプラグイン (AGP)8.13.0以降
Gradle8.13以降。AGP 9.0以降の場合はGradle 9.xを使用。
JDK17以降

コンパイル時のKSPの動作 ​

KSPは、Kotlin文法に基づいてKotlinソースコードをシンボルの階層として表現します。プロセッサーはこれらのシンボルを使用して、クラス、関数、プロパティ、型などの宣言を検査します。

KSPは宣言と型情報をモデル化しますが、プロセッサーに式や関数本体へのアクセスは提供しません。

KSPはコンパイルプロセスにおいて以下のように動作します:

  1. KSPプロセッサーがソースコードとリソースを解析します。

  2. プロセッサーがソースファイルやその他の出力を生成します。

  3. Kotlinコンパイラーが、元のソースコードを生成されたコードと一緒にコンパイルします。

KSPの詳細については、こちらの動画をご覧ください:

KSPによるプロセッサーの実行方法 ​

KSPは、SymbolProcessorインスタンスを作成するためのエントリーポイントとしてSymbolProcessorProviderの実装を使用します:

kotlin
interface SymbolProcessorProvider {
    fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}

SymbolProcessorインターフェースには処理ロジックが含まれます。KSPはprocess()関数を呼び出し、プロセッサーがソースコード内のシンボルにアクセスするために使用するResolverを提供します:

kotlin
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公式サポート
DeeplinkDispatchairbnb/DeepLinkDispatch#323によりサポート
DaggerAlpha
MotifAlpha
Hilt対応中
Auto Factory未サポート

その他のリソース ​