# バッチ設計書 47-appveyor（appveyor.yml）

## 概要

本ドキュメントは、AppVeyor CI設定ファイル「appveyor.yml」のバッチ設計書である。Visual Studio 2015〜2022の複数バージョン・32bit/64bitの組み合わせでWindows向けmrubyのビルドとテストを実行するCI設定について記載する。

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

本バッチは、AppVeyor CIプラットフォーム上でVisual Studio（MSVC）の複数バージョンとアーキテクチャの組み合わせによるマトリクスビルドを実行し、Windows環境でのmrubyの互換性を検証する。

**業務上の目的・背景**：mrubyはクロスプラットフォーム対応の組み込みRuby処理系であり、Windows環境での動作保証が重要である。Visual Studioの複数バージョン（2015/2017/2019/2022）と32bit/64bitの両アーキテクチャでの互換性を検証することで、Windows開発者がmrubyを安全に利用できることを保証する。GitHub ActionsのWindows環境テストに加え、AppVeyorを使用することでVisual Studioの古いバージョン（2015、2017）を含む広範な互換性テストを実現している。

**バッチの実行タイミング**：AppVeyorの設定に従い、リポジトリへのpush時に自動実行される（AppVeyorのデフォルト動作）。

**主要な処理内容**：
1. Visual Studioの環境変数を初期化し、コンパイラ環境を設定する
2. RubyInstaller（Ruby 2.6 64-bit）をPATHに追加する
3. MRUBY_CONFIGをci/msvcに設定し、rake -m test:run:serialでテストを逐次実行する

**前後の処理との関連**：本バッチはGitHub ActionsのBuild & Test（No.38）と並行してWindows環境でのテストを提供する。テスト実行にはrake test:run:serial（No.13と同等）を使用する。

**影響範囲**：Windows環境でのmrubyの互換性保証。Visual Studio 2015〜2022、32bit/64bitの全組み合わせでの動作検証結果。

## バッチ種別

ビルド・テスト / CI（継続的インテグレーション）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | 該当なし（イベントトリガー） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | リポジトリへのpush / Pull Request（AppVeyorのデフォルト設定） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| AppVeyorアカウント | AppVeyor CIでプロジェクトが設定されていること |
| Visual Studio | 各マトリクスのAppVeyorイメージにVisual Studioがインストールされていること |
| Ruby | RubyInstaller Ruby 2.6 64-bitがAppVeyorイメージに含まれていること |

### 実行可否判定

AppVeyorのデフォルトトリガー設定に従い、pushまたはPull Requestイベントで自動実行される。shallow_clone: trueが設定されているため、浅いクローンが使用される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| MRUBY_CONFIG | string | Yes | ci/msvc | mrubyビルド設定ファイルのパス |
| visualcpp | string | Yes | （マトリクスで定義） | Visual Studioのvcvarsバッチファイルパス |
| appveyor_build_worker_image | string | Yes | （マトリクスで定義） | AppVeyorビルドワーカーイメージ名 |
| machine | string | No | （未指定の場合デフォルト） | アーキテクチャ指定（x86/x86_amd64） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリソースコード | ファイルシステム | mrubyのソースコード一式 |
| ci/msvc | 設定ファイル | MSVC向けmrubyビルド設定 |

### ビルドマトリクス

| ジョブ名 | Visual Studio | アーキテクチャ | vcvarsパス | ワーカーイメージ |
|---------|--------------|---------------|-----------|----------------|
| Visual Studio 2022 64-bit | 2022 | 64-bit | C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat | Visual Studio 2022 |
| Visual Studio 2019 64-bit | 2019 | 64-bit | C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat | Visual Studio 2019 |
| Visual Studio 2019 32-bit | 2019 | 32-bit | C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars32.bat | Visual Studio 2019 |
| Visual Studio 2017 64-bit | 2017 | 64-bit | C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat | Visual Studio 2017 |
| Visual Studio 2017 32-bit | 2017 | 32-bit | C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars32.bat | Visual Studio 2017 |
| Visual Studio 2015 64-bit | 2015 | 64-bit | C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat | Visual Studio 2015 |
| Visual Studio 2015 32-bit | 2015 | 32-bit | C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat | Visual Studio 2015 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| AppVeyor CIステータス | CI Check | ビルド・テストの成功/失敗ステータス |
| AppVeyorビルドログ | テキスト | ビルドおよびテスト実行結果の詳細ログ |

