# バッチ設計書 2-bcz.cmd

## 概要

本ドキュメントは、OpenConsoleプロジェクトのソリューション全体をクリーンビルドするスクリプト `bcz.cmd` のバッチ設計書である。

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

bcz.cmd は、OpenConsole ソリューション全体に対して Clean + Build（クリーンビルド）を実行するバッチスクリプトである。Debug/Release/AuditMode のビルド構成切替、NuGet パッケージリストア、AppX バンドルビルドの制御、特定プロジェクトのみの排他ビルドに対応する。ビルド結果に応じてタスクバーの進捗表示を制御する機能も備える。

**業務上の目的・背景**：Windows Terminal プロジェクトの開発において、ソリューション全体のクリーンビルドを簡便に実行できるようにするための開発者支援スクリプトである。Microsoft 内部開発者が馴染みのある `bcz`（Build Clean Zero）コマンドを模倣している。Debug ビルド時には時間のかかる AppX バンドルビルドを自動的にスキップする最適化も組み込まれている。

**バッチの実行タイミング**：開発者がコード変更後にビルドを行う際に手動で実行する。クリーンビルドが必要な場面（ビルドエラーの解消、構成変更後）で使用される。

**主要な処理内容**：
1. 前回ビルド構成の保持と引数によるオーバーライド（dbg/rel/audit）
2. ビルドターゲットの設定（Clean;Build またはBuild のみ）
3. exclusive モード時の特定プロジェクト名解決（bx.ps1 呼び出し）
4. NuGet パッケージ復元（スキップ可能）
5. MSBuild によるソリューションビルド実行
6. タスクバー進捗表示の制御（OSC 9;4 シーケンス）
7. ビルド結果に応じたエラー状態のタスクバー通知

**前後の処理との関連**：razzle.cmd で設定された環境変数（OPENCON、MSBUILD、ARCH、_LAST_BUILD_CONF 等）を前提とする。bcx.cmd（exclusive ラッパー）、bz.cmd（no_clean ラッパー）、bx.cmd（exclusive + no_clean ラッパー）から呼び出される中核バッチである。

**影響範囲**：ビルド出力ディレクトリ（bin/%PLATFORM%/%_LAST_BUILD_CONF%）配下のバイナリ、中間ファイル。環境変数 `_LAST_BUILD_CONF` と `_BIN_` を更新する。

## バッチ種別

ビルド実行

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| razzle.cmd 実行済み | OPENCON、MSBUILD、ARCH 等の環境変数が設定されていること |
| Visual Studio / MSBuild | ビルドに必要な MSBuild が利用可能であること |
| NuGet | NuGet CLI が利用可能であること（_SKIP_NUGET_RESTORE=1 の場合は不要） |

### 実行可否判定

特別な実行可否判定はない。前提条件が満たされていない場合は、MSBuild 呼び出し時にエラーとなる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| dbg | フラグ | No | - | ビルド構成を Debug に設定 |
| rel | フラグ | No | - | ビルド構成を Release に設定 |
| audit | フラグ | No | - | ビルド構成を AuditMode に設定 |
| no_clean | フラグ | No | - | クリーンなしでビルド（Build のみ） |
| exclusive | フラグ | No | - | カレントディレクトリのプロジェクトのみビルド |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| OpenConsole.slnx | ソリューションファイル | ビルド対象のソリューション |
| OpenConsole.slnx.metaproj | MSBuild メタプロジェクト | exclusive モード時にプロジェクト名解決に使用 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| bin/%PLATFORM%/%_LAST_BUILD_CONF%/ | バイナリ | ビルド成果物の出力ディレクトリ |
| 環境変数 _LAST_BUILD_CONF | 環境変数 | 最後に使用されたビルド構成 |
| 環境変数 _BIN_ | 環境変数 | ビルド出力ディレクトリのパス |
| 終了コード | プロセス終了コード | MSBuild の終了コード（0: 成功、1: 失敗） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | MSBuild により生成されるバイナリ群 |
| 出力先 | bin/%PLATFORM%/%_LAST_BUILD_CONF%/ |
| 文字コード | 該当なし（バイナリ） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. 前回ビルド構成の初期化
   └─ _LAST_BUILD_CONF が未設定の場合 DEFAULT_CONFIGURATION を使用
2. ビルドターゲットの設定
   └─ デフォルトは Clean;Build（クリーンビルド）
