axiom-build-performance

ビルドパフォーマンスの最適化

概要

Xcode のビルドパフォーマンスを体系的に分析し、最適化します。基本原則：最適化の前に測定し、まずクリティカルパスを最適化します。

このスキルを使うタイミング

• ビルド時間が大幅に増加したとき
• インクリメンタルビルドに時間がかかりすぎるとき
• ビルドタイムラインを分析したいとき
• コンパイルに時間がかかる Swift コードを特定する必要があるとき
• CI/CD のビルド時間を最適化するとき
• ビルドパフォーマンスの低下を調査するとき
• Xcode 26 のコンパイルキャッシュを有効にするとき
• 明示的にビルドされるモジュールのバリアントを減らすとき
• 3 フェーズのビルドプロセス（スキャン → モジュール → コンパイル）を理解するとき

すぐできる改善：まずエージェントを実行する

自動スキャンとすぐにできる改善には、次を実行します。

/axiom:optimize-build

build-optimizer エージェントは、よくある問題をスキャンし、すぐに適用できる修正を提示します。詳細な分析には、このスキルを使ってください。

ビルドパフォーマンス最適化のワークフロー

ステップ 1：ベースラインを測定する（必須）

理由：測定しなければ改善できません。ベースラインを取ることで、見かけだけの最適化を防げます。

# Clean build (eliminates all caching)
xcodebuild clean build -scheme YourScheme

# Measure time
time xcodebuild build -scheme YourScheme

# Or use Xcode UI
Product → Perform Action → Build with Timing Summary

記録する項目：

• ビルド全体の時間
• インクリメンタルビルドの時間（ファイルを 1 つ変更して再ビルド）
• 最も時間がかかるフェーズ（コンパイル、リンク、スクリプト）

ベースラインの例：

Clean build: 247 seconds
Incremental (1 file change): 12 seconds
Longest phase: Compile Swift sources (189s)

ステップ 2：ビルドタイムラインを分析する（Xcode 14 以降）

表示方法：

1. プロジェクトをビルドします（Cmd+B）
2. レポートナビゲーターを開きます（Cmd+9）
3. 最新のビルドを選択します
4. アシスタントエディタを表示します（Cmd+Option+Return）
5. ビルドタイムラインがビルドログの横に表示されます

確認する項目：

クリティカルパス（ビルド速度の上限）

クリティカルパスとは、CPU コア数に制限がない場合の最短ビルド時間です。依存関係のあるタスクのうち、最も長い連鎖によって決まります。

┌─────────────────────────────────────────┐
│  Critical Path: A → B → C → D (120s)   │
│                                         │
│  Task A: 30s  ─────────┐               │
│  Task B: 40s           ├─→ D: 20s      │
│  Task C: 30s  ─────────┘               │
│                                         │
│  Even with 100 CPUs, build takes 120s  │
└─────────────────────────────────────────┘

目標：依存関係を解消して、クリティカルパスを短縮します。

タイムラインで注意すべき兆候

縦方向の空白：タスクが入力待ちの状態です

Timeline:
████████░░░░░░░░████████  ← Bad: idle cores waiting
████████████████████████  ← Good: continuous work

横方向に長いバー：個々のタスクに時間がかかっています

Task A: ████████████████████ (45 seconds) ← Investigate
Task B: ███ (3 seconds)      ← Fine

ターゲットの逐次ビルド：ターゲットが不必要に待機しています

Framework: ████████░░░░░░░░░░ ← Waiting
App:       ░░░░░░░░░░████████ ← Delayed

Better (parallel):
Framework: ████████
App:       ░░░░████████████

ステップ 3：ボトルネックを特定する（判断フロー）

コンパイルが最も遅いフェーズですか？ ├─ はい → 型チェックのパフォーマンスを確認します（ステップ 4） └─ いいえ → リンクに時間がかかっていますか？ ├─ はい → リンクの依存関係を確認します（ステップ 5） └─ いいえ → スクリプトに時間がかかっていますか？ ├─ はい → ビルドフェーズのスクリプトを最適化します（ステップ 6） └─ いいえ → 並列化を確認します（ステップ 7）

最適化パターン

パターン 1：型チェックのパフォーマンス（効果：中〜大）

