mcpField
K
kotlin-tooling-native-build-performance

kotlin-tooling-native-build-performance

github.com/kotlin開発1.1k976 回インストール7 週間前に更新
リポジトリ

kotlin-tooling-native-build-performance について

Kotlin/Native 開発者向けのビルド性能診断スキルです。同じ条件で測定し、安全な変更を段階的に適用しながら、CI のリリース動作を維持します。

主な機能

  1. 01遅い状況とビルド段階を分類
  2. 02読み取り専用の静的監査スクリプトを実行
  3. 03同じ条件で変更前後を測定
  4. 04キャッシュとビルド対象を安全な順で調整
  5. 05CI のリリース成果物が変わらないことを確認

活用シーン

  1. 01ローカル iOS 開発ループの遅いタスクを特定
  2. 02CI での Kotlin/Native 再ダウンロードを調査
  3. 03不要なターゲットやリリースビルドを削減
  4. 04Gradle キャッシュと生成コードのコストを評価

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/kotlin/kotlin-agent-skills --skill kotlin-tooling-native-build-performance

インストール後、Claude Code で/kotlin-tooling-native-build-performanceを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
EVALUATION.md
references/
artifacts-and-targets.md
caching-and-gradle.md
experimental.md
exports-and-generated-code.md
scripts/
audit-native-build.sh

詳細

Kotlin/Native のビルドパフォーマンス

「iOS のビルドが遅い」という問題を、測定に基づく診断と少数の安全な修正に変えましょう。常に次の2つのルールを守ってください。

  1. 必要なリリース時の動作を犠牲にしてはいけません。ローカルの開発ループを高速化しても、CI が公開する成果物を変更してはいけません。
  2. 同じコマンド、同じビルド状態で、修正の前後を測定してください。測定していない修正は推測にすぎません。

ステップ 0：遅い状況を分類する

何かを編集する前に、4つの事実を確認します。場所（ローカルか CI か）、対象（デバッグのフィードバックループか、リリース／配布用成果物か）、状態（初回ビルド、クリーン、ウォーム、または変更なし）、フェーズ（ログ内でどのタスクが時間の大半を占めているか）です。そのうえで、主な症状に当てはまる項目を確認してください。

ビルドログの症状考えられる原因参照先
ローカルの開発ループで linkRelease* または *ReleaseXCFramework タスクが実行される開発用に配布成果物をビルドしている成果物とターゲット
CI の実行ごとに Kotlin/Native コンパイラーの配布物がダウンロードされる実行間で ~/.konan が保持されていないキャッシュと Gradle
最初のタスクが始まる前に長い待ち時間がある構成フェーズで、構成キャッシュがないキャッシュと Gradle
シミュレーターが1つだけ必要なのに、すべての iOS ターゲットがビルドされる範囲の広いタスク（build、assemble、assemble*XCFramework）または未使用のターゲット成果物とターゲット
compileKotlinIos* より前に ksp* タスクがあるネイティブのビルド経路で生成コードの処理が行われているエクスポートと生成コード
小さなソース変更で再コンパイルと再リンクがすべて発生するコンパイラーキャッシュが無効になっている、またはインクリメンタル処理が機能していないキャッシュと Gradle、実験的な設定
複数の link* タスクが同時に実行され、マシンに過大な負荷がかかるネイティブリンクが並列実行されているキャッシュと Gradle、ワーカー数の上限に関する注意

ステップ 1：監査と測定

  1. プロジェクトのルートから静的監査を実行します。

    scripts/audit-native-build.sh /path/to/project

    この監査は読み取り専用で、無効なキャッシュ、ローカルで範囲の広いタスク、transitiveExport、範囲の広い KSP 設定、CI での .konan キャッシュの不足について、修正内容を記載した参照ファイルを示す file:line 形式の指摘を出力します。 指摘は手がかりであり、結論ではありません。それぞれがプロジェクトの方針に合っているか確認してください。

  2. ユーザーが実際に待っているコマンドを特定します。スクリプト、CI のステップ、または Xcode のビルドフェーズ内で実行される Gradle の呼び出しです。自分で選んだタスクではなく、そのコマンドを最適化してください。

  3. 可能であれば、コマンドを2回実行します。初回のビルドでは Kotlin/Native のコンポーネントがダウンロードされ、キャッシュが作成されます。目安となるのは2回目以降の実行です。コンパイラーを原因と決めつける前に、タスクごとの所要時間を確認してください。

    kotlin.build.report.output=file   # writes build/reports/kotlin-build/

    Gradle の --scan や --profile も利用できます。

  4. ビルドを実行できない場合（macOS ホストがない、Xcode がないなど）は、代わりにログ、ビルドスキャン、またはチェックイン済みのメトリクスを分析し、結論が静的分析に基づくものであることを明記してください。

