# バッチ設計書 13-build.sh

## 概要

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

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

build.shは、Linux/macOS環境向けのArcadeフレームワーク中核ビルドスクリプトである。このシェルスクリプトは、.NETプロジェクトのビルド、テスト、パッケージング、署名、公開など、ソフトウェア開発ライフサイクル全体をカバーする包括的なビルドオーケストレーションを提供する。

**業務上の目的・背景**：.NETエコシステムはクロスプラットフォーム開発をサポートしており、Linux/macOS環境でのビルドは必須要件である。build.shは、Windowsのbuild.cmdと同等の機能をBashスクリプトとして提供し、すべてのプラットフォームで一貫したビルド体験を実現する。CI/CDパイプライン（Azure Pipelines、GitHub Actions等）でも広く使用される。

**バッチの実行タイミング**：開発者による手動実行（随時）およびCI/CDパイプラインでの自動実行。ローカル開発、プルリクエスト検証、リリースビルドなど、様々なシナリオで使用される。

**主要な処理内容**：
1. コマンドライン引数の解析（restore、build、test、pack等）
2. 環境変数とデフォルト値の設定
3. tools.shの読み込みによる共通関数の初期化
4. ネイティブツールの初期化（restore時）
5. MSBuildを通じたビルド処理の実行
6. CI環境固有の設定適用（バイナリログ、ノード再利用無効化等）

**前後の処理との関連**：単独で実行可能だが、restore後のbuild、build後のtest/pack/publishという順序で実行されることが多い。-sourceBuildや-productBuildオプションでVMR互換ビルドも可能。

**影響範囲**：artifacts/ディレクトリにビルド成果物を生成。.dotnet/ディレクトリにSDKをインストール。環境変数（DOTNET_MULTILEVEL_LOOKUP等）を設定。

## バッチ種別

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

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Linux/macOS | Unix系OS環境 |
| Bash | Bash 4.0以上推奨 |
| curl または wget | dotnet-install.shのダウンロードに必要 |
| .NET SDK | global.jsonで指定されたバージョン（自動インストール可能） |

### 実行可否判定

- `set -u`により未定義変数使用でエラー
- `set -e`によりコマンド失敗で即座に終了
- -helpオプションでヘルプ表示のみ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| -configuration (-c) | string | No | Debug | ビルド構成（sourceBuild時はRelease） |
| -verbosity (-v) | string | No | minimal | MSBuild出力詳細度 |
| -binaryLog (-bl) | switch | No | false | バイナリログ出力 |
| -restore (-r) | switch | No | false | 依存関係リストア |
| -build (-b) | switch | No | false | ビルド実行 |
| -rebuild | switch | No | false | リビルド |
| -test (-t) | switch | No | false | ユニットテスト |
| -integrationTest | switch | No | false | 統合テスト |
| -performanceTest | switch | No | false | パフォーマンステスト |
| -pack | switch | No | false | パッケージ作成 |
| -sign | switch | No | false | 署名 |
| -publish | switch | No | false | 公開 |
| -clean | switch | No | false | artifacts削除 |
| -sourceBuild (-sb) | switch | No | false | ソースビルドモード |
| -productBuild (-pb) | switch | No | false | プロダクトビルドモード |
| -ci | switch | No | false | CI環境指定 |
| -projects | string | No | なし | ビルド対象プロジェクト |
| -warnAsError | bool | No | true | 警告をエラーとして扱う |
| -nodeReuse | bool | No | true（CI時false） | ノード再利用 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| global.json | JSON | SDKバージョン、ツールセット定義 |
| *.sln / *.csproj / *.fsproj | MSBuild | プロジェクト定義 |
| NuGet.config | XML | パッケージソース設定 |
| eng/configure-toolset.sh | Bash | カスタムツールセット設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| artifacts/bin/ | ディレクトリ | ビルド成果物 |
| artifacts/obj/ | ディレクトリ | 中間ファイル |
| artifacts/log/ | ディレクトリ | ログファイル |
| artifacts/packages/ | ディレクトリ | NuGetパッケージ |
| artifacts/toolset/ | ディレクトリ | ツールセット |
| .dotnet/ | ディレクトリ | .NET SDK |

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. スクリプト初期化
   ├─ set -u（未定義変数エラー）
   └─ set -e（コマンド失敗時終了）
2. シンボリックリンク解決
   └─ スクリプトの実際のパスを特定
3. 変数初期化
   └─ restore, build, test等のフラグをfalseに初期化
4. コマンドライン引数解析
   └─ while/caseによる引数処理
5. 設定適用
   ├─ sourceBuild時はconfiguration=Release
   └─ CI時はpipelines_log=true, node_reuse=false
6. tools.sh読み込み
   └─ 共通関数の初期化
7. cleanオプション処理
   └─ artifacts削除して終了
8. restore時のネイティブツール初期化
   └─ InitializeNativeTools呼び出し
9. Build関数実行
   ├─ InitializeToolset
   ├─ InitializeCustomToolset
   └─ MSBuild実行
```

### フローチャート

```mermaid
flowchart TD
    A[build.sh開始] --> B[set -u/-e]
    B --> C[シンボリックリンク解決]
    C --> D[変数初期化]
    D --> E[引数解析]
    E --> F{-help?}
    F -->|Yes| G[usage表示]
    G --> Z[終了]
    F -->|No| H[設定適用]
    H --> I[tools.sh読み込み]
    I --> J{-clean?}
    J -->|Yes| K[artifacts削除]
    K --> Z
    J -->|No| L{-restore?}
    L -->|Yes| M[InitializeNativeTools]
    M --> N[Build関数]
    L -->|No| N
    N --> O[InitializeToolset]
    O --> P[MSBuild実行]
    P --> Q{成功?}
    Q -->|Yes| R[ExitWithExitCode 0]
    Q -->|No| S[エラー終了]
    R --> Z
    S --> Z
```

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 一般エラー | コマンド実行失敗 | ログ確認 |
| 2 | ツールセット未復元 | restore未実行 | restoreを先に実行 |
| 3 | 無効なツールセットパス | パス不正 | キャッシュクリア |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（スクリプト自体では実行しない） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. `set +e`でエラー時継続モードに変更して原因調査
2. `-verbosity detailed`または`-verbosity diagnostic`で再実行
3. `-bl`でバイナリログを有効化して詳細分析
4. `rm -rf artifacts`でクリーンビルド

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

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

## パフォーマンス要件

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

## 排他制御

- `-nodeReuse false`でMSBuildノードの再利用を無効化可能
- CI環境では自動的にノード再利用が無効化
- StopProcesses関数で`pkill -9 "dotnet"` `pkill -9 "vbcscompiler"`を実行

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各処理開始時 | 処理内容のecho |
| 進捗ログ | 処理中 | MSBuild出力 |
| 終了ログ | バッチ終了時 | サマリー |
| エラーログ | エラー発生時 | Write-PipelineTelemetryError |

## 監視・アラート

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

## 備考

- `set -u`と`set -e`により厳格なエラーハンドリングが適用される
- シンボリックリンク解決により、どこからスクリプトが呼び出されても正しく動作
- `-sourceBuild`オプションはLinuxディストリビューションでの.NET自体のビルドに使用
- CI環境では自動的にバイナリログが有効化され、ノード再利用が無効化される
- Azure Pipelinesとの統合用にpipelines_log機能を内蔵
