# バッチ設計書 28-build.yml

## 概要

本ドキュメントは、Dear ImGuiプロジェクトのマルチプラットフォームビルドおよびテストを実行するGitHub Actionsワークフロー `build.yml` の設計書です。

### 本バッチの処理概要

このワークフローは、Dear ImGuiライブラリとそのサンプルアプリケーションを、Windows、Linux、macOS、iOS、Emscripten、Androidの各プラットフォームでビルドし、Windows/Linuxではテストスイートも実行します。

**業務上の目的・背景**：継続的インテグレーション（CI）はソフトウェア開発において品質を維持するために不可欠です。Dear ImGuiは多数のプラットフォームとグラフィックスバックエンドをサポートしているため、各プルリクエストやコミット時に自動的にビルドとテストを実行することで、リグレッションを早期に検出し、コードの品質を保証します。

**バッチの実行タイミング**：push、pull_request、またはscheduled/manualワークフローからのトリガー（workflow_run）時に実行されます。

**主要な処理内容**：
1. Windows環境でのMSVC/MinGWビルド（32bit/64bit）
2. Linux環境でのGCC/Clangビルド（32bit/64bit）
3. macOS環境でのClangビルド
4. iOS環境でのXcodeビルド
5. Emscripten環境でのWebAssemblyビルド
6. Android環境でのGradleビルド
7. Windows/Linuxでのテストスイート実行

**前後の処理との関連**：scheduled.yml や manual.yml からトリガーされることで、定期実行や手動実行のフルビルドを実現します。また、static-analysis.yml はこのワークフローの実行をトリガーとして静的解析を実行します。

**影響範囲**：リポジトリのmaster/dockingブランチへのプッシュ、プルリクエスト、または関連ワークフローからのトリガー時に全プラットフォームのビルドとテストが実行されます。

## バッチ種別

GitHub Actionsワークフロー（CI/CDパイプライン）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | push/pull_request時、またはworkflow_runトリガー時 |
| 実行時刻 | イベント発生時 |
| 実行曜日 | 任意（イベント駆動） |
| 実行日 | 任意（イベント駆動） |
| トリガー | push / pull_request / workflow_run |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | GitHub Actionsが有効なリポジトリであること |
| ブランチ | master または docking ブランチ（workflow_runの場合） |
| シークレット | テストスイート用リポジトリへのアクセス権（imgui_test_engine） |

### 実行可否判定

イベント（push、pull_request、workflow_run）発生時に自動的に実行されます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| github.event_name | 文字列 | Yes | - | トリガーイベント名（条件分岐に使用） |
| secrets.PVS_STUDIO_LICENSE | シークレット | No | - | PVS-Studio静的解析用ライセンス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリコード | Git | ImGuiソースコードとサンプル |
| imgui_test_engine | Git | テストスイート用外部リポジトリ |
| SDL2/SDL3ライブラリ | ZIP | Windowsビルド用依存ライブラリ |
| Vulkan SDK | ZIP | Windowsビルド用依存ライブラリ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actionsログ | テキスト | ビルド・テスト結果のログ |
| ビルドアーティファクト | バイナリ | コンパイルされた実行ファイル（一時的） |
| テスト結果 | テキスト | テストスイートの実行結果 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各サンプルの実行ファイル |
| 出力先 | GitHub Actionsワーカー上の一時ディレクトリ |
| 文字コード | バイナリ |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. ジョブ: Build-Windows
   ├─ チェックアウト
   ├─ 依存関係インストール（SDL2、SDL3、Vulkan SDK）
   ├─ プロジェクトファイル修正（PlatformToolset更新）
   ├─ MinGWビルド（example_null）
   ├─ MSVCビルド（example_null、各種サンプル）
   └─ Win32/Win64サンプルビルド

2. ジョブ: Build-Linux
   ├─ チェックアウト
   ├─ 依存関係インストール（apt-get）
   ├─ GCC/Clangビルド（32bit/64bit）
   ├─ 各種設定でのビルド検証
   └─ サンプルビルド

3. ジョブ: Build-MacOS
   ├─ チェックアウト
   ├─ 依存関係インストール（brew）
   ├─ Clangビルド
   └─ サンプルビルド（GLFW、SDL、Metal）

4. ジョブ: Build-iOS
   ├─ チェックアウト
   └─ Xcodeビルド

5. ジョブ: Build-Emscripten
   ├─ チェックアウト
   ├─ Emscripten SDK インストール
   └─ WebAssemblyビルド

6. ジョブ: Build-Android
   ├─ チェックアウト
   └─ Gradleビルド

7. ジョブ: Test-Windows
   ├─ チェックアウト（imgui + imgui_test_engine）
   ├─ テストスイートビルド
   └─ テスト実行

8. ジョブ: Test-Linux
   ├─ チェックアウト（imgui + imgui_test_engine）
   ├─ テストスイートビルド
   └─ テスト実行
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B{トリガー種別}
    B -->|push/PR| C[全ジョブ実行]
    B -->|workflow_run| D[全ジョブ実行+追加ビルド]

    C --> E[Build-Windows]
    C --> F[Build-Linux]
    C --> G[Build-MacOS]
    C --> H[Build-iOS]
    C --> I[Build-Emscripten]
    C --> J[Build-Android]
    C --> K[Test-Windows]
    C --> L[Test-Linux]

    E --> M{全ジョブ完了?}
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    L --> M

    M -->|成功| N[ワークフロー成功]
    M -->|失敗| O[ワークフロー失敗]
```

## データベース操作仕様

### 操作別データベース影響一覧

本ワークフローはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ビルドエラー | コンパイルエラー | ソースコードにエラーがある | ソースコードを修正してプッシュ |
| テストエラー | テスト失敗 | テストケースが失敗 | 失敗したテストを確認して修正 |
| 依存関係エラー | インストールエラー | 外部ライブラリの取得失敗 | ネットワークを確認、URLを更新 |
| タイムアウト | 実行時間超過 | ビルドまたはテストが長時間 | 処理を最適化 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | GitHub Actions標準（手動再実行） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 一時的なネットワークエラー等 |

### 障害時対応

1. GitHub Actionsのログを確認
2. 失敗したステップを特定
3. ローカルで再現テスト
4. 修正をコミット・プッシュ

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ワークフロー実行あたり複数ジョブ |
| 目標処理時間 | 全ジョブ合計30分〜1時間程度 |
| メモリ使用量上限 | GitHub Actionsランナー依存 |

## 排他制御

同一ブランチへの複数のプッシュがある場合、最新のワークフロー実行が優先されます（GitHub Actions標準動作）。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ステップログ | 各ステップ実行時 | コマンド出力 |
| ビルドログ | ビルド時 | コンパイラ出力 |
| テストログ | テスト時 | テスト結果 |
| エラーログ | エラー発生時 | エラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | 1回 | GitHubプルリクエスト/コミットステータス |
| テスト失敗 | 1回 | GitHubプルリクエスト/コミットステータス |

## 備考

- windows-2025ランナーを使用してVisual Studio 2022環境でビルドします。
- workflow_runイベント時のみ実行される追加のビルドステップがあります（Win32サンプル等）。
- imgui_test_engineリポジトリはプライベートリポジトリの可能性があるため、continue-on-errorが設定されています。
- PlatformToolsetはv143（VS2022）に自動更新されます。
- macOSのテストはコメントアウトされています。
