# バッチ設計書 1-razzle.cmd

## 概要

本ドキュメントは、OpenConsoleプロジェクトの開発環境セットアップスクリプト `razzle.cmd` のバッチ設計書である。

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

razzle.cmd は、Windows Terminal (OpenConsole) プロジェクトの開発環境を初期化するためのバッチスクリプトである。MSBuild、NuGet、vswhere などのビルドツールのパス設定、プロセッサアーキテクチャの検出、ビルド構成の初期化を行い、開発者がコマンドラインからビルド作業を行えるようにする。

**業務上の目的・背景**：Windows Terminal プロジェクトの開発において、開発者がビルド環境を手動で構成する手間を省き、一貫した開発環境を提供する。Microsoft 内部の開発ワークフロー（razzle）を模倣し、開発者が馴染みやすい環境を構築する。NuGet パッケージの復元、MSBuild の検出、TAEF テストランナーのパス設定など、ビルドおよびテストに必要な前提条件を自動的に整える。

**バッチの実行タイミング**：開発セッション開始時に手動で実行する。新しいコマンドプロンプトを開いた際に一度だけ実行すれば、そのセッション中は再実行不要（環境変数 `OpenConBuild` で重複実行を防止）。

**主要な処理内容**：
1. 環境変数 `OpenConBuild` による重複実行チェック
2. `PATH` 環境変数への tools ディレクトリの追加
3. `OPENCON_TOOLS` および `OPENCON` ルートディレクトリの環境変数設定
4. NuGet のパス追加および NuGet パッケージの復元（OpenConsole.slnx および packages.config）
5. MSBuild の検出（PATH 上の既存 MSBuild、または vswhere 経由で Visual Studio インストールから検出）
6. プロセッサアーキテクチャの検出（AMD64/x86）と ARCH/PLATFORM 環境変数の設定
7. デフォルトビルド構成（Debug）の設定
8. `.razzlerc.cmd` のカスタム設定の読み込み（存在しない場合はテンプレート生成）
9. コマンドライン引数（dbg/rel/x86）による構成オーバーライド
10. TAEF テストランナーパスの設定

**前後の処理との関連**：本バッチは他のすべてのビルド・テスト系バッチ（bcz.cmd、bz.cmd、runut.cmd 等）の前提条件となる。razzle.cmd で設定された環境変数（OPENCON、MSBUILD、TAEF、ARCH、PLATFORM、_LAST_BUILD_CONF 等）を後続のバッチが参照する。

**影響範囲**：現在のコマンドプロンプトセッションの環境変数（PATH、OPENCON、OPENCON_TOOLS、MSBUILD、ARCH、PLATFORM、DEFAULT_CONFIGURATION、TAEF、OpenConBuild）に影響を与える。ファイルシステムへの影響は NuGet パッケージの復元と `.razzlerc.cmd` テンプレートの生成のみ。

## バッチ種別

ビルド環境セットアップ

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Windows OS | Windows 環境でのみ動作する cmd スクリプト |
| Visual Studio インストール | MSBuild を含む Visual Studio がインストールされていること（または MSBuild が PATH 上にあること） |
| NuGet | dep/nuget ディレクトリに NuGet CLI が配置されていること |
| プロジェクトクローン済み | OpenConsole リポジトリがクローンされ、tools ディレクトリからスクリプトが実行可能であること |

### 実行可否判定

環境変数 `OpenConBuild` が設定済みの場合は、セットアップ処理をスキップして即座に終了する（`:END` ラベルにジャンプ）。これにより、同一セッション内での重複実行を防止する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| dbg | フラグ | No | - | デフォルトビルド構成を Debug に設定 |
| rel | フラグ | No | - | デフォルトビルド構成を Release に設定 |
| x86 | フラグ | No | - | アーキテクチャを x86/Win32 に強制設定 |
| (ファイルパス) | 文字列 | No | - | 存在するファイルを追加で呼び出し（カスタム環境設定スクリプト） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| OpenConsole.slnx | ソリューションファイル | NuGet パッケージ復元対象 |
| dep/nuget/packages.config | XML | NuGet パッケージ構成ファイル |
| .razzlerc.cmd | CMD スクリプト | ユーザーカスタム環境設定（任意） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 環境変数 PATH | 環境変数 | tools ディレクトリ、NuGet、MSBuild のパスを追加 |
| 環境変数 OPENCON | 環境変数 | プロジェクトルートディレクトリのパス |
| 環境変数 OPENCON_TOOLS | 環境変数 | tools ディレクトリのパス |
| 環境変数 MSBUILD | 環境変数 | MSBuild.exe のフルパス |
| 環境変数 ARCH | 環境変数 | アーキテクチャ（x64 または x86） |
| 環境変数 PLATFORM | 環境変数 | プラットフォーム（x64 または Win32） |
| 環境変数 DEFAULT_CONFIGURATION | 環境変数 | デフォルトビルド構成（Debug または Release） |
| 環境変数 TAEF | 環境変数 | TAEF テストランナー（TE.exe）のフルパス |
| 環境変数 OpenConBuild | 環境変数 | セットアップ完了フラグ（true） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | .razzlerc.cmd（存在しない場合のみテンプレート生成） |
| 出力先 | tools ディレクトリ |
| 文字コード | システムデフォルト |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. 重複実行チェック
   └─ 環境変数 OpenConBuild が設定済みなら :END へジャンプ
