spm-build-analysis

SPM ビルド分析

パッケージ構成、プラグイン、または依存関係の設定が Xcode ビルドの低速化に影響している可能性がある場合に、このスキルを使用します。

基本ルール

• パッケージ分析は、依存関係の置き換えを義務づけるものではなく、まず証拠を集める作業として扱います。
• パッケージグラフの問題とプロジェクト設定の問題を区別します。
• 明示的な承認を得ずに、パッケージマニフェストや依存関係のソースを書き換えないでください。

調査対象

• Package.swift と Package.resolved
• ローカルパッケージとリモートパッケージ
• パッケージプラグインとビルドツールの使用状況
• バイナリターゲットの占有範囲
• 依存関係の階層、重複したインポート、潜在的な循環
• パッケージ関連の作業を示すビルドログや所要時間の概要

推奨前の確認

推奨にローカルパッケージを含める前に、そのパッケージが実際にプロジェクトの依存関係グラフに含まれていることを確認してください。Vendor/ ディレクトリに、どのターゲットにもリンクされていないパッケージが含まれている場合があります。

• project.pbxproj で、パッケージのパスを参照する XCLocalSwiftPackageReference エントリを確認します。
• XCSwiftPackageProductDependency エントリを確認し、そのパッケージのプロダクトが少なくとも 1 つのターゲットにリンクされていることを確かめます。
• ローカルパッケージがディスク上に存在していても、プロジェクトから参照されていない場合は、ビルド時間に関する推奨に含めないでください。

ブランチ追跡中の依存関係にバージョンの固定を推奨する場合：

• ヘルパースクリプトを使って、ブランチに固定されたすべての依存関係を一度にスキャンします：

  python3 scripts/check_spm_pins.py --project App.xcodeproj
  

  これにより、ブランチに固定された各パッケージに対して git ls-remote --tags を実行し、固定に利用できるタグがあるパッケージを報告します。
• タグがない場合は、再現性を確保するため、代わりに特定のコミットリビジョンハッシュへの固定を推奨します。
• 上流にタグがないためブランチに固定されているパッケージと、タグがあるものの意図的にブランチを追跡しているパッケージを区別して示します。

注目する領域

• パッケージグラフの構造と、変更によって下流で発生する作業の量
• ローカル開発および CI におけるプラグインのオーバーヘッド
• クリーンな環境で現れるチェックアウトやフェッチのコストを示す兆候
• 重複したモジュールのビルドを引き起こす設定の不一致
• 依存関係を共有しながら異なるマクロやオプションを使用するパッケージターゲットのリスク
• 依存関係の方向に関する違反（共有の下位レイヤーではなく、機能同士が依存し合っている）
• モジュール間の循環依存（共有するコントラクトをプロトコルモジュールに切り出します）
• サイズの大きすぎるモジュール（200 ファイル以上）によって、インクリメンタル再ビルドの範囲が広がる問題
• @_exported import を使用するアンブレラモジュールが、隠れた依存関係の連鎖を生み出す問題
• ビルドの並列処理を妨げる、インターフェースと実装の分離不足
• テスト対象のモジュールではなく、アプリターゲットに依存するテストターゲット
• Swift マクロによる再ビルドの連鎖：Swift マクロ（TCA、swift-syntax ベースのライブラリなど）を多用すると、マクロ展開によって下流のモジュールが無効化され、些細なソース変更がほぼ全体の再ビルドに波及することがあります
• 事前ビルド済みバイナリがない場合に swift-syntax がすべてのアーキテクチャ向けにビルドされ、クリーンビルドのオーバーヘッドが大幅に増える問題
• 複数プラットフォームのビルドによる増加：watchOS などの副次的なプラットフォームターゲットを追加すると、共有 SPM パッケージが複数回ビルドされ（例：iOS arm64、iOS x86_64、watchOS arm64）、SwiftCompile、SwiftEmitModule、ScanDependencies タスクが増加することがあります

モジュラー SDK 移行時の注意点

モノリシックなターゲットからモジュラーなマルチターゲット SDK（たとえば、単一の統合ライブラリを Core、RUM、Logs、Trace の各モジュールに置き換える場合）に依存関係を移行しても、ビルド時間が自動的に短縮されるわけではありません。モジュラーターゲットでは、各ターゲットを個別にコンパイル、スキャンし、モジュールを出力する必要があるため、SwiftCompile、SwiftEmitModule、ScanDependencies のタスク数が増加します。ビルド時間のトレードオフは、プロジェクトの並列処理の余力と、実際に必要なモジュラーターゲットの数によって変わります。

モジュラー SDK への移行を検討する際は、次の点に注意してください。

• 移行前後の SwiftCompile タスクの総数を比較します。
• ビルド速度向上を目的に移行を推奨する前に、両方の構成でベンチマークを実施します。
• 動機が API サーフェスの縮小（使用するものだけをインポートすること）である場合、インポートの適切さは改善されても、ビルド時間は変わらないか、長くなる可能性があることを明記します。
• ビルド速度向上を目的にモジュラー SDK への移行を推奨するのは、プロジェクトが現在、使用していないモノリシック SDK の大部分をコンパイルしており、モジュラー版ではその未使用部分を完全にスキップできる場合に限ります。

明示的なモジュール依存関係の観点

タイミング出力に同じモジュールが複数回表示される場合は、パッケージやターゲットの異なるオプションによって、追加のモジュールバリアントが強制されていないか調査します。ソースコードを少し削るよりも、オプションを統一するほうが重要な場合があります。

報告形式

各調査結果には、次の項目を含めます。

• 根拠
• 影響を受けるパッケージまたはプラグイン
• クリーンビルドとインクリメンタルビルドへの影響の見込み
• 関連する場合は CI への影響
• 影響の推定
• 承認の要否

主な問題がパッケージに関するものでない場合は、対象スキルの SKILL.md を読み、同じプロジェクトのコンテキストにそのワークフローを適用して、xcode-project-analyzer または xcode-compilation-analyzer に引き継ぎます。

追加リソース

• 詳細な監査チェックリストについては、references/spm-analysis-checks.md を参照してください。
• 共通の推奨事項の構成については、references/recommendation-format.md を参照してください。
• ソースの引用については、references/build-optimization-sources.md を参照してください。