Kotlin Gradleプラグインにおけるコンパイルとキャッシュ
このページでは、以下のトピックについて学ぶことができます。
- インクリメンタルコンパイル
- Gradleビルドキャッシュのサポート
- Gradleコンフィグレーションキャッシュのサポート
- KotlinデーモンとGradleでの使用方法
- 以前のコンパイラへのロールバック
- Kotlinコンパイラ実行戦略の定義
- Kotlinコンパイラのフォールバック戦略
- 最新の言語バージョンの試用
- ビルドレポート
インクリメンタルコンパイル
Kotlin Gradleプラグインはインクリメンタルコンパイル(増分コンパイル)をサポートしており、Kotlin/JVMおよびKotlin/JSプロジェクトではデフォルトで有効になっています。 インクリメンタルコンパイルはビルド間でクラスパス内のファイルへの変更を追跡し、これらの変更によって影響を受けるファイルのみが コンパイルされるようにします。 このアプローチはGradleのビルドキャッシュと連携し、コンパイル回避(compilation avoidance)をサポートします。
Kotlin/JVMの場合、インクリメンタルコンパイルはクラスパスのスナップショットに依存しており、 モジュールのAPI構造をキャプチャして再コンパイルが必要なタイミングを判断します。 パイプライン全体を最適化するために、Kotlinコンパイラは2種類のクラスパススナップショットを使用します。
- きめ細かなスナップショット(Fine-grained snapshots): プロパティや関数などのクラスメンバーに関する詳細情報を含みます。 メンバーレベルの変更が検出されると、Kotlinコンパイラは変更されたメンバーに依存するクラスのみを再コンパイルします。 パフォーマンスを維持するため、Kotlin GradleプラグインはGradleキャッシュ内の
.jarファイルに対して粗粒度のスナップショットを作成します。 - 粗粒度のスナップショット(Coarse-grained snapshots): クラスのABIハッシュのみを含みます。 ABIの一部が変更されると、Kotlinコンパイラは変更されたクラスに依存するすべてのクラスを再コンパイルします。 これは、外部ライブラリのように頻繁に変更されないクラスに役立ちます。
Kotlin/JSプロジェクトでは、履歴ファイルに基づいた異なるインクリメンタルコンパイルアプローチが使用されます。
インクリメンタルコンパイルを無効にする方法はいくつかあります。
Kotlin/JVMの場合は
kotlin.incremental=falseを設定します。Kotlin/JSプロジェクトの場合は
kotlin.incremental.js=falseを設定します。コマンドラインパラメータとして
-Pkotlin.incremental=falseまたは-Pkotlin.incremental.js=falseを使用します。このパラメータは、それ以降の各ビルドに追加する必要があります。
インクリメンタルコンパイルを無効にすると、ビルド後に増分キャッシュが無効になります。最初のビルドは決して増分(インクリメンタル)にはなりません。
インクリメンタルコンパイルの問題は、障害が発生してから数回のビルドが経過した後に顕在化することがあります。ビルドレポート を使用して変更とコンパイルの履歴を追跡してください。これにより、再現性のあるバグレポートを提供するのに役立ちます。
現在のインクリメンタルコンパイルのアプローチがどのように機能し、以前のアプローチとどう異なるかについての詳細は、 ブログ記事を参照してください。
Gradleビルドキャッシュのサポート
Kotlinプラグインは、将来のビルドで再利用するためにビルド出力を保存するGradleビルドキャッシュを使用します。
すべてのKotlinタスクでキャッシュを無効にするには、システムプロパティkotlin.caching.enabledをfalseに設定します (-Dkotlin.caching.enabled=falseの引数を指定してビルドを実行します)。
Gradleコンフィグレーションキャッシュのサポート
Kotlinプラグインは、設定フェーズの結果を後続のビルドで再利用することでビルドプロセスを高速化するGradleコンフィグレーションキャッシュを使用します。
コンフィグレーションキャッシュを有効にする方法については、Gradleドキュメント を参照してください。この機能を有効にすると、Kotlin Gradleプラグインは自動的にこれを使用し始めます。
KotlinデーモンとGradleでの使用方法
- Gradleデーモンと一緒に実行され、プロジェクトをコンパイルします。
- IntelliJ IDEA組み込みのビルドシステムでプロジェクトをコンパイルする場合、Gradleデーモンとは別に実行されます。
Kotlinデーモンは、Kotlinコンパイルタスクの1つがソースのコンパイルを開始した際、Gradleの実行フェーズ で起動します。 Kotlinデーモンは、Gradleデーモンが停止したとき、またはKotlinのコンパイルが行われないままアイドル状態が2時間続いたときのいずれかで停止します。
Kotlinデーモンは、Gradleデーモンと同じJDKを使用します。
KotlinデーモンのJVM引数の設定
引数を設定する以下の各方法は、前に指定されたものを上書きします。
Gradleデーモン引数の継承
デフォルトでは、KotlinデーモンはGradleデーモンから特定の引数セットを継承しますが、Kotlinデーモンに直接指定されたJVM引数があればそれらで上書きします。たとえば、gradle.propertiesファイルに以下のJVM引数を追加した場合:
org.gradle.jvmargs=-Xmx1500m -Xms500m -XX:MaxMetaspaceSize=1gこれらの引数は、KotlinデーモンのJVM引数に追加されます。
-Xmx1500m -XX:ReservedCodeCacheSize=320m -XX:MaxMetaspaceSize=1g -XX:UseParallelGC -ea -XX:+UseCodeCacheFlushing -XX:+HeapDumpOnOutOfMemoryError -Djava.awt.headless=true -Djava.rmi.server.hostname=127.0.0.1 --add-exports=java.base/sun.nio.ch=ALL-UNNAMEDJVM引数に関するKotlinデーモンのデフォルト動作の詳細については、JVM引数に関するKotlinデーモンの動作を参照してください。
kotlin.daemon.jvm.optionsシステムプロパティ
GradleデーモンのJVM引数にkotlin.daemon.jvm.optionsシステムプロパティが含まれている場合は、gradle.propertiesファイルでそれを使用します。
org.gradle.jvmargs=-Dkotlin.daemon.jvm.options=-Xmx1500m,Xms500m引数を渡す際は、以下のルールに従ってください。
- マイナス記号
-は、Xmx、XX:MaxMetaspaceSize、およびXX:ReservedCodeCacheSizeの引数の前にのみ使用してください。 - 引数はスペースを含めずにカンマ(
,)で区切ってください。スペースの後にある引数は、KotlinデーモンではなくGradleデーモン用に使用されます。
以下の条件がすべて満たされる場合、Gradleはこれらのプロパティを無視します。
- GradleがJDK 1.9以上を使用している。
- Gradleのバージョンが7.0以上7.1.1以下である。
- GradleがKotlin DSLスクリプトをコンパイルしている。
- Kotlinデーモンが実行されていない。
これを解決するには、Gradleをバージョン7.2(またはそれ以上)にアップグレードするか、kotlin.daemon.jvmargsプロパティを使用してください(次のセクションを参照)。
kotlin.daemon.jvmargsプロパティ
gradle.propertiesファイルにkotlin.daemon.jvmargsプロパティを追加できます。
kotlin.daemon.jvmargs=-Xmx1500m -Xms500mここで、またはGradleのJVM引数でReservedCodeCacheSize引数を指定しない場合、Kotlin Gradleプラグインはデフォルト値の320mを適用することに注意してください。
-Xmx1500m -XX:ReservedCodeCacheSize=320m -Xms500mkotlin拡張
kotlin拡張で引数を指定できます。
kotlin {
kotlinDaemonJvmArgs = listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC")
}kotlin {
kotlinDaemonJvmArgs = ["-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"]
}特定のタスク定義
特定のタスクに対して引数を指定できます。
tasks.withType<CompileUsingKotlinDaemon>().configureEach {
kotlinDaemonJvmArguments.set(listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"))
}tasks.withType(CompileUsingKotlinDaemon).configureEach { task ->
task.kotlinDaemonJvmArguments = ["-Xmx1g", "-Xms512m"]
}この場合、タスクの実行時に新しいKotlinデーモンインスタンスが起動する可能性があります。詳細については、JVM引数に関するKotlinデーモンの動作を参照してください。
JVM引数に関するKotlinデーモンの動作
KotlinデーモンのJVM引数を設定する際は、以下の点に注意してください。
- 異なるサブプロジェクトやタスクが異なるJVM引数セットを持っている場合、複数のKotlinデーモンインスタンスが同時に実行されることが想定されています。
- 新しいKotlinデーモンインスタンスは、Gradleが関連するコンパイルタスクを実行し、既存のKotlinデーモンが同じJVM引数セットを持っていない場合にのみ起動します。 たとえば、プロジェクトに多数のサブプロジェクトがあるとします。その大半はKotlinデーモンにある程度のヒープメモリしか必要としませんが、1つのモジュールだけが(滅多にコンパイルされないものの)大量のヒープメモリを必要とします。 このような場合は、そのモジュールに異なるJVM引数セットを提供することで、この特定のモジュールを触る開発者に対してのみ、より大きなヒープサイズを持つKotlinデーモンが起動するようにできます。
コンパイルリクエストを処理するのに十分なヒープサイズを持つKotlinデーモンがすでに実行されている場合、 要求された他のJVM引数が異なっていても、新しいデーモンを起動せずにそのデーモンが再利用されます。
以下の引数が指定されていない場合、KotlinデーモンはGradleデーモンからそれらを継承します。
-Xmx-XX:MaxMetaspaceSize-XX:ReservedCodeCacheSize。指定も継承もされていない場合、デフォルト値は320mです。
Kotlinデーモンには、以下のデフォルトJVM引数があります。
-XX:UseParallelGC。この引数は、他のガベージコレクタが指定されていない場合にのみ適用されます。-ea-XX:+UseCodeCacheFlushing-Djava.awt.headless=true-D{java.servername.property}={localhostip}--add-exports=java.base/sun.nio.ch=ALL-UNNAMED。この引数はJDKバージョン16以降にのみ適用されます。
KotlinデーモンのデフォルトJVM引数のリストはバージョンによって異なる場合があります。VisualVMなどのツールを使用して、Kotlinデーモンのような実行中のJVMプロセスの実際の設定を確認できます。
以前のコンパイラへのロールバック
Kotlin 2.0.0以降、K2コンパイラがデフォルトで使用されます。
Kotlin 2.0.0~2.3.21で以前のコンパイラを使用するには、以下のいずれかを行います。
build.gradle.ktsファイルで、言語バージョンを1.9に設定します。または
コンパイラオプション
-language-version 1.9を使用します。
Kotlin 2.4.0以降は、以前のコンパイラにロールバックすることはできません。
K2コンパイラの利点についての詳細は、K2コンパイラ移行ガイドを参照してください。
最新の言語バージョンの試用
Kotlin 2.0.0以降では、最新の言語バージョンを試すために、gradle.propertiesファイルでkotlin.experimental.tryNextプロパティを設定します。 このプロパティを使用すると、Kotlin Gradleプラグインは言語バージョンをお使いのKotlinバージョンのデフォルト値より1つ上のバージョンに引き上げます。 たとえばKotlin 2.0.0では、デフォルトの言語バージョンは2.0であるため、このプロパティによって言語バージョン2.1が設定されます。
あるいは、以下のコマンドを実行することもできます。
./gradlew assemble -Pkotlin.experimental.tryNext=trueビルドレポートでは、各タスクのコンパイルに使用された言語バージョンを確認できます。
ビルドレポート
ビルドレポートには、各コンパイルフェーズの所要時間や、コンパイルが増分(インクリメンタル)にならなかった理由が含まれます。 コンパイル時間が長すぎる場合や、同じプロジェクトでコンパイル時間が変動する場合のパフォーマンス問題の調査にビルドレポートを活用してください。
Kotlinビルドレポートは、個々のGradleタスクを粒度単位とするGradle build scansよりも効率的に、ビルドパフォーマンスの問題を調査するのに役立ちます。
コンパイル時間が長い場合に、ビルドレポートを分析することで解決できる一般的なケースが2つあります。
- ビルドがインクリメンタルでなかった場合。理由を分析し、根本的な問題を修正します。
- ビルドはインクリメンタルだったが時間がかかりすぎた場合。ソースファイルを再編成してみてください(大きなファイルを分割する、個別のクラスを別々のファイルに保存する、大きなクラスをリファクタリングする、トップレベル関数を別々のファイルで宣言するなど)。
ビルドレポートには、プロジェクトで使用されているKotlinバージョンも表示されます。さらに、Kotlin 1.9.0以降では、 コードのコンパイルにどのコンパイラが使用されたかをGradle build scansで確認できます。
ビルドレポートの読み方 およびJetBrainsでのビルドレポートの活用方法について学ぶことができます。
ビルドレポートの有効化
ビルドレポートを有効にするには、gradle.propertiesでビルドレポートの出力先を宣言します。
kotlin.build.report.output=file出力には以下の値およびその組み合わせを使用できます。
| オプション | 説明 |
|---|---|
file | 人間が読める形式でローカルファイルにビルドレポートを保存します。デフォルトは${project_folder}/build/reports/kotlin-build/${project_name}-timestamp.txtです。 |
single_file | 指定したローカルファイルにオブジェクト形式でビルドレポートを保存します。 |
build_scan | ビルドスキャン(build scan)のcustom valuesセクションにビルドレポートを保存します。Gradle Enterpriseプラグインにはカスタム値の数と長さに制限があることに注意してください。大規模なプロジェクトでは、一部の値が失われる可能性があります。 |
http | HTTP(S)を使用してビルドレポートを送信します。POSTメソッドはJSON形式でメトリクスを送信します。送信されるデータの現在のバージョンは、Kotlinリポジトリで確認できます。HTTPエンドポイントのサンプルはこちらのブログ記事にあります。 |
json | JSON形式でローカルファイルにビルドレポートを保存します。デフォルトは${project_folder}/build/reports/kotlin-build/${project_name}-build-<date-time>-<index>.jsonです。 |
kotlin.build.reportで使用可能なオプションの一覧は以下のとおりです。
# 必須の出力形式。任意の組み合わせが可能です
kotlin.build.report.output=file,single_file,http,build_scan,json
# single_file 出力を使用する場合は必須。レポートの配置場所
# 非推奨の `kotlin.internal.single.build.metrics.file` プロパティの代わりに使用してください
kotlin.build.report.single_file=my/directory/path/some_filename
# 任意。ファイルベースまたはJSONレポートの出力ディレクトリ。デフォルト: build/reports/kotlin-build/
kotlin.build.report.file.output_dir=kotlin-reports
# 任意。ビルドレポートをマーキングするためのラベル(デバッグパラメータなど)
kotlin.build.report.label=some_labelHTTPにのみ適用可能なオプション:
# 必須。HTTP(S)ベースのレポートの送信先
kotlin.build.report.http.url=http://127.0.0.1:8080
# 任意。HTTPエンドポイントで認証が必要な場合のユーザー名とパスワード
kotlin.build.report.http.user=someUser
kotlin.build.report.http.password=somePassword
# 任意。ビルドのGitブランチ名をビルドレポートに追加
kotlin.build.report.http.include_git_branch.name=true|false
# 任意。コンパイラ引数をビルドレポートに追加
# プロジェクトに多数のモジュールが含まれている場合、レポート内のコンパイラ引数は非常に肥大化し、あまり役に立たない場合があります
kotlin.build.report.include_compiler_arguments=true|falseカスタム値の制限
ビルドスキャンの統計情報を収集するために、KotlinビルドレポートはGradleのカスタム値(custom values)を使用します。 ユーザー自身とさまざまなGradleプラグインの両方がカスタム値にデータを書き込むことができます。カスタム値の数には制限があります。 現在の最大カスタム値数については、Build scanプラグインドキュメントを参照してください。
大規模なプロジェクトの場合、そのようなカスタム値の数が非常に多くなることがあります。この数が制限を超えると、 ログに次のメッセージが表示されることがあります。
Maximum number of custom values (1,000) exceededKotlinプラグインが生成するカスタム値の数を減らすには、gradle.propertiesで次のプロパティを使用できます。
kotlin.build.report.build_scan.custom_values_limit=500プロジェクトおよびシステムプロパティの収集の無効化
HTTPビルド統計ログには、一部のプロジェクトおよびシステムプロパティが含まれる場合があります。これらのプロパティはビルドの動作を変更する可能性があるため、 ビルド統計にログとして記録しておくと便利です。 ただし、これらのプロパティにはパスワードやプロジェクトのフルパスなどの機密データが保存されている可能性があります。
gradle.propertiesにkotlin.build.report.http.verbose_environmentプロパティを追加することで、 これらの統計の収集を無効にできます。
JetBrainsがこれらの統計を収集することはありません。レポートの保存場所はユーザー自身が選択します。
次のステップ
以下の詳細についても参照してください。
