# バッチ設計書 38-Build & Test（build.yml）

## 概要

本ドキュメントは、mrubyプロジェクトにおけるGitHub Actionsワークフロー `Build & Test`（build.yml）のバッチ設計書である。push/PR時にGCC/Clangで複数OS・コンパイラの組み合わせでビルドとテストを実行するCI/CDパイプラインについて記述する。

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

`Build & Test` ワークフローは、GitHub Actionsで定義されたCI/CDパイプラインであり、コードのpushまたはプルリクエスト作成時に自動的にトリガーされ、複数のOS・コンパイラの組み合わせ（マトリクスビルド）でmrubyのビルドとテストを実行する。GCC-CLANG、Cosmopolitan、Windows-VCの3つのジョブで構成される。

**業務上の目的・背景**：mrubyはクロスプラットフォーム対応のRuby実装であるため、複数のOS（Ubuntu、macOS、Windows）および複数のコンパイラ（GCC、Clang、MSVC）での動作保証が必要である。本ワークフローにより、全てのサポート対象環境でのビルドとテストの自動検証を行い、プラットフォーム固有のバグを早期に検出する。

**バッチの実行タイミング**：GitHubリポジトリへのpush時およびプルリクエスト作成・更新時に自動実行される。

**主要な処理内容**：
1. GCC-CLANGジョブ：8つのマトリクスパターン（Ubuntu/macOS/Windows x GCC/Clang）でビルドとテストを実行
2. Cosmopolitanジョブ：cosmocc（Cosmopolitan Libc）を使用したクロスプラットフォームビルドとテスト
3. Windows-VCジョブ：Visual Studio 2022のMSVCコンパイラでビルドとテスト

**前後の処理との関連**：本ワークフローはリポジトリへのpush/PR時に自動実行される。No.39 Coverage（coverage.yml）はpush時のみに実行されるカバレッジ測定ワークフローである。

**影響範囲**：GitHub Actions上でのCI/CD実行のみ。リポジトリのコードには影響しない。PRのステータスチェックとして機能する。

## バッチ種別

CI/CDパイプライン（ビルド・テスト）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（push/PR時） |
| 実行時刻 | イベント発生時 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | push、pull_request |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions | GitHubリポジトリでActionsが有効であること |
| ランナー | ubuntu-24.04、ubuntu-22.04、macos-15、macos-14、windows-2025、windows-2022のランナーが利用可能であること |
| Ruby | 各ランナーにRubyがプリインストールされていること |

### 実行可否判定

pushまたはpull_requestイベントが発生した場合に自動実行される。Cosmopolitanジョブのcosmocc取得はキャッシュが使用される（キー: `cosmocc-${{ runner.os }}-20260104`）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| MRUBY_CONFIG | 環境変数 | Yes | ci/gcc-clang（GCC-CLANG）、ci/msvc（Windows-VC）、cosmopolitan（Cosmopolitan） | mrubyビルド設定ファイルパス |
| CC | 環境変数 | Yes | マトリクス定義による | Cコンパイラ（gcc/clang） |
| CXX | 環境変数 | Yes | マトリクス定義による | C++コンパイラ（g++/clang++） |
| LD | 環境変数 | Yes | マトリクス定義による | リンカ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .github/workflows/build.yml | YAML | ワークフロー定義 |
| mrubyソースコード一式 | C/Ruby | ビルド・テスト対象 |
| ci/gcc-clang | Ruby | GCC/Clang向けビルド設定 |
| ci/msvc | Ruby | MSVC向けビルド設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | ビルド・テスト実行ログ |
| GitHub ステータスチェック | ステータス | 各ジョブの成功/失敗ステータス |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | N/A（ログ出力のみ） |
| 出力先 | GitHub Actions UI |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. トリガー検知
   └─ push/pull_requestイベントの検知
2. GCC-CLANGジョブ（8並列・最大並列数8）
   2a. コードチェックアウト
   2b. Rubyバージョン確認
   2c. コンパイラバージョン確認
   2d. rake -m test:run:serial 実行（ビルド＆テスト）
