kapt コンパイラプラグイン

• 以下の場合には kapt を使用してください：
  • Maven プロジェクトを使用している場合。
  • Gradle プロジェクトを使用しているが、必要な Java アノテーションプロセッサがまだ KSP をサポートしていない場合。サポートされているライブラリのリストを確認してください。
• 以下の場合には KSP を使用してください：
  • Gradle プロジェクトを使用しており、必要な Java アノテーションプロセッサが KSP をサポートしている場合。
  • 独自のアノテーションプロセッサを作成したい場合。

kapt コンパイラプラグインを使用すると、Kotlin で既存の Java アノテーションプロセッサを使用でき、Maven と Gradle の両方で動作します。 これは Kotlin ソースコードからスタブファイルを生成し、それらのスタブに対して Java アノテーションプロセッサを実行します。

これにより、MapStruct や データバインディング などのライブラリに対して、Kotlin プロジェクトで Java ベースのアノテーション処理が可能になります。

Gradle での使用

Gradle で kapt を使用するには、以下の手順に従ってください：

1. ビルドスクリプトファイル build.gradle(.kts) に kapt Gradle プラグインを適用します：

   KotlinGroovy

   plugins {
       kotlin("kapt") version "2.3.0"
   }

   plugins {
       id "org.jetbrains.kotlin.kapt" version "2.3.0"
   }

2. dependencies {} ブロックで kapt 構成を使用して、それぞれの依存関係を追加します：

   KotlinGroovy

   dependencies {
       kapt("groupId:artifactId:version")
   }

   dependencies {
       kapt 'groupId:artifactId:version'
   }

3. 以前にアノテーションプロセッサに Android サポート を使用していた場合は、annotationProcessor 構成の使用を kapt に置き換えてください。プロジェクトに Java クラスが含まれている場合、kapt はそれらも処理します。

   androidTest または test ソースに対してアノテーションプロセッサを使用する場合、それぞれの kapt 構成は kaptAndroidTest および kaptTest という名前になります。kaptAndroidTest と kaptTest は kapt を継承しているため、kapt 依存関係を提供すれば、本番ソースとテストの両方で利用可能になります。

アノテーションプロセッサの引数

ビルドスクリプトファイル build.gradle(.kts) の arguments {} ブロックを使用して、アノテーションプロセッサに引数を渡します：

kapt {
    arguments {
        arg("key", "value")
    }
}

Gradle ビルドキャッシュのサポート

kapt のアノテーション処理タスクは、デフォルトで Gradle でキャッシュ されます。 しかし、アノテーションプロセッサは任意のコードを実行できるため、タスクの入力を出力に確実に変換できない場合や、Gradle が追跡していないファイルにアクセスして変更する場合があります。 ビルドで使用されるアノテーションプロセッサを適切にキャッシュできない場合は、ビルドスクリプトで useBuildCache プロパティを指定することで、kapt のキャッシュを完全に無効にできます。 これにより、kapt タスクに対する誤ったキャッシュヒット（false-positive cache hits）を防ぐことができます。

kapt {
    useBuildCache = false
}

kapt を使用するビルド速度の改善

kapt タスクを並列で実行する

kapt を使用するビルドの速度を向上させるために、kapt タスクに対して Gradle Worker API を有効にできます。Worker API を使用すると、Gradle は単一のプロジェクトから独立したアノテーション処理タスクを並列で実行でき、場合によっては実行時間を大幅に短縮できます。

Kotlin Gradle プラグインで カスタム JDK ホーム 機能を使用する場合、kapt タスクのワーカーは プロセス分離モード（process isolation mode）のみを使用します。kapt.workers.isolation プロパティは無視されることに注意してください。

kapt ワーカープロセスに追加の JVM 引数を提供したい場合は、KaptWithoutKotlincTask の入力 kaptProcessJvmArgs を使用します：

KotlinGroovy

tasks.withType<org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask>()
    .configureEach {
        kaptProcessJvmArgs.add("-Xmx512m")
    }

tasks.withType(org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask.class)
    .configureEach {
        kaptProcessJvmArgs.add('-Xmx512m')
    }

Experimental