症状：「Compile Swift sources」にビルド時間の 50% 超がかかっています。

診断：

コンパイラの警告を有効にして、時間のかかる関数を見つけます。

// Add to Debug build settings → Other Swift Flags
-warn-long-function-bodies 100
-warn-long-expression-type-checking 100

ビルドすると、Xcode に警告が表示されます。

MyView.swift:42: Function body took 247ms to type-check (limit: 100ms)
LoginViewModel.swift:18: Expression took 156ms to type-check (limit: 100ms)

時間のかかる型チェックを修正する：

// ❌ SLOW - Complex type inference (247ms)
func calculateTotal(items: [Item]) -> Double {
    return items
        .filter { $0.isActive }
        .map { $0.price * $0.quantity }
        .reduce(0, +)
}

// ✅ FAST - Explicit types (12ms)
func calculateTotal(items: [Item]) -> Double {
    let activeItems: [Item] = items.filter { $0.isActive }
    let prices: [Double] = activeItems.map { $0.price * $0.quantity }
    let total: Double = prices.reduce(0, +)
    return total
}

時間がかかりやすいパターン：

• 中間型を指定しない複雑なチェーン処理
• 深くネストされたクロージャ
• 大きなリテラル（辞書、配列）
• 複雑な式での演算子オーバーロード

期待できる効果：該当するファイルのコンパイルが 10〜30% 高速化します。

---

パターン 2：ビルドフェーズのスクリプト最適化（効果：大）

症状：ビルドタイムラインで、デバッグビルド中に時間のかかるスクリプトフェーズが表示されます。

よくある原因：

• デバッグビルドで dSYM／Crashlytics のアップロードが実行される
• ビルドのたびにアセットが処理される
• キャッシュを使わないコード生成スクリプト

修正方法：スクリプトを条件付きで実行します

# ❌ BAD - Runs in ALL configurations (adds 6+ seconds to debug builds)
#!/bin/bash
firebase crashlytics upload-symbols

# ✅ GOOD - Skip in Debug
#!/bin/bash
if [ "${CONFIGURATION}" = "Release" ]; then
    firebase crashlytics upload-symbols
fi

# Example savings: 6.3 seconds per incremental debug build

スクリプトフェーズのサンドボックス化（Xcode 14 以降）

データ競合を防ぎ、並列化を向上させるには、有効にします。

Build Settings → User Script Sandboxing → YES

理由：入力と出力を明示的に宣言する必要が生じ、並列実行が可能になります。

# Script phase with proper inputs/outputs
Input Files:
  $(SRCROOT)/input.txt
  $(DERIVED_FILE_DIR)/checksum.txt

Output Files:
  $(DERIVED_FILE_DIR)/output.html

# Now Xcode knows dependencies and can parallelize safely

スクリプトの並列実行：

Build Settings → FUSE_BUILD_SCRIPT_PHASES → YES

⚠️ 警告：すべてのスクリプトで正しい入力と出力が宣言されている場合にのみ有効にしてください。そうしないと、データ競合が発生します。

期待できる効果：デバッグのインクリメンタルビルド 1 回につき 5〜10 秒短縮します。

---

パターン 3：コンパイルモードの設定（重要）

症状：インクリメンタルビルドでモジュール全体が再コンパイルされます。

現在の設定を確認：

# In project.pbxproj
grep "SWIFT_COMPILATION_MODE" project.pbxproj

最適な構成：

構成	設定	理由
Debug	singlefile（インクリメンタル）	変更されたファイルのみを再コンパイルします
Release	wholemodule	最適化を最大限に行います

// ❌ BAD - Whole module in Debug
SWIFT_COMPILATION_MODE = wholemodule; // ALL configs

// ✅ GOOD - Incremental for Debug
Debug: SWIFT_COMPILATION_MODE = singlefile;
Release: SWIFT_COMPILATION_MODE = wholemodule;

修正方法：

1. Project → Build Settings
2. フィルター：「Compilation Mode」
3. Debug を「Incremental」に設定します
4. Release を「Whole Module」に設定します

期待される効果：インクリメンタルなデバッグビルドが 40〜60％高速になります。

---

パターン 4：アクティブなアーキテクチャのみをビルド（効果大）