3. コマンドライン引数の解析
   └─ dbg/rel/audit でビルド構成設定、no_clean でターゲット変更、exclusive で排他モード
4. exclusive モードの処理（該当時のみ）
   └─ MSBuildEmitSolution=1 でメタプロジェクト生成後、bx.ps1 でプロジェクト名を解決
5. AppX ビルド制御
   └─ 非 exclusive かつ Debug 時は AppxBundle=false に設定
6. NuGet パッケージ復元
   └─ _SKIP_NUGET_RESTORE=1 でない場合、nuget.exe restore を実行
7. MSBuild 実行
   └─ ソリューション全体（または exclusive 指定プロジェクト）をビルド
8. タスクバー進捗制御
   └─ ビルド開始時: 不確定進捗（OSC 9;4;3）、成功時: クリア（OSC 9;4）、失敗時: エラー表示後クリア
9. 終了コードの返却
   └─ MSBuild の終了コードをそのまま返す
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[前回ビルド構成の初期化]
    B --> C[引数解析: dbg/rel/audit/no_clean/exclusive]
    C --> D{exclusive モード?}
    D -->|はい| E[メタプロジェクト生成・プロジェクト名解決]
    E --> F{プロジェクト名取得成功?}
    F -->|いいえ| G[エラーメッセージ表示・終了]
    F -->|はい| H[NuGet 復元判定]
    D -->|いいえ| I{Debug ビルド?}
    I -->|はい| J[AppxBundle=false 設定]
    I -->|いいえ| K[AppX ビルド有効]
    J --> H
    K --> H
    H --> L[NuGet パッケージ復元]
    L --> M[タスクバー: 不確定進捗表示]
    M --> N[MSBuild 実行]
    N --> O{ビルド成功?}
    O -->|はい| P[タスクバー: 進捗クリア]
    O -->|いいえ| Q[タスクバー: エラー表示・500ms待機・クリア]
    P --> R[終了コード返却]
    Q --> R
    R --> S[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ビルドエラー | MSBuild がビルドに失敗した場合 | ビルドエラーメッセージを確認し、コードを修正して再実行 |
| -1 | プロジェクト未検出 | exclusive モードで vcxproj が見つからない場合 | vcxproj が存在するディレクトリに移動して再実行 |

### リトライ仕様

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

### 障害時対応

ビルド失敗時はタスクバーにエラー状態が500ms間表示される。MSBuild の出力を確認してエラー原因を特定し、コード修正後に再実行する。クリーンビルドで解消しない場合は、手動でビルド出力ディレクトリを削除してから再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（Clean;Build によりビルド出力は毎回クリーンされる） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ソリューション全体のビルド（数百プロジェクト） |
| 目標処理時間 | 数分〜数十分（マシンスペック・構成に依存） |
| メモリ使用量上限 | MSBuild の /m（マルチプロセッサ）オプションにより並列ビルド |

## 排他制御

同一ディレクトリでの同時ビルドは MSBuild により制御される。バッチスクリプト自体には排他制御機構はない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | 引数解析時 | "Manually building debug/release" |
| 情報ログ | AppX スキップ時 | "Skipping building appx..." |
| 情報ログ | NuGet 復元時 | "Performing nuget restore..." |
| 情報ログ | ビルド開始時 | ビルドコマンドライン全体と "Starting build..." |
| 情報ログ | exclusive モード時 | "Building only %PROJECT_NAME%" |

## 監視・アラート

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

本バッチは開発者が手動で実行するため、監視・アラートの設定は不要。ビルド失敗時はタスクバーのエラー表示で通知される。

## 備考

- 環境変数 `_LAST_BUILD_CONF` は bcz.cmd 実行間で保持され、前回のビルド構成が引き継がれる。
- `/p:GenerateAppxPackageOnBuild=false` により、wapproj プロジェクトの .msix パッケージ生成は常にスキップされる。
- タスクバー進捗表示は OSC 9;4 エスケープシーケンスを使用しており、Windows Terminal で動作する。
- exclusive モードでは `bx.ps1` を呼び出してメタプロジェクトからプロジェクト名を解決する（No.6 参照）。
- `_SKIP_NUGET_RESTORE=1` を事前に設定しておくと NuGet 復元をスキップできる。
- ビルド失敗時の500ms待機は `ping 128.0.0.1 -n 1 -w 500` で実現している（応答しないアドレスへの ping タイムアウトを利用）。