2. PATH に tools ディレクトリを追加
   └─ %~dp0 を PATH に追記
3. プロジェクトルート環境変数の設定
   └─ OPENCON_TOOLS と OPENCON を設定（tools パスから末尾7文字を除去）
4. NuGet パス追加とパッケージ復元
   └─ dep/nuget を PATH に追加し、OpenConsole.slnx と packages.config を復元
5. MSBuild 検出
   └─ まず PATH 上を検索、なければ vswhere で最新の VS プレリリース版から検出
6. MSBuild パスを PATH に追加
   └─ MSBuild.exe のディレクトリを PATH に追記
7. プロセッサアーキテクチャ検出
   └─ PROCESSOR_ARCHITECTURE が AMD64 なら x64、それ以外は x86
8. デフォルト構成を Debug に設定
   └─ DEFAULT_CONFIGURATION=Debug
9. .razzlerc.cmd の読み込み
   └─ 存在すれば call、なければテンプレートを生成
10. コマンドライン引数の処理
    └─ dbg/rel/x86 の各フラグ、またはファイルパスの呼び出し
11. TAEF パス設定と完了フラグ設定
    └─ TAEF 環境変数を設定し、OpenConBuild=true とする
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{OpenConBuild が設定済み?}
    B -->|はい| C[セットアップ済みメッセージ表示]
    C --> Z[バッチ終了]
    B -->|いいえ| D[PATH に tools ディレクトリ追加]
    D --> E[OPENCON/OPENCON_TOOLS 環境変数設定]
    E --> F[NuGet パス追加・パッケージ復元]
    F --> G{MSBuild が PATH 上に存在?}
    G -->|はい| H[既存 MSBuild を使用]
    G -->|いいえ| I[vswhere で MSBuild 検出]
    I --> J{MSBuild が見つかった?}
    J -->|いいえ| K[エラーメッセージ表示・終了]
    J -->|はい| H
    H --> L[MSBuild パスを PATH に追加]
    L --> M[プロセッサアーキテクチャ検出]
    M --> N[デフォルト構成設定]
    N --> O{.razzlerc.cmd が存在?}
    O -->|はい| P[.razzlerc.cmd を呼び出し]
    O -->|いいえ| Q[テンプレート生成]
    P --> R[コマンドライン引数処理]
    Q --> R
    R --> S[TAEF パス設定]
    S --> T[OpenConBuild=true 設定]
    T --> Z
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | vswhere 未検出 | vswhere.exe がパッケージディレクトリに見つからない場合 | VSWHERE 環境変数を手動設定して再実行 |
| - | MSBuild 未検出 | MSBuild.exe が PATH にもなく vswhere でも見つからない場合 | MSBUILD 環境変数を手動設定して再実行、または Visual Studio をインストール |

### リトライ仕様

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

### 障害時対応

MSBuild や vswhere が見つからない場合は、エラーメッセージに従い環境変数を手動設定するか、Visual Studio をインストールする。NuGet 復元に失敗した場合は、ネットワーク接続を確認して再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（環境変数設定のみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/セッション |
| 目標処理時間 | 数秒〜数十秒（NuGet 復元の状態に依存） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同時実行の制御は特に行わない。ただし、環境変数 `OpenConBuild` により同一セッション内での重複実行は防止される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | "Setting up dev environment..." |
| 情報ログ | MSBuild 検出時 | "Using MsBuild at ... which was already on the path." |
| エラーログ | vswhere 未検出時 | "Could not find vswhere on your machine..." |
| エラーログ | MSBuild 未検出時 | "Could not find MsBuild on your machine..." |
| 終了ログ | セットアップ完了時 | "The dev environment is ready to go!" |

## 監視・アラート

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

本バッチは開発者が手動で実行するため、監視・アラートの設定は不要。

## 備考

- 本スクリプトは `@echo off` で始まるため、コマンドのエコー出力は抑制される。
- vswhere による MSBuild 検出では、プレリリース版の Visual Studio も対象に含まれる（`-prerelease` フラグ）。これにより、VS 2022 等の最新版が優先的に使用される。
- `.razzlerc.cmd` ファイルにより、開発者ごとのカスタム環境設定が可能。
- TAEF のパスは NuGet パッケージの特定バージョン（10.100.251104001）に依存している。
- 引数として任意のスクリプトファイルパスを渡すことで、ショートカットごとの追加カスタマイズが可能。