アノテーションプロセッサのクラスローダーのキャッシュ

アノテーションプロセッサのクラスローダーをキャッシュすることで、多くの Gradle タスクを連続して実行する場合に kapt のパフォーマンスが向上します。

この機能を有効にするには、gradle.properties ファイルで以下のプロパティを使用します：

# gradle.properties
#
# 正の値を指定するとキャッシュが有効になります
# kapt を使用するモジュール数と同じ値を使用してください
kapt.classloaders.cache.size=5

# キャッシュを機能させるために false に設定します
kapt.include.compile.classpath=false

アノテーションプロセッサのキャッシュで問題が発生した場合は、それらのキャッシュを無効にしてください：

# キャッシュを無効にするアノテーションプロセッサのフルネームを指定します
kapt.classloaders.cache.disableForProcessors=[annotation processors full names]

この機能に関する問題が発生した場合は、YouTrack までフィードバックをお寄せください。

アノテーションプロセッサのパフォーマンス測定

アノテーションプロセッサの実行に関する統計情報を取得するには、-Kapt-show-processor-timings プラグインオプションを使用します。 出力例：

Kapt Annotation Processing performance report:
com.example.processor.TestingProcessor: total: 133 ms, init: 36 ms, 2 round(s): 97 ms, 0 ms
com.example.processor.AnotherProcessor: total: 100 ms, init: 6 ms, 1 round(s): 93 ms

このレポートは、プラグインオプション -Kapt-dump-processor-timings (org.jetbrains.kotlin.kapt3:dumpProcessorTimings) を使用してファイルにダンプできます。 次のコマンドは、kapt を実行し、統計を ap-perf-report.file ファイルにダンプします：

kotlinc -cp $MY_CLASSPATH \
-Xplugin=kotlin-annotation-processing-SNAPSHOT.jar -P \
plugin:org.jetbrains.kotlin.kapt3:aptMode=stubsAndApt,\
plugin:org.jetbrains.kotlin.kapt3:apclasspath=processor/build/libs/processor.jar,\
plugin:org.jetbrains.kotlin.kapt3:dumpProcessorTimings=ap-perf-report.file \
-Xplugin=$JAVA_HOME/lib/tools.jar \
-d cli-tests/out \
-no-jdk -no-reflect -no-stdlib -verbose \
sample/src/main/

アノテーションプロセッサで生成されたファイル数の測定

kapt Gradle プラグインは、各アノテーションプロセッサによって生成されたファイル数に関する統計を報告できます。

これにより、未使用のアノテーションプロセッサがビルドに含まれていないかどうかを追跡できます。生成されたレポートを使用して、不要なアノテーションプロセッサをトリガーしているモジュールを見つけ、それを回避するようにモジュールを更新できます。

統計レポートを有効にするには：

1. build.gradle(.kts) で showProcessorStats プロパティの値を true に設定します：

   // build.gradle.kts
   kapt {
       showProcessorStats = true
   }

2. gradle.properties で kapt.verbose Gradle プロパティを true に設定します：

   # gradle.properties
   kapt.verbose=true

コマンドラインオプション verbose を使用して詳細な出力を有効にすることもできます。

統計は info レベルでログに表示されます。 Annotation processor stats: 行に続いて、各アノテーションプロセッサの実行時間に関する統計が表示されます。 それらの行の後に Generated files report: 行があり、各アノテーションプロセッサによって生成されたファイル数に関する統計が表示されます。例：

[INFO] Annotation processor stats:
[INFO] org.mapstruct.ap.MappingProcessor: total: 290 ms, init: 1 ms, 3 round(s): 289 ms, 0 ms, 0 ms
[INFO] Generated files report:
[INFO] org.mapstruct.ap.MappingProcessor: total sources: 2, sources per round: 2, 0, 0

kapt のコンパイル回避

kapt を使用したインクリメンタルビルドの時間を短縮するために、Gradle の コンパイル回避（compile avoidance） を使用できます。 コンパイル回避が有効な場合、プロジェクトを再ビルドする際に Gradle はアノテーション処理をスキップできます。特に、次の場合にアノテーション処理がスキップされます：

