# バッチ設計書 12-build.cmd

## 概要

本ドキュメントは、Arcadeフレームワークの共通ビルドスクリプト（eng/common/build.cmd）の設計仕様を記述したものである。

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

build.cmdは、.NETプロジェクト向けArcadeフレームワークの中核となるビルドスクリプトであり、Windows環境でのビルド処理を統一的に管理する。このバッチファイルはbuild.ps1 PowerShellスクリプトのシンプルなラッパーとして機能し、すべてのコマンドライン引数を透過的に転送する。

**業務上の目的・背景**：.NET製品群（F#コンパイラを含む）は、一貫したビルドプロセスを確保するためにArcadeフレームワークを採用している。このフレームワークにより、複数のリポジトリ間で統一されたビルド体験を提供し、CI/CDパイプラインとの連携を容易にしている。build.cmdはこの統一インターフェースの入り口として機能する。

**バッチの実行タイミング**：開発者による手動実行（随時）。ローカル開発環境でのビルド、デバッグ、テスト実行時に使用される。CI/CDパイプラインでは、より特化したCIBuild.cmdが使用されることが多い。

**主要な処理内容**：
1. PowerShellの実行ポリシーをByPassに設定
2. プロファイルの読み込みをスキップしてPowerShellを高速起動
3. build.ps1スクリプトを呼び出し、すべての引数を転送
4. PowerShellスクリプトの終了コードをそのまま返却

**前後の処理との関連**：Restore処理の後に実行されることが一般的。ビルド成果物は後続のテスト、パッケージング、署名、公開処理で使用される。

**影響範囲**：artifacts/ディレクトリ配下にビルド成果物を生成。.dotnet/ディレクトリにSDKがインストールされる可能性がある。

## バッチ種別

ビルド実行 / 開発インフラストラクチャ

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Windows OS | Windows 10以降またはWindows Server |
| PowerShell | PowerShell 5.1以上 |
| .NET SDK | global.jsonで指定されたバージョン（自動インストール可能） |

### 実行可否判定

特段の実行可否判定は行わない。引数に-helpを指定した場合はヘルプを表示して終了。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| -configuration (-c) | string | No | Debug | ビルド構成 |
| -platform | string | No | なし | プラットフォーム（x86, x64など） |
| -verbosity (-v) | string | No | minimal | MSBuild出力詳細度 |
| -restore (-r) | switch | No | false | 依存関係リストアを実行 |
| -build (-b) | switch | No | false | ビルドを実行 |
| -rebuild | switch | No | false | リビルドを実行 |
| -test (-t) | switch | No | false | ユニットテストを実行 |
| -pack | switch | No | false | NuGetパッケージを作成 |
| -sign | switch | No | false | ビルド成果物に署名 |
| -publish | switch | No | false | 成果物を公開 |
| -clean | switch | No | false | artifactsディレクトリを削除 |
| -ci | switch | No | false | CI環境での実行を指定 |
| -binaryLog (-bl) | switch | No | false | バイナリログを出力 |
| -projects | string | No | なし | ビルド対象プロジェクト |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| global.json | JSON | SDKバージョン、ツールセット定義 |
| *.sln / *.csproj / *.fsproj | MSBuild | プロジェクト定義 |
| NuGet.config | XML | パッケージソース設定 |
| Directory.Build.props | MSBuild | 共通ビルドプロパティ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| artifacts/bin/ | ディレクトリ | ビルド成果物（DLL、EXE等） |
| artifacts/obj/ | ディレクトリ | 中間ファイル |
| artifacts/log/ | ディレクトリ | ログファイル |
| artifacts/packages/ | ディレクトリ | NuGetパッケージ（pack時） |
| artifacts/toolset/ | ディレクトリ | ツールセット関連ファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | Build.binlog（バイナリログ有効時） |
| 出力先 | artifacts/log/{Configuration}/ |
| 文字コード | バイナリ |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. バッチファイル起動
   └─ @echo off でコマンドエコー抑制
2. PowerShell起動
   └─ ExecutionPolicy ByPass
   └─ NoProfile
3. build.ps1実行
   ├─ tools.ps1読み込み
   ├─ ヘルプ表示（-help時）
   ├─ クリーン処理（-clean時）
   ├─ CI設定適用（-ci時）
   ├─ ネイティブツール初期化（-restore時）
   └─ Build関数実行
       ├─ ツールセット初期化
       ├─ カスタムツールセット初期化
       └─ MSBuild実行
4. 終了コード返却
   └─ exit /b %ErrorLevel%
```

### フローチャート

```mermaid
flowchart TD
    A[build.cmd開始] --> B[PowerShell起動]
    B --> C[build.ps1実行]
    C --> D{-help?}
    D -->|Yes| E[ヘルプ表示]
    E --> Z[終了]
    D -->|No| F{-clean?}
    F -->|Yes| G[artifacts削除]
    G --> Z
    F -->|No| H{-restore?}
    H -->|Yes| I[ネイティブツール初期化]
    I --> J[Build関数実行]
    H -->|No| J
    J --> K[ツールセット初期化]
    K --> L[MSBuild実行]
    L --> M{成功?}
    M -->|Yes| N[終了コード0]
    M -->|No| O[終了コード非ゼロ]
    N --> Z
    O --> Z
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | なし | なし | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 一般エラー | ビルド失敗、例外発生 | ログを確認 |
| 2 | ツールセットエラー | Arcade SDKリストア失敗 | ネットワーク確認 |
| 3 | ツールセットパスエラー | 無効なツールセットパス | キャッシュクリア |

### リトライ仕様

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

### 障害時対応

1. artifacts/log/ディレクトリのログを確認
2. -binaryLogオプションを有効にして詳細ログを取得
3. -verbosity diagnosticで再実行して詳細情報を取得
4. artifacts/ディレクトリを削除して再実行

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト数に依存 |
| 目標処理時間 | プロジェクト規模に依存 |
| メモリ使用量上限 | 指定なし |

## 排他制御

MSBuildのノード再利用（-nodeReuse）オプションにより、複数ビルドプロセス間でのビルドサーバー共有を制御可能。CI環境ではノード再利用は無効化される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | エコー抑制 |
| 進捗ログ | 処理中 | MSBuild出力（verbosityに依存） |
| 終了ログ | バッチ終了時 | サマリー（/clp:Summary） |
| エラーログ | エラー発生時 | エラー詳細、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | プロジェクト依存 | CI/CDパイプライン |
| エラー件数 | 1件 | 開発者 |

## 備考

- Arcadeフレームワークの一部として提供される共通インフラストラクチャ
- -productBuild (-pb) オプションでVMRビルド互換モードを有効化可能
- カスタムツールセット（eng/restore-toolset.ps1）がある場合は自動的に読み込まれる
- 終了コードは%ErrorLevel%として正確に伝播される
