kaptコンパイラープラグイン

kaptはメンテナンスモードです。最新のKotlinおよびJavaリリースに対応するよう更新を続けていますが、新機能の実装予定はありません。アノテーション処理にはKotlin Symbol Processing API (KSP)を使用してください。 KSPがサポートするライブラリのリストはこちらを参照してください。

アノテーションプロセッサー（JSR 269参照）は、Kotlinでは_kapt_コンパイラープラグインでサポートされています。

要するに、kaptはJavaベースのアノテーション処理を有効にすることで、Daggerや Data Bindingといったライブラリを Kotlinプロジェクトで使用できるようにします。

K2コンパイラーでkaptを使用中に問題が発生した場合は、課題トラッカーに報告し、gradle.propertiesファイルでK2モードを無効にしてください。
kotlin
kapt.use.k2=false

Gradleでの使用

Gradleでkaptを使用するには、次の手順に従います。

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

KotlinGroovy

kotlin

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

groovy

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

dependencies {}ブロックでkapt構成を使用して、それぞれの依存関係を追加します。
KotlinGroovy
kotlin
dependencies { kapt("groupId:artifactId:version") }
groovy
dependencies { kapt 'groupId:artifactId:version' }
以前にアノテーションプロセッサーのAndroidサポートを使用していた場合、annotationProcessor構成の使用をkaptに置き換えてください。プロジェクトにJavaクラスが含まれている場合、kaptもそれらを処理します。
androidTestまたはtestソースにアノテーションプロセッサーを使用する場合、それぞれのkapt構成は kaptAndroidTestとkaptTestと命名されます。kaptAndroidTestとkaptTestはkaptを拡張しているため、 kapt依存関係を提供すれば、プロダクションソースとテストの両方で利用可能になります。

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

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

kotlin

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

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

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

groovy

kapt {
    useBuildCache = false
}

kaptを使用するビルドの速度向上

kaptタスクを並行して実行

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

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

kaptワーカプロセスに追加のJVM引数を提供したい場合は、KaptWithoutKotlincTaskの入力kaptProcessJvmArgsを使用してください。

KotlinGroovy

kotlin

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

groovy

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

Experimental

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

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

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

none

# gradle.properties
#
# Any positive value enables caching
# Use the same value as the number of modules that use kapt
kapt.classloaders.cache.size=5

# Disable for caching to work
kapt.include.compile.classpath=false

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

none

# Specify annotation processors' full names to disable caching for them
kapt.classloaders.cache.disableForProcessors=[annotation processors full names]

この機能で問題が発生した場合は、 YouTrackでフィードバックをいただけると幸いです。

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

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

text

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ファイルにダンプします。

bash

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プラグインは、各アノテーションプロセッサーについて生成されたファイルの数に関する統計を報告できます。

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

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

build.gradle.kts)でshowProcessorStatsプロパティの値をtrueに設定します。
kotlin
```
// build.gradle.kts
kapt {
    showProcessorStats = true
}
```
gradle.propertiesでkapt.verbose Gradleプロパティをtrueに設定します。
none
```
# gradle.properties
kapt.verbose=true
```

コマンドラインオプションverboseでも詳細出力を有効にできます。

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

text

[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のコンパイル回避を使用できます。コンパイル回避が有効になっている場合、Gradleはプロジェクトを再構築する際にアノテーション処理をスキップできます。特に、アノテーション処理は次の場合にスキップされます。

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

ただし、コンパイルクラスパスで検出されたアノテーションプロセッサーにはコンパイル回避を使用できません。これは、それらの_どのような変更_であってもアノテーション処理タスクの実行を必要とするためです。

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

アノテーションプロセッサーの依存関係をkapt*構成に手動で追加します。
gradle.propertiesファイルで、コンパイルクラスパス内のアノテーションプロセッサーの検出をオフにします。
none
```
# gradle.properties
kapt.include.compile.classpath=false
```

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

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

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

none

kapt.incremental.apt=false

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

スーパー構成からアノテーションプロセッサーを継承

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

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

kotlin

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

dependencies {
    implementation("com.google.dagger:dagger:2.48.1")
    commonAnnotationProcessors("com.google.dagger:dagger-compiler:2.48.1")
}

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

Javaコンパイラーオプション

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

groovy

kapt {
    javacOptions {
        // Increase the max count of errors from annotation processors.
        // Default is 100.
        option("-Xmaxerrs", 500)
    }
}

存在しない型の修正

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

groovy

kapt {
    correctErrorTypes = true
}

Mavenでの使用

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

xml

<execution>
    <id>kapt</id>
    <goals>
        <goal>kapt</goal> <!-- You can skip the <goals> element
        if you enable extensions for the plugin -->
    </goals>
    <configuration>
        <sourceDirs>
            <sourceDir>src/main/kotlin</sourceDir>
            <sourceDir>src/main/java</sourceDir>
        </sourceDirs>
        <annotationProcessorPaths>
            <!-- Specify your annotation processors here -->
            <annotationProcessorPath>
                <groupId>com.google.dagger</groupId>
                <artifactId>dagger-compiler</artifactId>
                <version>2.9</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

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

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

例:

xml

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

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

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

CLIでの使用

kaptコンパイラープラグインは、Kotlinコンパイラーのバイナリディストリビューションで利用可能です。

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

bash

-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>。オプションは繰り返すことができます。

例:

bash

-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オプションは、エンコードされたオプションのマップを受け入れます。自分でオプションをエンコードする方法は次のとおりです。

kotlin

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オプションを使用します。

groovy

kapt {
    keepJavacAnnotationProcessors = true
}

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

概要

ビルダー

Spring

Spring Bootを使用してデータベースを持つRESTful Webサービスを作成する

JavaからKotlinへの移行ガイド

C interop

Objective-C interop

メモリマネージャー

リファレンスとヒント

JSプラットフォーム向けKotlin

概要

Dokkaを実行する

出力形式

認知複雑度の最小化

kaptコンパイラープラグイン

Gradleでの使用

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

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

kaptを使用するビルドの速度向上

kaptタスクを並行して実行

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

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

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

kaptのコンパイル回避

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

スーパー構成からアノテーションプロセッサーを継承

Javaコンパイラーオプション

存在しない型の修正

Mavenでの使用

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

CLIでの使用

Kotlinソースの生成

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

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

Spring Bootを使用してデータベースを持つRESTful Webサービスを作成する

kaptコンパイラープラグイン ​

Gradleでの使用 ​

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

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

kaptを使用するビルドの速度向上 ​

kaptタスクを並行して実行 ​

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

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

アノテーションプロセッサーによって生成されたファイルの数を測定 ​

kaptのコンパイル回避 ​

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

スーパー構成からアノテーションプロセッサーを継承 ​

Javaコンパイラーオプション ​

存在しない型の修正 ​

Mavenでの使用 ​

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

CLIでの使用 ​

Kotlinソースの生成 ​

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

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

kaptコンパイラープラグイン

Gradleでの使用

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

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

kaptを使用するビルドの速度向上

kaptタスクを並行して実行

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

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

kaptのコンパイル回避

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

スーパー構成からアノテーションプロセッサーを継承

Javaコンパイラーオプション

存在しない型の修正

Mavenでの使用

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

CLIでの使用

Kotlinソースの生成

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

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