症状：デバッグビルドで複数のアーキテクチャ（x86_64 + arm64）向けにコンパイルされます。

確認：

grep "ONLY_ACTIVE_ARCH" project.pbxproj

修正：

構成	設定	理由
Debug	YES	現在のデバイス向け（arm64 または x86_64）のみビルドします
Release	NO	ユニバーサルバイナリをビルドします

修正方法：

1. Build Settings → 「Build Active Architecture Only」
2. Debug を YES に設定します
3. Release は NO のままにします

期待される効果：デバッグビルドが 40〜50％高速になります（アーキテクチャが半分になります）。

---

パターン 5：デバッグ情報形式（効果中）

症状：デバッグビルドで不要な dSYM が生成されます。

最適な構成：

構成	設定	理由
Debug	dwarf	デバッグ情報を埋め込み、より高速です
Release	dwarf-with-dsym	クラッシュレポート用に個別の dSYM を生成します

# Check current
grep "DEBUG_INFORMATION_FORMAT" project.pbxproj

修正方法：

1. Build Settings → 「Debug Information Format」
2. Debug を「DWARF」に設定します
3. Release を「DWARF with dSYM File」に設定します

期待される効果：デバッグビルドごとに 3〜5 秒短縮されます。

---

パターン 6：ターゲットの並列化（WWDC 2018-408）

症状：並列実行できるターゲットがあるにもかかわらず、Build Timeline ではターゲットが順次ビルドされています。

スキームの構成を確認：

1. Product → Scheme → Edit Scheme
2. Build タブ
3. 「Parallelize Build」チェックボックスがオンになっていることを確認します
4. ターゲットの順序が並列化を可能にしていることを確認します

依存関係グラフの例：

App ──┬──→ Framework A
      └──→ Framework B

Framework A ──→ Utilities
Framework B ──→ Utilities

タイムライン（不適切 - 直列）：

Utilities:   ████████░░░░░░░░░░░░░░
Framework A: ░░░░░░░░████████░░░░░░
Framework B: ░░░░░░░░░░░░░░░░████████
App:         ░░░░░░░░░░░░░░░░░░░░░░████

タイムライン（適切 - 並列）：

Utilities:   ████████
Framework A: ░░░░░░░░████████
Framework B: ░░░░░░░░████████
App:         ░░░░░░░░░░░░░░░░████

期待される効果：独立したターゲット数に比例します（例：2 つのターゲットを並列化すると約 2 倍高速になります）。

---

パターン 7：モジュール最適化の出力（Xcode 14 以降、Swift 5.7 以降）

概要：Swift モジュールはコンパイルとは別に生成されるため、後続のターゲットがより早く処理を開始できます。

変更前（Xcode 13）：

Framework: Compile ████████████ → Emit Module █
App:       ░░░░░░░░░░░░░░░░░░░░░░░░░█████████
           ↑
           Waiting for Framework compilation to finish

変更後（Xcode 14 以降）：

Framework: Compile ████████████
           Emit Module ███
App:       ░░░░░░███████████
           ↑
           Starts as soon as module emitted

自動適用：設定は不要です。Xcode 14 以降と Swift 5.7 以降で動作します。

期待される効果：複数ターゲットのビルドにおけるアイドル時間を 20〜40％削減します。

---

パターン 8：先行リンク（Xcode 14 以降）

概要：モジュールの準備ができていれば、すべてのコンパイルが完了する前にリンクを開始できます。

効果：依存関係チェーンのクリティカルパスをさらに短縮します。

自動適用：Xcode 14 以降で自動的に動作します。

---

パターン 9：コンパイルキャッシュ（Xcode 26 以降、重要）

概要：Xcode 26 では、クリーンビルドをまたいで以前にコンパイルした成果物を再利用するコンパイルキャッシュが導入されています。

ビルド設定：

Build Settings → COMPILATION_CACHE_ENABLE_CACHING → YES

仕組み：

• 入力ファイルの内容とコンパイラーフラグに基づいてコンパイル結果をキャッシュします
• クリーンビルドをまたいで動作します。xcodebuild clean の実行後でも、キャッシュされた成果物を再利用できます
• クリーンビルドが頻繁に行われる CI/CD で、ビルド時間を大幅に短縮します