### 出力ファイル仕様

本バッチは成果物のアーティファクトアップロードを行わない。ビルド成果物はAppVeyorのビルドワーカー上に一時的に生成される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（アーティファクト未設定） |
| 出力先 | AppVeyorビルドログ |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. 環境初期化（initフェーズ）
   ├─ Visual Studioの環境変数を初期化（call "%visualcpp%" %machine%）
   ├─ RubyInstaller Ruby 2.6 64-bitをPATHに追加
   └─ Rubyバージョンを表示（ruby --version）
2. ビルド＆テスト（build_scriptフェーズ）
   ├─ MRUBY_CONFIGをci/msvcに設定
   └─ rake -m test:run:serialでビルドとテストを逐次実行
```

### フローチャート

```mermaid
flowchart TD
    A[AppVeyor CI開始] --> B[マトリクスジョブ分岐<br>7つの組み合わせ]
    B --> C[Visual Studio環境初期化<br>vcvarsバッチ実行]
    C --> D[Ruby 2.6をPATHに追加]
    D --> E[MRUBY_CONFIG=ci/msvc設定]
    E --> F[rake -m test:run:serial実行]
    F --> G{テスト結果}
    G -->|成功| H[ジョブ成功]
    G -->|失敗| I[ジョブ失敗]
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンパイルエラー | MSVCでのコンパイルに失敗した場合 | コンパイルエラーの原因を修正する |
| - | テスト失敗 | テストケースが失敗した場合 | テストログから失敗原因を特定し修正する |
| - | vcvars実行エラー | Visual Studio環境変数の初期化に失敗した場合 | AppVeyorワーカーイメージの構成を確認する |
| - | Ruby未検出 | Ruby 2.6が見つからない場合 | AppVeyorイメージのRubyインストール状態を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動で再実行（AppVeyor UIから） |
| リトライ間隔 | 該当なし（手動） |
| リトライ対象エラー | 一時的なインフラエラー |

### 障害時対応

ビルドまたはテスト失敗時は、AppVeyorのビルドログから該当するマトリクスジョブのエラーを確認し、修正する。特定のVisual Studioバージョンでのみ失敗する場合は、コンパイラのバージョン固有の問題として対処する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 7マトリクスジョブ（並列実行可能） |
| 目標処理時間 | 明示的な規定なし |
| メモリ使用量上限 | AppVeyorワーカーのデフォルトリソース |

## 排他制御

AppVeyorの標準動作により、同一リポジトリに対する複数のビルドが同時に実行される可能性がある。AppVeyorのプロジェクト設定で同時実行数を制御可能。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ビルド開始時 | AppVeyorの標準ログ（ビルドバージョン、環境情報） |
| 進捗ログ | 各フェーズ実行時 | vcvars実行結果、Rubyバージョン、ビルド進捗、テスト結果 |
| 終了ログ | ビルド終了時 | ビルド・テスト結果サマリー |
| エラーログ | エラー発生時 | コンパイルエラー、テスト失敗詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | 1回 | AppVeyorの通知設定に従う |
| テスト失敗 | 1回 | AppVeyorの通知設定に従う |

## 備考

- shallow_clone: trueにより浅いクローンを使用してチェックアウト時間を短縮している
- バージョンは"{build}"のプレースホルダーで自動採番される
- Ruby 2.6はAppVeyorの全イメージで共通利用可能な最高バージョンとして選択されている（コメントに記載）
- Visual Studio 2015のvcvarsパスは他のバージョンと異なる形式（vcvarsall.batを使用し、machineパラメータでアーキテクチャを指定）
- `rake -m`オプションによりマルチタスク実行が有効化されている
- テストは`test:run:serial`で逐次実行される（並列実行ではない）
- MRUBY_CONFIGは`ci/msvc`に設定されており、MSVC固有のビルド設定が使用される
