# バッチ設計書 7-build.bat

## 概要

本ドキュメントは、ColorTool プロジェクトを MSBuild でビルドするスクリプト `build.bat` のバッチ設計書である。

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

build.bat は、ColorTool プロジェクト（src/tools/ColorTool）を MSBuild でビルドするためのバッチスクリプトである。MSBuild の自動検出機能を持ち、Visual Studio 2017/2019 の各エディション（Community/Professional/Enterprise/BuildTools）および MSBuild 14.0 から MSBuild を検索する。clean/rel オプションによるビルドターゲットと構成の切替に対応する。

**業務上の目的・背景**：ColorTool は、Windows コンソールのカラースキームを変更するための独立したユーティリティツールである。メインの OpenConsole ソリューションとは独立した ColorTool.sln ソリューションを持つため、専用のビルドスクリプトが用意されている。このスクリプトにより、razzle.cmd による環境セットアップなしでも ColorTool を単独でビルドできる。

**バッチの実行タイミング**：ColorTool の開発・修正時に手動で実行する。

**主要な処理内容**：
1. MSBuild の自動検出（PATH 上 -> VS2019 -> VS2017 各エディション -> MSBuild 14.0）
2. コマンドライン引数の解析（clean/rel）
3. MSBuild による ColorTool.sln のビルド実行
4. ビルド成功時に成果物（ColorTool.exe）をプロジェクトルートにコピー

**前後の処理との関連**：独立したビルドスクリプトであり、razzle.cmd や bcz.cmd とは独立して動作する。ビルド成果物の ColorTool.exe は開発者が直接使用する。

**影響範囲**：ColorTool プロジェクトのビルド出力ディレクトリ（ColorTool/bin/Debug or Release）と、プロジェクトルートへのコピー先（ColorTool.exe）。

## バッチ種別

ビルド実行

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| MSBuild | MSBuild が PATH 上にあるか、Visual Studio 2017/2019 がインストールされていること |
| .NET | ColorTool プロジェクトのビルドに必要な .NET SDK |

### 実行可否判定

MSBuild が検出できない場合は、エラーメッセージ "MSBuild was not found." を表示して終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| clean | フラグ | No | - | Clean,Build ターゲットでビルド（クリーンビルド） |
| rel | フラグ | No | - | Release 構成でビルド |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ColorTool.sln | ソリューションファイル | ビルド対象のソリューション |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ColorTool/bin/{Debug\|Release}/ | バイナリ | ビルド成果物の出力ディレクトリ |
| ColorTool.exe（プロジェクトルート） | 実行ファイル | ビルド成功時にルートにコピーされた実行ファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | ColorTool.exe |
| 出力先 | src/tools/ColorTool/（ビルド成功時のコピー先） |
| 文字コード | 該当なし（バイナリ） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. MSBuild の検出
   └─ PATH 上の msbuild.exe を where.exe で検索
   └─ 見つからない場合、以下の順で存在チェック:
       (1) VS2019 Community
       (2) VS2017 Community
       (3) VS2017 Professional
       (4) VS2017 Enterprise
       (5) VS2017 BuildTools
       (6) MSBuild 14.0
2. MSBuild パスの表示
   └─ "MSBuild was found at ..." を出力
3. コマンドライン引数の解析
   └─ デフォルト: _MSBUILD_TARGET=Build, _MSBUILD_CONFIG=Debug
   └─ clean 引数: _MSBUILD_TARGET=Clean,Build
   └─ rel 引数: _MSBUILD_CONFIG=Release
4. MSBuild によるビルド実行
   └─ ColorTool.sln を指定構成・ターゲットでビルド（/m 並列・/nr:true ノードリユース有効）
5. ビルド結果の処理
   └─ ERRORLEVEL=0 の場合: 成果物パス表示、ColorTool.exe をプロジェクトルートにコピー
6. 一時停止
   └─ Pause で待機
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{MSBuild が PATH 上に存在?}
    B -->|はい| C[MSBuild パス確定]
    B -->|いいえ| D[VS2019/2017 各エディションを順に検索]
    D --> E{MSBuild 検出?}
    E -->|いいえ| F[エラーメッセージ表示・終了]
    E -->|はい| C
    C --> G[引数解析: clean/rel]
    G --> H[MSBuild でビルド実行]
    H --> I{ERRORLEVEL = 0?}
    I -->|はい| J[成果物パス表示]
    J --> K[ColorTool.exe をプロジェクトルートにコピー]
    I -->|いいえ| L[エラー状態のまま終了へ]
    K --> M[Pause]
    L --> M
    M --> N[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | MSBuild 未検出 | PATH 上にも VS インストールにも MSBuild が見つからない場合 | Visual Studio をインストールするか MSBuild を PATH に追加 |
| 非0 | ビルドエラー | MSBuild がビルドに失敗した場合 | ビルドエラーメッセージを確認して修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

ビルド失敗時は MSBuild の出力を確認してエラー原因を特定する。clean オプションを付けて再実行を試みる。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 単一プロジェクト（ColorTool） |
| 目標処理時間 | 数十秒 |
| メモリ使用量上限 | MSBuild に依存 |

## 排他制御

同時実行の制御は特に行わない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | MSBuild 検出時 | "MSBuild was found at %MSBUILD%" |
| エラーログ | MSBuild 未検出時 | "MSBuild was not found. Make sure it is installed and included in the search path." |
| 情報ログ | ビルド成功時 | 成果物パスと "Copying exe to root of project..." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- 本スクリプトは OpenConsole のメインビルドシステム（razzle.cmd / bcz.cmd）とは独立して動作する。
- MSBuild の検索順序は: PATH上 -> VS2019 Community -> VS2017 Community -> VS2017 Professional -> VS2017 Enterprise -> VS2017 BuildTools -> MSBuild 14.0 である。
- ビルドオプション `/nr:true`（Node Reuse）が有効で、MSBuild ノードプロセスを再利用する。
- ビルド成功時に `colortool.exe` をプロジェクトルート（`src/tools/ColorTool/`）にコピーする。
- スクリプト末尾の `Pause` により、ビルド結果を確認できるよう一時停止する。
- AMD64 以外のプロセッサアーキテクチャでは Program Files（x86 なし）を参照する。
