# バッチ設計書 8-CI-win.yml

## 概要

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

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

`CI-win.yml` は、GitHub Actionsで実行されるWindows系プラットフォームのCI/CDワークフローである。Visual Studio 2022（複数アーキテクチャ）によるネイティブビルド・テストと、MinGWクロスコンパイル（Linux上でのビルド + Windows上でのテスト）の2つのビルドパイプラインを提供する。

**業務上の目的・背景**：libuvはWindowsプラットフォームを第一級のターゲットとしてサポートしている。Win32（x86）、x64、ARM64の各アーキテクチャおよびASAN/UBSAN付きビルドの検証が必要であり、また MinGWクロスコンパイルによるGNU互換環境でのWindows向けビルドの検証も重要である。本ワークフローはこれらの全Windows系ビルド構成の品質を保証する。

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

**主要な処理内容**：
1. **build-windows**: Visual Studio 17 2022 による6つの構成でのビルド・テスト
   - Win32（x86）、x64、x64+ASAN、x64+UBSAN、ARM64（ビルドのみ）、x64 on Server 2025
2. **build-mingw**: Ubuntu上でMinGWクロスコンパイル（i686、x86_64）、ビルド成果物をアーティファクトとしてアップロード
3. **test-mingw**: Windows上でMinGWビルド成果物をダウンロードしてテスト実行

**前後の処理との関連**：CMakeLists.txt（No.4）を使用してCMakeビルドを実行する。sanitizer.yml（No.9）のWindows UBSANテストと補完的な関係にある。

**影響範囲**：Windows系の全アーキテクチャ（Win32、x64、ARM64）およびMinGW環境でのビルド・テスト結果に影響する。PRマージ可否の判断基準となる。

## バッチ種別

CI/CDワークフロー

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actionsランナー | windows-2022、windows-2025、ubuntu-latest が利用可能であること |
| Visual Studio 2022 | windows-2022/2025ランナーにVS 2022がプリインストールされていること |
| MinGW-w64 | ubuntu-latestランナーでapt installにより取得可能であること |

### 実行可否判定

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| libuvリポジトリ全体 | Git | actions/checkout@v6 でチェックアウト |
| cmake-toolchains/cross-mingw32.cmake | CMakeツールチェーンファイル | MinGWクロスコンパイル用ツールチェーン設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | ビルド・テスト結果のログ |
| GitHub PR ステータスチェック | ステータス | 各ジョブの成功/失敗ステータス |
| mingw-{arch} アーティファクト | アーカイブ | MinGWビルド成果物（2日間保持） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | mingw-i686、mingw-x86_64（アーティファクト名） |
| 出力先 | GitHub Actionsアーティファクトストレージ |
| 保持期間 | 2日間（retention-days: 2） |

## 処理フロー

### 処理シーケンス

```
1. build-windows ジョブ（6環境マトリクス）
   └─ checkout → CMake構成（VS 2022ジェネレータ） → ビルド（RelWithDebInfo）
   └─ ASAN構成: *.exeと*.dllをRelWithDebInfoにコピー
   └─ ARM64以外: platform_output_a、platform_output 実行
   └─ ASAN/ARM64以外: ctest -C RelWithDebInfo -V
   └─ ASAN構成: uv_run_tests_a.exe のみ実行
2. build-mingw ジョブ（2環境マトリクス）
   └─ checkout → apt install mingw-w64 ninja-build
   └─ CMake構成（Ninja、MinGWツールチェーン） → ビルド → インストール
   └─ テストバイナリ・DLL・テストフィクスチャをパッケージング
   └─ アーティファクトアップロード（retention-days: 2）
3. test-mingw ジョブ（2環境マトリクス、build-mingwに依存）
   └─ アーティファクトダウンロード → uv_run_tests_a.exe 実行 → uv_run_tests.exe 実行
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[build-windows x6]
    A --> C[build-mingw x2]
    B --> B1[CMake VS 2022 構成] --> B2[ビルド RelWithDebInfo]
    B2 --> B3{ARM64?}
    B3 -->|No| B4[platform_output] --> B5{ASAN?}
    B3 -->|Yes| B6[ジョブ完了]
    B5 -->|No| B7[ctest -C RelWithDebInfo -V]
    B5 -->|Yes| B8[uv_run_tests_a.exe のみ]
    C --> C1[MinGWクロスビルド] --> C2[アーティファクトアップロード]
    C2 --> D[test-mingw x2]
    D --> D1[アーティファクトダウンロード] --> D2[テスト実行]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ビルドエラー | ソースコードのコンパイルに失敗した場合 | ビルドログを確認し、コード修正を行う |
| - | テスト失敗 | テストケースが失敗した場合 | テストログを確認し、コード修正またはテスト修正を行う |
| - | ASAN検出 | AddressSanitizerがメモリエラーを検出した場合 | ASANレポートを確認し、メモリ安全性の問題を修正する |

### リトライ仕様

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

### 障害時対応

各ジョブは `fail-fast: false` で設定されているため、一つのマトリクス環境が失敗しても他の環境のテストは継続される。test-mingw ジョブは build-mingw に依存（needs: build-mingw）しており、build-mingw が失敗した場合は test-mingw も実行されない。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 3ジョブ（Windows 6環境 + MinGWビルド 2環境 + MinGWテスト 2環境 = 10環境） |
| 目標処理時間 | 各ジョブ数分〜数十分 |
| メモリ使用量上限 | GitHub Actions ランナーのデフォルトリソース |

## 排他制御

各ジョブは独立したランナーで実行される。test-mingw は build-mingw の完了を待機する（needs 依存）。

## ログ出力

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

## 監視・アラート

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

## 備考

- build-windows のASAN構成では `CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded` が設定され、静的ランタイムを使用する
- build-windows のASAN構成では ctest ではなく uv_run_tests_a.exe を直接実行する（Windows HANDLEの問題回避）
- ARM64構成はビルドのみ実行され、テストは実行されない（ARM64ランナーが利用不可のため）
- MinGWビルドではlibgcc_s_dw2-1.dll（i686）/ libgcc_s_seh-1.dll（x86_64）、libwinpthread-1.dll、libatomic-1.dll をバイナリと一緒にパッケージングする
- アーティファクトの保持期間は2日間に設定されている
- build-mingw はactions/upload-artifact@v6、test-mingw はactions/download-artifact@v7 を使用（バージョン差異あり）
