# バッチ設計書 7-CI-unix.yml

## 概要

本ドキュメントは、libuvプロジェクトのUnix/Linux系プラットフォーム対応CI/CDワークフロー `.github/workflows/CI-unix.yml` の設計仕様を定義する。

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

`CI-unix.yml` は、GitHub Actionsで実行されるUnix/Linux系プラットフォームのCI/CDワークフローである。Linux（Autotools）、Android（エミュレータ）、macOS（CMake + Autotools）、iOS（Xcode）、クロスコンパイル（QEMU + 16種のアーキテクチャ）の各ターゲットに対して、ビルドとテストを自動実行する。

**業務上の目的・背景**：libuvは多数のUnix系プラットフォームとアーキテクチャをサポートしており、コード変更がこれらの環境で正常にビルド・動作することを保証する必要がある。本ワークフローは、Pull Requestやブランチへのpush時に自動的にビルド・テストを実行し、回帰バグの早期検出とプラットフォーム互換性の維持を実現する。

**バッチの実行タイミング**：Pull Request作成/更新時（docs/、src/win/、隠しファイルを除くパス変更時）、およびバージョンブランチ（v[0-9].*）やmasterブランチへのpush時に自動実行される。

**主要な処理内容**：
1. **build-linux**: Autotoolsビルド（autogen.sh + configure + make distcheck）
2. **build-android**: Android NDKクロスコンパイル + エミュレータテスト（API 30、x86_64、QEMU）
3. **build-macos**: CMakeビルド + テスト（macos-14、macos-15、macos-15-intel の3環境）+ Autotoolsビルド
4. **build-ios**: Xcode CMakeビルド（macos-14、macos-15、ビルドのみ・テストなし）
5. **build-cross-qemu**: 16種のクロスコンパイルターゲット（arm、armhf、aarch64、riscv64、ppc、ppc64、ppc64le、s390x、mips、mips64、mipsel、mips64el、u64 slots版4種）のQEMUエミュレーションビルド・テスト

**前後の処理との関連**：autogen.sh（No.1）をLinux/macOSビルドで使用する。CMakeLists.txt（No.4）をmacOS/iOS/Androidビルドで使用する。sanitizer.yml（No.9）と補完的な関係にある（本ワークフローは正常ビルド、sanitizer.ymlはメモリ安全性テスト）。

**影響範囲**：Unix/Linux系の全プラットフォームでのビルド・テスト結果に影響する。PRマージ可否の判断基準となる。

## バッチ種別

CI/CDワークフロー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（PR作成/更新、push） |
| 実行時刻 | イベント発生時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | pull_request（パスフィルタ付き）、push（v[0-9].*、master） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actionsランナー | ubuntu-latest、macos-14/15/15-intel、ubuntu-24.04 が利用可能であること |
| Android NDK | ubuntu-latestランナーにAndroid NDKがプリインストールされていること |
| KVMサポート | Androidエミュレータ実行にKVMが利用可能であること |
| クロスコンパイルツールチェーン | 各アーキテクチャ向けGCCがapt installで取得可能であること |

### 実行可否判定

パスフィルタにより、docs/配下のみの変更、src/win/配下のみの変更、隠しファイルのみの変更ではワークフローが実行されない（ただし本ワークフロー自身の変更は除く）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| （ワークフロー入力なし） | - | - | - | トリガーイベントにより自動実行 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| libuvリポジトリ全体 | Git | actions/checkout@v6 でチェックアウト |

## 出力仕様

### 出力データ

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

### 出力ファイル仕様

該当なし（CI/CDの実行結果はGitHub Actionsのインターフェースで確認）

## 処理フロー

### 処理シーケンス

```
1. build-linux ジョブ
   └─ checkout → autogen.sh → mkdir build → configure → make distcheck
2. build-android ジョブ
   └─ checkout → envinfo → KVM有効化 → Android Emulator起動
   └─ CMakeクロスビルド（Android NDK）→ termux-elf-cleaner → adb push → テスト実行
3. build-macos ジョブ（3環境マトリクス）
   └─ checkout → envinfo → ファイアウォール無効化 → brew install
   └─ CMake構成（Ninja）→ ビルド → platform_output → テスト実行
   └─ Autotoolsビルド（autogen.sh + configure + make）
4. build-ios ジョブ（2環境マトリクス）
   └─ checkout → CMake構成（Xcode、iOS SDK）→ ビルド
5. build-cross-qemu ジョブ（16環境マトリクス）
   └─ checkout → apt install（qemu-user、クロスコンパイラ）
   └─ CMake構成（QEMU=ON）→ ビルド → QEMU経由テスト実行
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[build-linux]
    A --> C[build-android]
    A --> D[build-macos x3]
    A --> E[build-ios x2]
    A --> F[build-cross-qemu x16]
    B --> B1[autogen.sh] --> B2[configure] --> B3[make distcheck]
    C --> C1[CMake NDKビルド] --> C2[エミュレータテスト]
    D --> D1[CMake Ninja ビルド] --> D2[ctest] --> D3[Autotools ビルド]
    E --> E1[CMake Xcode ビルド]
    F --> F1[クロスコンパイル] --> F2[QEMU テスト]
```

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

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

該当なし（本ワークフローはCI/CDパイプラインであり、データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ビルドエラー | ソースコードのコンパイルに失敗した場合 | ビルドログを確認し、コード修正を行う |
| - | テスト失敗 | テストケースが失敗した場合 | テストログを確認し、コード修正またはテスト修正を行う |
| - | エミュレータタイムアウト | Androidエミュレータの起動に失敗した場合 | ジョブを再実行する |
| - | QEMUエラー | クロスコンパイルバイナリのQEMU実行に失敗した場合 | ターゲットアーキテクチャ固有の問題を調査する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | ワークフローレベルでの自動リトライなし（手動で Re-run が可能） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

各ジョブは `fail-fast: false` で設定されているため（macOS、iOS、QEMU）、一つのマトリクス環境が失敗しても他の環境のテストは継続される。失敗時はGitHub ActionsのUIからログを確認する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 5ジョブ（Linux 1 + Android 1 + macOS 3 + iOS 2 + QEMU 16 = 23環境） |
| 目標処理時間 | 各ジョブ数分〜数十分（全体は並列実行） |
| メモリ使用量上限 | GitHub Actions ランナーのデフォルトリソース |

## 排他制御

各ジョブは独立したランナーで並列実行される。同一PRに対する複数実行はGitHub Actionsのデフォルト動作に従う。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルドログ | ビルド実行時 | CMake/Autotools のビルド出力 |
| テストログ | テスト実行時 | ctest -V または uv_run_tests_a の出力 |
| 環境情報 | envinfo実行時 | npx envinfo によるランナー環境情報 |
| platform_output | テスト前 | uv_run_tests platform_output によるプラットフォーム情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功/失敗 | 1つでも失敗 | GitHub PRステータスチェック |

## 備考

- build-macos のmacos-15/macos-15-intelではroot権限でテスト実行（`sudo UV_RUN_AS_ROOT=1 ctest -V`）
- build-android ではSELinuxをpermissiveモードに設定（`setenforce 0`）してテスト実行
- build-android ではtermux-elf-cleanerを使用してリンカバグを回避
- build-android ではUV_TEST_TIMEOUT_MULTIPLIER=5でテストタイムアウトを延長
- QEMU環境の "u64 slots" ターゲットは特定の内部データ構造のテストに使用
- パスフィルタにより、ドキュメントのみの変更やWindows固有コードの変更ではワークフローが実行されない