• プロジェクトのソースファイルが変更されていない場合。
• 依存関係の変更が ABI 互換である場合（例：メソッドの本体のみが変更された場合）。

ただし、コンパイルクラスパスで見つかったアノテーションプロセッサに対してはコンパイル回避を使用できません。それらが「少しでも変更」されると、アノテーション処理タスクの実行が必要になるためです。

コンパイル回避を使用して kapt を実行するには：

• アノテーションプロセッサの依存関係を kapt* 構成に手動で追加します。

• gradle.properties ファイルで、コンパイルクラスパスからのアノテーションプロセッサの検出をオフにします：

  # gradle.properties
  kapt.include.compile.classpath=false

インクリメンタルアノテーション処理

kapt はデフォルトでインクリメンタルアノテーション処理をサポートしています。 現在、アノテーション処理をインクリメンタルにできるのは、使用されているすべてのアノテーションプロセッサがインクリメンタルである場合のみです。

インクリメンタルアノテーション処理を無効にするには、gradle.properties ファイルに次の行を追加します：

kapt.incremental.apt=false

インクリメンタルアノテーション処理には、インクリメンタルコンパイル も有効になっている必要があることに注意してください。

親構成からのアノテーションプロセッサの継承

共通のアノテーションプロセッサのセットを別の Gradle 構成で親構成（superconfiguration）として定義し、それをサブプロジェクトの kapt 固有の構成でさらに拡張できます。

例として、MapStruct を使用するサブプロジェクトの場合、build.gradle(.kts) ファイルで次の構成を使用します：

val commonAnnotationProcessors by configurations.creating
configurations.named("kapt") { extendsFrom(commonAnnotationProcessors) }

dependencies {
    implementation("org.mapstruct:mapstruct:1.6.3")
    commonAnnotationProcessors("org.mapstruct:mapstruct-processor:1.6.3")
}

この例では、commonAnnotationProcessors Gradle 構成は、すべてのプロジェクトで使用したいアノテーション処理用の共通親構成です。extendsFrom() メソッドを使用して、commonAnnotationProcessors を親構成として追加します。kapt は、commonAnnotationProcessors Gradle 構成が MapStruct アノテーションプロセッサに依存していることを認識します。そのため、kapt はアノテーション処理のための自身の構成に MapStruct アノテーションプロセッサを含めます。

Java コンパイラオプション

kapt はアノテーションプロセッサの実行に Java コンパイラを使用します。 javac に任意のオプションを渡す方法は次のとおりです：

kapt {
    javacOptions {
        // アノテーションプロセッサからのエラーの最大数を増やす。
        // デフォルトは 100。
        option("-Xmaxerrs", 500)
    }
}

存在しない型の補正

一部のアノテーションプロセッサ（AutoFactory など）は、宣言シグネチャ内の正確な型に依存します。 デフォルトでは、kapt は未知の型（生成されたクラスの型を含む）をすべて NonExistentClass に置き換えますが、この動作を変更できます。スタブ内でのエラー型の推論を有効にするには、build.gradle(.kts) ファイルにオプションを追加します：

kapt {
    correctErrorTypes = true
}

Maven での使用

compile の前に kotlin-maven-plugin の kapt ゴールの実行を追加します：

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal> <!-- プラグインの拡張を有効にしている場合は 
        <goals> 要素を省略できます -->
    </goals>
    <configuration>
        <sourceDirs>
            <sourceDir>src/main/kotlin</sourceDir>
            <sourceDir>src/main/java</sourceDir>
        </sourceDirs>
        <annotationProcessorPaths>
            <!-- ここでアノテーションプロセッサを指定します -->
            <annotationProcessorPath>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

アノテーション処理のレベルを設定するには、<configuration> ブロックの aptMode として次のいずれかを設定します：

• stubs – アノテーション処理に必要なスタブのみを生成します。
• apt – アノテーション処理のみを実行します。
• stubsAndApt – (デフォルト) スタブを生成し、アノテーション処理を実行します。

例：

<configuration>
   ...
   <aptMode>stubs</aptMode>
</configuration>

IntelliJ ビルドシステムでの使用