3. Cosmopolitanジョブ
   3a. コードチェックアウト
   3b. Rubyバージョン確認
   3c. cosmoccキャッシュ確認・ダウンロード
   3d. COSMO_ROOT指定でrake -m test:run:serial 実行
4. Windows-VCジョブ
   4a. コードチェックアウト
   4b. Rubyバージョン確認
   4c. vcvars64.batでVC環境設定
   4d. rake -m test:run:serial 実行
```

### フローチャート

```mermaid
flowchart TD
    A[push/PR イベント] --> B[ワークフロー開始]
    B --> C[GCC-CLANGジョブ 8マトリクス]
    B --> D[Cosmopolitanジョブ]
    B --> E[Windows-VCジョブ]
    C --> C1[チェックアウト]
    C1 --> C2[Ruby/コンパイラバージョン確認]
    C2 --> C3[rake -m test:run:serial]
    C3 --> C4{テスト結果}
    D --> D1[チェックアウト]
    D1 --> D2[cosmoccキャッシュ/ダウンロード]
    D2 --> D3[rake -m test:run:serial MRUBY_CONFIG=cosmopolitan]
    D3 --> D4{テスト結果}
    E --> E1[チェックアウト]
    E1 --> E2[vcvars64.bat実行]
    E2 --> E3[rake -m test:run:serial]
    E3 --> E4{テスト結果}
    C4 --> F[全ジョブ完了]
    D4 --> F
    E4 --> F
```

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

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

本バッチではデータベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ジョブ失敗 | ビルドエラー | コンパイルエラー | ソースコードを修正してpush |
| ジョブ失敗 | テスト失敗 | テストケース失敗 | テスト結果を確認し修正してpush |
| ジョブ失敗 | cosmocc取得失敗 | ダウンロードエラー | ネットワーク状態を確認、再実行 |
| ジョブ失敗 | タイムアウト | 処理時間超過 | ジョブのタイムアウト設定を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（GitHub Actions標準動作、手動で再実行可能） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

ジョブ失敗時はGitHub Actionsのログを確認し、失敗したステップを特定する。GitHub UIから手動で再実行が可能。fail-fast: falseのため、1つのマトリクスが失敗しても他のマトリクスは継続実行される。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベーストランザクションなし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全マトリクスパターン（GCC-CLANG: 8、Cosmopolitan: 1、Windows-VC: 1） |
| 目標処理時間 | GCC-CLANG: 10分以内、Cosmopolitan: 15分以内、Windows-VC: 10分以内 |
| メモリ使用量上限 | GitHub Actionsランナーのデフォルト値 |

## 排他制御

GitHub Actionsの同一ワークフローは複数同時実行可能。ただし、max-parallel: 8の制限により、GCC-CLANGジョブは最大8並列で実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | チェックアウト情報、Rubyバージョン、コンパイラバージョン |
| 進捗ログ | ビルド・テスト中 | コンパイル進捗、テスト実行状況 |
| 終了ログ | ジョブ完了時 | テスト結果サマリー |
| エラーログ | エラー発生時 | コンパイルエラー・テスト失敗詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ実行時間 | GCC-CLANG: 10分、Cosmopolitan: 15分、Windows-VC: 10分 | GitHub Actions UI |
| ジョブ失敗 | 1件以上 | GitHub通知、PRステータスチェック |

## 備考

- `permissions: contents: read` でリポジトリの読み取り権限のみが付与される
- GCC-CLANGジョブのマトリクス構成:
  - ubuntu-24.04: gcc/clang
  - ubuntu-22.04: gcc/clang
  - macos-15: clang
  - macos-14: clang
  - windows-2025: mingw-gcc
  - windows-2022: mingw-gcc
- `fail-fast: false` により、1つのマトリクスが失敗しても他は継続実行される
- Cosmopolitanジョブではcosmocc（Cosmopolitan Libc用コンパイラ）をキャッシュして再利用する
- Windows-VCジョブではVisual Studio 2022 Enterpriseのvcvars64.batを使用してMSVC環境を設定する
- 全ジョブで `rake -m test:run:serial` を実行（`-m` はマルチタスク有効化）
