kapt コンパイラプラグイン

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

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

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

kapt は IntelliJ のビルドシステムではサポートされていません。IntelliJ IDEA でアノテーション処理を再実行するには、Maven ツールウィンドウからビルドを起動してください。

プラグインの設定

kapt プラグインは、Gradle、Maven で構成するか、コマンドライン から使用できます。

Gradle

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

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

   KotlinGroovy

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

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

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 依存関係を提供すれば、本番ソースとテストの両方で利用可能になります。

Maven

設定を簡略化するための <extensions> オプション を使用するか、kapt の実行を完全に制御するために 手動 で設定できます。

自動設定

Kotlin Maven プラグインの <extensions> オプションを有効にすることで、kapt の設定を簡略化できます。この場合、ゴールやソースディレクトリを含む kapt の <execution> セクションを手動で設定する必要はありません。

kapt を自動的に設定するには、pom.xml ビルドファイルで kotlin-maven-plugin の <extensions> オプションを true に設定します：

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <extensions>true</extensions>
    <configuration>
        <annotationProcessorPaths>
            <!-- ここでアノテーションプロセッサを指定します -->
            <annotationProcessorPath>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</plugin>

<extensions> オプションの詳細については、自動設定 を参照してください。

手動設定

Kotlin Maven プロジェクトで kapt を手動で設定するには、compile 実行の前に kotlin-maven-plugin の kapt ゴールの実行を追加します：

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal>
    </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 オプションを設定します。例：

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

CLI

kapt は、Kotlin コンパイラのバイナリ配布物に含まれるスタンドアロンの CLI ツールとして利用可能です。

コマンドラインから kapt を実行するには、次のようにします：

kapt <options> <source files>

例：

kapt -Kapt-mode=stubsAndApt \
  -Kapt-sources=build/kapt/sources \
  -Kapt-classes=build/kapt/classes \
  -Kapt-stubs=build/kapt/stubs \
  -Kapt-classpath=lib/ap.jar \
  -Kapt-classpath=lib/anotherAp.jar \
  src/main/kotlin

• kapt 固有のコンパイラオプション の全リストを参照してください。
• すべての有効な Kotlin コンパイラオプション を渡すこともできます。それらを確認するには kotlinc -help を実行してください。

アノテーションプロセッサの構成

kapt には、プロセッサのクラスパスの管理、共有構成からのプロセッサの継承、javac 固有のプロセッサのアクティブ維持など、アノテーションプロセッサの検出、編成、および実行を制御するためのオプションが用意されています。

アノテーションプロセッサや javac へのオプションの受け渡しなど、その他の構成オプションについては、アノテーションプロセッサの構成 を参照してください。

プロセッサのクラスパスと検出の設定

kapt のプロセッサパスに含まれていないアノテーションプロセッサの検出を無効にすることができます。これにより、不要なアノテーションプロセッサをコンパイルクラスパスから除外できます。

Gradle

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

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

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

そのため、コンパイルクラスパスからのアノテーションプロセッサの使用は推奨されません。これらのプロセッサを kapt の処理から除外するには、gradle.properties ファイルに kapt.include.compile.classpath プロパティを追加します：

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

このオプションを false に設定すると、プロセッサパス（kapt* 構成）に含まれていないアノテーションプロセッサの依存関係は、kapt の処理から除外されます。

Maven

kapt のプロセッサパスに含まれていないアノテーションプロセッサを除外するには、kapt プラグインの <execution> セクションで includeCompileClasspath オプションを false に設定します：

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal>
    </goals>
    <configuration>
        <includeCompileClasspath>false</includeCompileClasspath>
        <sourceDirs>...</sourceDirs>
        <annotationProcessorPaths>...</annotationProcessorPaths>
    </configuration>
</execution>

あるいは、pom.xml の <properties> セクションで kapt.include.compile.classpath プロパティを使用することもできます：

<properties>
    <kapt.include.compile.classpath>false</kapt.include.compile.classpath>
</properties>

このオプションを false に設定すると、<annotationProcessorPaths> セクションに含まれていないアノテーションプロセッサは kapt の処理から除外されます。

includeCompileClasspath オプションが設定されておらず、kapt がプロセッサパスで明示的に定義されていないアノテーションプロセッサをコンパイルクラスパス上で検出した場合、非推奨の警告が表示されます：

[WARNING] Annotation processors discovery from compile classpath is deprecated.
Set 'kapt.include.compile.classpath=false' to disable discovery.

kapt クラスパスに存在しないアノテーションプロセッサの一覧を確認するには、ビルドを --info ログレベルオプションを付けて実行してください。

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