有効にする場合：

• クリーンビルドを頻繁に行う CI/CD パイプライン
• ビルド成果物を共有するチーム
• 依存関係が安定しているプロジェクト

確認：

# Build with caching enabled
xcodebuild build -scheme YourScheme \
  COMPILATION_CACHE_ENABLE_CACHING=YES

# Check build log for cache information

現在の制限事項（Xcode 26）：

• Swift Package Manager の依存関係はまだキャッシュできません
• CompileStoryboard、CompileXIB、DataModelCompile、Ld タスクはキャッシュできません
• 初回実行時にはキャッシュの構築に時間がかかります

期待される効果：初回のキャッシュ構築後、クリーンビルドが 20〜40％高速になります（条件のよいプロジェクトでは最大 70％以上）。

---

パターン 10：明示的にビルドされるモジュール（Xcode 16 以降、影響大）

概要：Xcode はモジュールのコンパイルを、暗黙的なオンデマンドのコンパイルではなく、明示的なビルドタスクに分割します。Xcode 26 では Swift でデフォルトで有効になっています。

暗黙的なモジュールの問題（Xcode 16 より前）：

コンパイラがインポートに遭遇すると、その場でモジュールをビルドします：

Compile A.swift ─── needs UIKit ───→ (builds UIKit.pcm) ───→ continues
Compile B.swift ─── needs UIKit ───→ (waits for A to finish) ───→ uses cached
Compile C.swift ─── needs UIKit ───→ (waits) ───→ uses cached

問題点：

• 同じモジュールを待っている他のタスクが、1 つのタスクによってブロックされます
• 非決定的です。最初に到達したタスクがビルドします
• ビルドの失敗を再現しにくくなります（タスクの実行順序によって異なるため）

明示的にビルドされるモジュールによる解決策：

Xcode はコンパイルを 3 つのフェーズに分割するようになりました：

Phase 1: SCAN          Phase 2: BUILD MODULES    Phase 3: COMPILE
┌──────────────────┐   ┌──────────────────────┐   ┌──────────────────┐
│ Scan A.swift     │   │ Build UIKit.pcm      │   │ Compile A.swift  │
│ Scan B.swift     │ → │ Build Foundation.pcm │ → │ Compile B.swift  │
│ Scan C.swift     │   │ Build SwiftUI.pcm    │   │ Compile C.swift  │
└──────────────────┘   └──────────────────────┘   └──────────────────┘
     (fast)                 (parallel)                (parallel)

メリット：

• より信頼性の高いビルド：依存関係が正確になり、決定的なビルドグラフを実現できます
• より効率的なスケジューリング：ビルドシステムが必要なものを正確に把握できます
• デバッグの改善：デバッガーがビルド済みのモジュールを再利用します（個別の再ビルドは不要です）
• モジュールタスクの可視化：ビルドログで「Compile Clang Module」と「Compile Swift Module」を確認できます

有効化／無効化（必要に応じて）：

Build Settings → Explicitly Built Modules → YES (default in Xcode 26 for Swift)

モジュールバリアント（WWDC 2024-10171）

同じモジュールが、異なる設定で複数回ビルドされることがあります：

Build Log:
  Compile Clang module 'UIKit' (hash: abc123)   ← Variant 1
  Compile Clang module 'UIKit' (hash: def456)   ← Variant 2
  Compile Swift module 'UIKit' (hash: ghi789)   ← Variant 3

バリアントが発生する一般的な原因：

• ターゲット間でプリプロセッサマクロが異なる
• C と Objective-C の言語モードが混在している
• C 言語のバージョンが異なる（C11 と C17 など）
• 一部のターゲットで ARC が無効になっている

バリアントを診断する：

1. Timing Summary を使用してビルドします：Product → Perform Action → Build with Timing Summary
2. ビルドログをフィルタリングします：フィルターボックスに「modules report」と入力します
3. バリアント数を示す Clang および Swift モジュールのレポートを確認します

バリアントを減らす（プロジェクト／ワークスペースレベルで設定を統一します）：

# Check for macro differences
grep "GCC_PREPROCESSOR_DEFINITIONS" project.pbxproj