kapt は IntelliJ IDEA 独自のビルドシステムではサポートされていません。アノテーション処理を再実行したい場合は、いつでも「Maven Projects」ツールバーからビルドを起動してください。

CLI での使用

kapt コンパイラプラグインは、Kotlin コンパイラのバイナリ配布物に含まれています。

Xplugin kotlinc オプションを使用して JAR ファイルへのパスを指定することで、プラグインをアタッチできます：

-Xplugin=$KOTLIN_HOME/lib/kotlin-annotation-processing.jar

利用可能なオプションの一覧は次のとおりです：

• sources (必須): 生成されたファイルの出力パス。
• classes (必須): 生成されたクラスファイルとリソースの出力パス。
• stubs (必須): スタブファイルの出力パス。つまり、何らかの一時ディレクトリ。
• incrementalData: バイナリスタブの出力パス。
• apclasspath (繰り返し可能): アノテーションプロセッサ JAR へのパス。所有している JAR の数だけ apclasspath オプションを渡します。
• apoptions: アノテーションプロセッサオプションの base64 エンコードされたリスト。詳細は AP/javac オプションのエンコーディング を参照してください。
• javacArguments: javac に渡されるオプションの base64 エンコードされたリスト。詳細は AP/javac オプションのエンコーディング を参照してください。
• processors: アノテーションプロセッサの完全修飾クラス名のカンマ区切りリスト。指定された場合、kapt は apclasspath 内のアノテーションプロセッサを検索しません。
• verbose: 詳細な出力を有効にします。
• aptMode (必須)
  • stubs – アノテーション処理に必要なスタブのみを生成します。
  • apt – アノテーション処理のみを実行します。
  • stubsAndApt – スタブを生成し、アノテーション処理を実行します。
• correctErrorTypes: 詳細は 存在しない型の補正 を参照してください。デフォルトでは無効です。
• dumpFileReadHistory: アノテーション処理中に使用されたクラスのリストをファイルごとにダンプする出力パス。

プラグインオプションの形式は -P plugin:<plugin id>:<key>=<value> です。オプションは繰り返すことができます。

例：

-P plugin:org.jetbrains.kotlin.kapt3:sources=build/kapt/sources
-P plugin:org.jetbrains.kotlin.kapt3:classes=build/kapt/classes
-P plugin:org.jetbrains.kotlin.kapt3:stubs=build/kapt/stubs

-P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/ap.jar
-P plugin:org.jetbrains.kotlin.kapt3:apclasspath=lib/anotherAp.jar

-P plugin:org.jetbrains.kotlin.kapt3:correctErrorTypes=true

Kotlin ソースの生成

kapt は Kotlin ソースを生成できます。生成された Kotlin ソースファイルを processingEnv.options["kapt.kotlin.generated"] で指定されたディレクトリに書き込むだけで、これらのファイルはメインソースと一緒にコンパイルされます。

kapt は、生成された Kotlin ファイルに対して複数ラウンドの処理をサポートしていないことに注意してください。

AP/Javac オプションのエンコーディング

apoptions および javacArguments CLI オプションは、エンコードされたオプションのマップを受け取ります。 自分でオプションをエンコードする方法は次のとおりです：

fun encodeList(options: Map<String, String>): String {
    val os = ByteArrayOutputStream()
    val oos = ObjectOutputStream(os)

    oos.writeInt(options.size)
    for ((key, value) in options.entries) {
        oos.writeUTF(key)
        oos.writeUTF(value)
    }

    oos.flush()
    return Base64.getEncoder().encodeToString(os.toByteArray())
}

Java コンパイラのアノテーションプロセッサを保持する

デフォルトでは、kapt はすべてのアノテーションプロセッサを実行し、javac によるアノテーション処理を無効にします。 しかし、javac のアノテーションプロセッサの一部を動作させる必要がある場合があります（例えば Lombok など）。

Gradle ビルドファイルで、keepJavacAnnotationProcessors オプションを使用します：

kapt {
    keepJavacAnnotationProcessors = true
}

Maven を使用する場合は、具体的なプラグイン設定を指定する必要があります。 Lombok コンパイラプラグインの設定例を参照してください。

次のステップ

• kapt から KSP への移行方法を確認する