共通のアノテーションプロセッサのセットを別の 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 はすべてのアノテーションプロセッサを実行し、javac によるアノテーション処理を無効にします。 しかし、javac のアノテーションプロセッサの一部を動作させる必要がある場合があります（例えば Lombok など）。

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

kapt {
    keepJavacAnnotationProcessors = true
}

Maven を使用する場合は、プラグインを明示的に構成してください。 Lombok コンパイラプラグインの設定例 を参照してください。

kapt ビルドの最適化

kapt は、タスクの並列実行、ビルドキャッシュの活用、プロセッサクラスローダーのキャッシュ、インクリメンタルアノテーション処理の使用など、アノテーション処理時間を短縮するための Gradle 固有の戦略をいくつか提供しています。

エラー型の補正、スタブメタデータの削除、コンパイルクラスパスのスキャンなど、ビルドの動作に影響を与えるその他のオプションについては、動作オプション を参照してください。

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

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

Kotlin Gradle プラグインで カスタム JDK バージョン を設定する場合、kapt タスクのワーカーは processIsolation() モードのみを使用します。

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

Gradle ビルドキャッシュの安全な使用

Gradle は デフォルトで kapt のアノテーション処理タスクをキャッシュします。 しかし、アノテーションプロセッサは任意のコードを実行できるため、タスクの入力を出力に不必要に変換したり、Gradle が追跡していないファイルにアクセスして変更したりする場合があります。

ビルドで使用されるアノテーションプロセッサを適切にキャッシュできない場合は、kapt タスクに対する誤ったキャッシュヒットを防ぐためにキャッシュを無効にできます。これを行うには、ビルドスクリプトで useBuildCache プロパティを使用します：

kapt {
    useBuildCache = false
}

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 までフィードバックをお寄せください。

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

Gradle では、kapt はデフォルトでインクリメンタルアノテーション処理をサポートしており、変更されたファイルのみが再処理されます。

現在、インクリメンタルアノテーション処理が機能するのは、次の場合のみです：

• インクリメンタルコンパイル が有効である。
• ビルド内のすべてのアノテーションプロセッサがインクリメンタルである。

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

kapt.incremental.apt=false

現在、Maven や CLI では kapt のインクリメンタルアノテーション処理はサポートされていません。

パフォーマンスの分析

kapt には、プロセッサごとの実行時間レポートや、未使用のプロセッサを特定するための生成ファイル数など、アノテーション処理のパフォーマンスを把握するのに役立つ組み込みの診断機能が用意されています。

インクリメンタル処理をデバッグするためのファイル読み取り履歴やメモリリーク検出など、その他の診断オプションについては、診断および統計オプション を参照してください。

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

アノテーションプロセッサの実行に関するパフォーマンス統計を取得するには、showProcessorStats オプションを使用します。出力例：

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

このレポートは dumpProcessorStats オプションを使用してファイルにダンプできます。 例えば、次の CLI コマンドは kapt を実行し、統計を ap-perf-report.file ファイルにダンプします：

kapt -Kapt-mode=stubsAndApt \
  -Kapt-classpath=processor/build/libs/processor.jar \
  -Kapt-dump-processor-stats=ap-perf-report.file \
  sample/src/main/

生成されたファイル数の追跡

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

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

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

1. Gradle ビルドファイルで、showProcessorStats オプションを true に設定します：

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

2. gradle.properties ファイルで、verbose コンパイラオプションを true に設定します：

   # gradle.properties
   kapt.verbose=true

統計は 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

現在、Maven や CLI では showProcessorStats および verbose コンパイラオプションを使用した生成ファイル数の追跡はサポートされていません。

Kotlin ソースの生成

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

kapt は、生成された Kotlin ファイルに対して複数ラウンドのアノテーション処理をサポートしていません。

コンパイラオプション

アノテーションプロセッサの構成

オプション	説明	設定方法
aptMode	kapt ワークフローの各段階の実行を制御します： stubsAndApt: スタブを生成し、アノテーション処理を実行します（デフォルト） stubs: Kotlin から Java スタブのみを生成します apt: アノテーション処理のみを実行します（スタブがすでに存在することを前提とします）	Gradle: 直接利用できません。Gradle は stubs と apt を別々のタスクとして実行します Maven: CLI: -Kapt-mode=stubsAndApt
classpath	アノテーションプロセッサが検出されるクラスパスエントリ。	Gradle: Maven: CLI: -Kapt-classpath=lib/my-processor.jar
processors	検出をバイパスして実行するプロセッサの完全修飾クラス名をカンマ区切りで指定します。	Gradle: Maven: CLI: -Kapt-processors=com.example.MyProcessor
apOption	アノテーションプロセッサに渡されるキーと値のオプション。	Gradle: Maven: CLI: -Kapt-options:room.schemaLocation=/schemas
javacOption	Java コンパイラに渡されるキーと値のオプション。	Gradle: Maven: CLI: -Kapt-javac-option:-source=11
processIncrementally	インクリメンタルアノテーション処理を有効にします。変更の影響を受けるファイルのみを再処理します。	Gradle: Maven: 現在サポートされていません CLI: 現在サポートされていません