# Move target-specific macros to project level where possible
Project → Build Settings → Preprocessor Macros → [unify here]

例（WWDC 2024-10171 より）：

Before: 4 UIKit variants (2 Swift × 2 Clang)
After:  2 UIKit variants (unified settings)
Impact: Fewer module builds = faster incremental builds

期待される効果：モジュールの重複コンパイルを減らし、ビルドを 10～30％高速化します。

注：Swift Build（Xcode 26 以降）：Xcode は現在、Apple のオープンソースビルドエンジンである Swift Build を使用します。これにより、より予測可能なビルド、SPM との連携の強化、クロスプラットフォーム対応（Linux、Windows、Android）が実現します。設定は不要です。

---

測定と検証

変更前後の比較

必須の手順：

1. ベースライン（変更前）：

   xcodebuild clean build -scheme YourScheme 2>&1 | tee baseline.log
   

2. 一度に 1 つの最適化を適用します

3. 改善を測定します：

   xcodebuild clean build -scheme YourScheme 2>&1 | tee optimized.log
   

4. 比較します：

   # Extract build time from logs
   grep "Build succeeded" baseline.log
   grep "Build succeeded" optimized.log
   

例：

Baseline:   Build succeeded (247.3 seconds)
Optimized:  Build succeeded (156.8 seconds)
Improvement: 90.5 seconds (36.6% faster)

ビルドタイムラインの目視確認

最適化前：

• 空白の縦方向の領域（アイドル状態のコア）を探します
• 長い横棒（遅いタスク）を確認します
• ターゲットが順番にビルドされているか確認します

最適化後：

• タイムラインがより「埋まっている」はずです
• 横棒が短くなります
• ターゲットが並列でビルドされます

クリティカルパス：目に見えて短くなっているはずです。

---

実際の最適化例

例 1：大規模な iOS アプリ（ソースファイル 50 個以上）

ベースライン：

• クリーンビルド：247 秒
• インクリメンタルビルド（1 ファイル）：12 秒

適用した最適化：

1. デバッグコンパイルモード：singlefile（89 秒短縮）
2. Build Active Architecture：YES（45 秒短縮）
3. 条件付き dSYM アップロードスクリプト（インクリメンタルビルドごとに 6.3 秒短縮）

結果：

• クリーンビルド：156 秒（36％高速化）
• インクリメンタルビルド：5.7 秒（52％高速化）

---

例 2：複数のフレームワークを含むプロジェクト

ベースライン：

• 5 つのフレームワークを順番にビルド
• 合計：189 秒

適用した最適化：

1. スキームで並列ビルドを有効化
2. 不要な依存関係を修正
3. モジュール最適化を出力（Xcode 14 では自動）

結果：

• 合計：94 秒（50％高速化）
• クリティカルパスを 189 秒から 94 秒に短縮

---

よくある落とし穴

落とし穴 1：測定せずに最適化する

誤り：「これなら効果がありそう」→変更を加える→測定しない。

問題点：プラセボ効果、時間の浪費、実際の性能低下の見落としにつながります。

対策：変更前に必ず測定し、1 つだけ変更してから、変更後に測定します。

---

落とし穴 2：リリースビルドを速度優先で最適化する

間違い：「ビルドを高速化する」ために、Release をインクリメンタルコンパイルに設定する。

問題点：リリースビルドでは、ビルド速度ではなく実行時のパフォーマンスを最適化する必要があります。Release ビルドはユーザーに提供するものです。

対処法：速度を最適化するのは Debug ビルドだけにします。Release は実行時のパフォーマンスを重視した設定にします。

---

落とし穴 3：並列化のために依存関係を壊す

間違い：「ビルドを並列化する」ために、本来必要な依存関係を削除する。

問題点：ビルドエラー、未定義動作、競合状態が発生します。

対処法：本当に独立しているターゲットだけを並列化します。Build Timeline を使って、安全に並列化できる箇所を特定します。

---

落とし穴 4：サンドボックス化せずに FUSE_BUILD_SCRIPT_PHASES を有効にする

間違い：スクリプトの並列実行を有効にしても、入力／出力を宣言しない。

問題点：データ競合、非決定的なビルド失敗、不正なビルドが発生します。

