# バッチ設計書 6-vswhere_usability_wrapper.cmd

## 概要

本ドキュメントは、libuvプロジェクトのWindowsビルド前処理スクリプト `tools/vswhere_usability_wrapper.cmd` の設計仕様を定義する。

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

`vswhere_usability_wrapper.cmd` は、Windows環境でVisual Studioのインストール場所を自動検出するバッチスクリプトである。Microsoftが提供する `vswhere.exe` ツールを使用し、最新のVisual Studioインストールパスを検出して、環境変数 `VCINSTALLDIR` および `VS150COMNTOOLS` を設定する。

**業務上の目的・背景**：Windows環境でlibuvをネイティブビルドする際には、Visual StudioのVC++コンパイラ（cl.exe）が必要となる。Visual Studio 2017以降、インストールパスが固定されなくなったため、vswhere.exeを使用した動的な検出が必要になった。本スクリプトはNode.jsのwindows-autoconfプロジェクトから派生したものであり、Visual Studioのインストール場所を自動検出してビルドツールチェーンのパス解決を行う。

**バッチの実行タイミング**：WindowsネイティブビルドのGYPベースのビルドプロセスの前処理として手動で実行される。CMakeビルドでは直接使用されないが、Autotools以外のレガシービルドフローで参照される可能性がある。

**主要な処理内容**：
1. 引数 "prerelease" の判定（プレリリース版VS検出の有無）
2. vswhere.exe のパス解決（Program Files (x86) または Program Files 配下のMicrosoft Visual Studio Installer）
3. vswhere.exe の存在確認
4. vswhere パラメータの構築（-requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64）
5. バージョン範囲指定（[15.0,16.0) = VS 2017）
6. プレリリースモード時の -prerelease フラグ追加
7. vswhere 実行と結果のパース
8. VCINSTALLDIR および VS150COMNTOOLS 環境変数の設定

**前後の処理との関連**：本スクリプトは単独のユーティリティツールであり、Windowsビルドの前処理として使用される。CI-win.yml（No.8）では直接使用されていないが、ローカルのWindowsビルド環境構築時に参照される可能性がある。

**影響範囲**：Windows環境変数 VCINSTALLDIR および VS150COMNTOOLS に影響する。後続のビルドプロセスでこれらの環境変数を参照してVC++ツールチェーンのパスを解決する。

## バッチ種別

ビルド環境検出（Windows前処理）

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Windows OS | Windowsバッチスクリプトのため、Windows環境でのみ実行可能 |
| Visual Studio インストール済み | Visual Studio 2017（バージョン15.x）がインストールされていること |
| vswhere.exe 利用可能 | Visual Studio Installerに含まれるvswhere.exeがインストールされていること |
| VC++ ツールコンポーネント | Microsoft.VisualStudio.Component.VC.Tools.x86.x64 がインストールされていること |

### 実行可否判定

vswhere.exe が見つからない場合、"could not find vswhere" メッセージを出力して終了コード1で終了する。Visual Studioが条件に合致するバージョンでインストールされていない場合も同様に終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| %1 | 文字列 | No | （なし） | "prerelease" を指定するとプレリリース版Visual Studioも検出対象に含める |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| vswhere.exe | 実行ファイル | Microsoft Visual Studio Installerに同梱されるVSインストール検出ツール |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| VCINSTALLDIR | 環境変数 | Visual StudioのVC++インストールディレクトリパス（例: C:\Program Files\Microsoft Visual Studio\2022\Community\VC\） |
| VS150COMNTOOLS | 環境変数 | Visual Studioの共通ツールディレクトリパス（例: C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\） |

### 出力ファイル仕様

該当なし（環境変数の設定のみ）

## 処理フロー

### 処理シーケンス

```
1. プレリリースモード判定
   └─ 第1引数が "prerelease" の場合 VSWHERE_WITH_PRERELEASE=1 を設定
2. vswhere.exeパス検索
   └─ Program Files (x86)\Microsoft Visual Studio\Installer を最初に確認
   └─ 存在しない場合 Program Files\Microsoft Visual Studio\Installer を確認
3. vswhere.exe存在確認
   └─ where コマンドで vswhere の存在を確認、不在なら :no-vswhere へジャンプ
4. vswhereパラメータ構築
   └─ -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64
   └─ -property installationPath
   └─ -version "[15.0,16.0)"
5. プレリリースフラグ追加（条件付き）
   └─ VSWHERE_WITH_PRERELEASE=1 の場合 -prerelease を追加
6. vswhere実行
   └─ -latest -products * オプションで最新のインストールを検出
7. 結果パース・環境変数設定
   └─ installationPath から VCINSTALLDIR と VS150COMNTOOLS を設定
8. 正常終了（exit /B 0）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{引数 = prerelease?}
    B -->|Yes| C[VSWHERE_WITH_PRERELEASE=1]
    B -->|No| D[InstallerPath検索]
    C --> D
    D --> E{Program Files x86\VS\Installer 存在?}
    E -->|Yes| F[Path追加]
    E -->|No| G{Program Files\VS\Installer 存在?}
    G -->|Yes| F
    G -->|No| H[no-vswhere: エラー終了]
    F --> I{vswhere コマンド存在?}
    I -->|No| H
    I -->|Yes| J[vswhereパラメータ構築]
    J --> K{prerelease対応?}
    K -->|Yes| L[-prerelease追加]
    K -->|No| M[vswhere実行]
    L --> M
    M --> N{VS検出成功?}
    N -->|Yes| O[VCINSTALLDIR/VS150COMNTOOLS設定]
    N -->|No| H
    O --> P[exit /B 0]
    H --> Q[echo エラーメッセージ]
    Q --> R[exit /B 1]
```

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

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

該当なし（本スクリプトは環境変数の設定のみ行い、データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | vswhere未検出 | vswhere.exeがPATH上に見つからない場合 | Visual Studio Installerを確認し、vswhere.exeが含まれていることを確認する |
| 1 | VS未検出 | 条件に合致するVisual Studioが見つからない場合 | Visual Studio 2017以降をインストールし、VC++ツールコンポーネントを含める |

### リトライ仕様

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

### 障害時対応

vswhere未検出時は "could not find vswhere" メッセージが出力される。Visual Studioのインストール状況を確認し、必要なコンポーネントをインストールする。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回の実行でVSインストールパスを1つ検出 |
| 目標処理時間 | 1秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

環境変数の設定のみであるため、排他制御は不要。ただし、setlocal/endlocal のスコープにより、成功時のみ呼び出し元の環境に変数が伝播する仕組みになっている。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| デバッグログ | DEBUG_HELPER定義時 | @ECHO OFFが無効化され、コマンドトレースが出力される |
| エラーログ | vswhere未検出時 | "could not find vswhere" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | 呼び出し元バッチスクリプト |

## 備考

- 本スクリプトはNode.jsのwindows-autoconf（Refael Ackermann）から派生したもので、バージョン2.0.0である
- バージョン範囲 "[15.0,16.0)" は Visual Studio 2017 を対象としているが、VSWHERE_LMT の値を変更することで他バージョンにも対応可能
- setlocal/endlocal の構造により、vswhere検出成功時のみ環境変数が親プロセスに伝播する
- DEBUG_HELPER 環境変数が定義されている場合、@ECHO OFF が無効化されてデバッグ出力が有効になる