出力ディレクトリオプション

オプション	説明	設定方法
sources	アノテーションプロセッサが .java ソースファイルを生成するディレクトリ。	Gradle: build/generated/source/kapt/main に自動的に設定されます Maven: target/generated-sources/kapt/ に自動的に設定されます CLI: -Kapt-sources=build/kapt/sources
classes	生成されたソースからコンパイルされた .class ファイルのディレクトリ。	Gradle: 自動的に管理されます Maven: 自動的に管理されます CLI: -Kapt-classes=build/kapt/classes
stubs	アノテーションプロセッサの入力として使用される、Kotlin ソースから生成された Java スタブファイルのディレクトリ。	Gradle: 自動的に管理されます Maven: 自動的に管理されます CLI: -Kapt-stubs=build/kapt/stubs
incrementalData	インクリメンタルビルドの状態を保存します。	Gradle: 自動的に管理されます Maven: 現在サポートされていません CLI: 現在サポートされていません

動作オプション

オプション	説明	設定方法
correctErrorTypes	デフォルトでは、kapt はすべての未知の型（生成されたクラスの型を含む）を NonExistentClass に置き換えます。 スタブ内でのエラー型の推論を有効にして、未解決のエラー型を生成されたソースからの型に置き換えることができます。 デフォルトは false です	Gradle: Maven: CLI: -Kapt-correct-error-types=true
dumpDefaultParameterValues	生成されたスタブにフィールド値としてデフォルトパラメータの初期化子を含めます。 デフォルトは false です	Gradle: Maven: 利用できません CLI: -Kapt-dump-default-parameter-values=true
mapDiagnosticLocations	スタブファイルからのエラーメッセージを、元の Kotlin ソースの場所にマッピングし直します。 デフォルトは false です	Gradle: Maven: CLI: -Kapt-map-diagnostic-locations=true
strict	スタブ生成の非互換性を、警告ではなくエラーとして扱います。 デフォルトは false です	Gradle: Maven: 利用できません CLI: -Kapt-strict=true
stripMetadata	生成されたスタブから @kotlin.Metadata アノテーションを削除し、スタブのサイズを縮小してプロセッサから Kotlin 固有の情報を隠します。 デフォルトは false です	Gradle: Maven: 利用できません CLI: -Kapt-strip-metadata=true
verbose	kapt の詳細ログを有効にします。 デフォルトは false です	Gradle: Maven: 現在サポートされていません CLI: 現在サポートされていません
infoAsWarnings	情報（info）レベルの kapt メッセージを警告（warning）に昇格させます。 デフォルトは false です	Gradle: 直接利用できません Maven: 現在サポートされていません CLI: 現在サポートされていません
includeCompileClasspath	コンパイルクラスパスをスキャンしてアノテーションプロセッサを探します。再現性のために false に設定することをお勧めします。 デフォルトは true です	Gradle: Maven: CLI: 現在サポートされていません

診断および統計オプション

オプション	説明	設定方法
showProcessorStats	プロセッサごとの実行時間を標準出力（stdout）に印刷します。	Gradle: Maven: 利用できません CLI: -Kapt-show-processor-stats=true
dumpProcessorStats	プロセッサのタイミング統計をファイルに書き込みます。	Gradle: 利用できません Maven: 利用できません CLI: -Kapt-dump-processor-stats=build/kapt-stats.txt
dumpFileReadHistory	プロセッサによって読み取られたファイルのリストをファイルに書き込みます。インクリメンタルアノテーションプロセッサのデバッグに役立ちます。	Gradle: 利用できません Maven: 利用できません CLI: -Kapt-dump-file-read-history=build/kapt-reads.txt
detectMemoryLeaks	メモリリーク検出モード：none、default、または paranoid。	Gradle: Maven: 現在サポートされていません CLI: 現在サポートされていません

次のステップ

• MapStruct アノテーションプロセッサで kapt を使用する
• kapt から KSP への移行方法を確認する