対処法：まず ENABLE_USER_SCRIPT_SANDBOXING = YES を有効にしてすべてのエラーを修正し、その後で FUSE_BUILD_SCRIPT_PHASES を有効にします。

---

トラブルシューティング

問題：最適化後もビルドが遅い

確認項目：

1. 計測前にクリーンビルドしましたか？（xcodebuild clean）
2. 適切なビルドを計測していますか？（Debug と Release）
3. マシンでサーマルスロットリングが発生していませんか？（アクティビティモニタ → CPU タブ）
4. CPU を使用しているほかのアプリはありませんか？（計測中は Xcode、Docker、VM を終了します）

---

問題：Build Timeline に並列化が表示されない

確認項目：

1. Scheme → Parallelize Build にチェックが入っていますか？
2. ターゲットは実際に独立していますか？（依存関係グラフを確認します）
3. ターゲットに不要な明示的依存関係がありませんか？

---

問題：型チェックの警告が表示されない

確認項目：

1. 正しい構成にフラグを追加しましたか？（Release ではなく Debug）
2. 構文は正しいですか？ -warn-long-function-bodies 100（ハイフンを使用）
3. 正しい Scheme をビルドしていますか？
4. 再コンパイルを強制するためにクリーンビルドしましたか？

---

高度な内容：ビルドログの分析

コンパイル時間を抽出する

# Find slowest files to compile
xcodebuild -workspace YourApp.xcworkspace \
  -scheme YourScheme \
  clean build \
  OTHER_SWIFT_FLAGS="-Xfrontend -debug-time-function-bodies" 2>&1 | \
  grep ".[0-9]ms" | \
  sort -nr | \
  head -20

出力：

247.3ms  MyViewModel.swift:42:1  func calculateTotal
156.8ms  LoginView.swift:18:3    var body
89.2ms   NetworkManager.swift:67:1  func handleResponse
...

対応：最も時間のかかる関数に明示的な型を追加します。

---

ビルドフェーズの所要時間を抽出する

# From build log
Build target 'MyApp' (project 'MyApp')
    Compile Swift source files (128.4 seconds)
    Link MyApp (12.3 seconds)
    Run custom shell script (6.7 seconds)

対応：最も時間のかかるフェーズから最適化します。

---

チェックリスト：ビルドパフォーマンスの監査

ビルドが最適化されたと判断する前に、次の項目を確認してください。

計測

• ベースラインを計測した（クリーンビルド＋インクリメンタルビルド）
• Build Timeline で改善を確認した
• ベースラインと最適化後の比較を記録した

コンパイル設定

• Debug でインクリメンタルコンパイルを使用している
• Build Active Architecture = YES（Debug のみ）
• Debug で DWARF を使用している（dSYM ではない）
• 型チェックの警告を有効にした
• 型チェックに時間のかかる関数（>100ms）を修正した

並列化

• Scheme で Parallelize Build を有効にした
• 不要なターゲット依存関係がない
• ビルドフェーズのスクリプトは条件付きで実行される（可能な場合は Debug でスキップ）
• スクリプトを並列実行する場合は、スクリプトのサンドボックス化を有効にした

Xcode 26 以降（該当する場合）

• CI/CD 用にコンパイルキャッシュを有効にした（COMPILATION_CACHE_ENABLE_CACHING）
• モジュールバリアントを確認した（ビルドログの Modules Report、パターン 10 を参照）
• モジュールバリアントを減らすため、プロジェクトレベルでビルド設定を統一した
• Explicitly Built Modules を有効にした（Xcode 26 の Swift ではデフォルト）

---

リソース

WWDC：2018-408、2022-110364、2024-10171、2025-247

ドキュメント：/xcode/improving-the-speed-of-incremental-builds、/xcode/building-your-project-with-explicit-module-dependencies

ツール：Xcode Build Timeline（Xcode 14 以降）、Build with Timing Summary（Product → Perform Action）、Modules Report（Xcode 16 以降）、Instruments Time Profiler

---

覚えておいてください：ビルドパフォーマンスの最適化では、体系的な計測と的を絞った改善が重要です。まずクリティカルパスを最適化し、すべてを計測して、Build Timeline で改善を確認してください。