ステップ 2：安全な順序で修正する

修正を1つずつ適用し、都度測定し直してください。

  1. 健全なデフォルト設定に戻す — キャッシュやデーモンの回避策を取り除き、Gradle のビルドキャッシュと構成キャッシュを有効にし、CI で ~/.konan を温存し、Kotlin を更新します：キャッシュと Gradle
  2. フィードバックループに必要なものだけをビルドする — ループごとに特定のタスクを1つだけ実行し、適切な統合方法を使い、ターゲットの組み合わせを正当な理由に基づいて選びます： 成果物とターゲット
  3. エクスポートと生成コードのコストを削減する — transitiveExport を削除し、export(...) の範囲を絞り、必要なネイティブコンパイルに KSP の処理を限定します： エクスポートと生成コード
  4. 実験的な設定は最後に、ユーザーの同意を得て適用します： 実験的な設定

実例

Apple Silicon 搭載の Mac を使う開発者が、「shared-module の変更のたびに 12 分かかる」と訴えています。開発サイクルでは ./gradlew :shared:assembleXCFramework を実行しています。2 回目（ウォーム時）の実行でビルドスキャンを確認すると、次の結果が表示されます。

:shared:linkReleaseFrameworkIosArm64             348s
:shared:linkReleaseFrameworkIosX64               341s
:shared:compileKotlinIosX64                       96s
:shared:linkDebugFrameworkIosSimulatorArm64       41s
:shared:compileKotlinIosSimulatorArm64            38s
configuration phase                               64s

推論の流れ：

  • 開発サイクルは ローカル + デバッグ + ウォーム ですが、約 690 秒が linkRelease* に費やされています。リリースのリンクはデバッグより桁違いに遅く、必要とするのは CI のみです。ローカルのコマンドを :shared:linkDebugFrameworkIosSimulatorArm64 に置き換えます（Xcode がビルドを実行する場合は、Xcode の埋め込みタスクを使います）。(artifacts-and-targets)
  • iosX64 の処理はすべて Intel シミュレーター向けです。ターゲットを削除する前に、チームがまだ対応を続ける必要があるか確認します。(artifacts-and-targets)
  • org.gradle.configuration-cache=true を試した後は、毎回発生する 64 秒の設定処理が実行時間に影響しなくなります。(caching-and-gradle)
  • 変更後に想定される開発サイクルは、ウォームビルドでコンパイル約 40 秒 + リンク約 40 秒です。新しいコマンドを 2 回実行して比較し、確認します。
  • CI では assembleXCFramework を変更せずに使います。レポートにその旨を明記します。

検証

  • 正確なベースラインコマンドを再実行します。ウォームビルド同士を比較し、ウォームビルドとコールドビルドは比較しません。
  • 設定キャッシュを使用した 2 回目の実行で、キャッシュが再利用されていることを確認します。
  • ローカル開発ログに linkRelease*、*ReleaseXCFramework、削除したジェネレータータスクが含まれなくなったことを確認します。
  • CI で必要なすべてのリリース成果物が、変更なく引き続き生成されることを確認します。
  • テストに合格し、Xcode からアプリが引き続き実行できることを確認します。
  • scripts/audit-native-build.sh で、意識的に許容して文書化したもの以外の指摘がないことを確認します。

変更内容の報告

最後に、簡潔なパフォーマンス報告を添えます。

  • 時間がかかるシナリオ（ローカル／CI、デバッグ／リリース、コールド／ウォーム）と測定結果、または分析が静的解析である旨。
  • 各変更の内容と、リリース時の動作に影響しない理由。
  • 効果を確認するためにユーザーが実行できる変更前後のコマンド。
  • 残るトレードオフ：有効にした実験的フラグ、ポリシー上の前提に基づいて削除したターゲット、ワーカー数の制限、または後回しにした生成コードの処理。
  • 以下の関連する公式ドキュメントへのリンク。

公式ドキュメント

トピックリンク
Kotlin/Native のコンパイル時間の改善https://kotlinlang.org/docs/native-improving-compilation-time.html
Kotlin Gradle プラグインのコンパイルとキャッシュhttps://kotlinlang.org/docs/gradle-compilation-and-caches.html
iOS の統合方法https://kotlinlang.org/docs/multiplatform-ios-integration-overview.html
Xcode との直接統合https://kotlinlang.org/docs/multiplatform/multiplatform-direct-integration.html
最終的なネイティブバイナリと XCFramework のビルドhttps://kotlinlang.org/docs/multiplatform/multiplatform-build-native-binaries.html
Kotlin/Native のバイナリオプションhttps://kotlinlang.org/docs/native-binary-options.html
Kotlin Multiplatform での KSPhttps://kotlinlang.org/docs/ksp-multiplatform.html

コメント

Markdown 対応