# バッチ設計書 21-init-tools-native.sh

## 概要

本ドキュメントは、F#コンパイラプロジェクトにおけるネイティブツール初期化スクリプト（init-tools-native.sh）の設計を記述するものです。このスクリプトはLinux/macOS環境でのネイティブビルドツールのインストールと管理を担当します。

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

このバッチはArcadeフレームワークの一部として、global.jsonで定義されたネイティブツール（CMakeなど）を自動的にダウンロードしてインストールする処理を行います。

**業務上の目的・背景**：クロスプラットフォームでのF#コンパイラ開発において、ネイティブコードのコンパイルに必要なツール（CMake等）を統一的に管理・インストールする必要があります。このスクリプトにより、開発者の環境依存を排除し、CI/CD環境でも一貫したビルド環境を構築できます。Arcadeフレームワークの標準的なツール管理機構として機能し、.NETエコシステム全体での一貫性を確保します。

**バッチの実行タイミング**：ビルドプロセスの初期段階、特にネイティブコンポーネントのビルド前に実行されます。CI/CDパイプラインではビルドジョブの前提条件として実行され、開発者のローカル環境では初回セットアップ時やツールバージョン更新時に手動で実行されることもあります。

**主要な処理内容**：
1. global.jsonファイルからnative-toolsセクションを解析し、必要なツールとバージョンを取得
2. jqコマンドが利用可能な場合はそれを使用、そうでない場合は手動JSONパースにフォールバック
3. 各ネイティブツールに対応するインストーラースクリプト（install-{TOOL}.sh）を呼び出し
4. インストール結果の検証とPATH環境変数への追加（Azure DevOps用の##vso出力）
5. クリーンアップオプションによる既存インストールの削除

**前後の処理との関連**：eng/common/build.shやeng/build.shから呼び出される前提処理として機能します。ネイティブツールのインストール後、実際のビルドプロセスがこれらのツールを使用します。pipeline-logging-functions.shとnative/common-library.shに依存しています。

**影響範囲**：ローカルのネイティブツールインストールディレクトリ（デフォルト: ~/.netcoreeng/native）、Azure DevOpsパイプラインの環境変数（PATH）に影響を与えます。

## バッチ種別

ツールインストール / 環境セットアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ビルド前） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | ビルドスクリプトからの呼び出し / 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| global.jsonの存在 | プロジェクトルートにglobal.jsonファイルが存在すること |
| Bashシェル環境 | Linux/macOS環境でBashが利用可能であること |
| ネットワーク接続 | ツールダウンロード用にnetcorenativeassets.blob.core.windows.netへのアクセスが可能であること |
| 依存スクリプトの存在 | pipeline-logging-functions.sh、native/common-library.shが存在すること |

### 実行可否判定

global.jsonにnative-toolsセクションが定義されていない場合、スクリプトは「No native tools defined in global.json」を出力して正常終了します。native-toolsが定義されている場合のみインストール処理が実行されます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --baseuri | string | No | https://netcorenativeassets.blob.core.windows.net/resource-packages/external | ツールダウンロード元のベースURI |
| --installdirectory | string | No | ~/.netcoreeng/native | ツールのインストール先ディレクトリ |
| --clean | flag | No | false | インストールせずクリーンアップのみ実行 |
| --force | flag | No | false | 強制的に再インストール |
| --donotabortonfailure | flag | No | false | 失敗時に中断しない |
| --donotdisplaywarnings | flag | No | false | 警告を表示しない |
| --downloadretries | integer | No | 5 | ダウンロードリトライ回数 |
| --retrywaittimeseconds | integer | No | 30 | リトライ間隔（秒） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| global.json | JSON | native-toolsセクションからツール名とバージョンを取得 |
| 環境変数 NETCOREENG_INSTALL_DIRECTORY | string | インストールディレクトリの環境変数指定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| {install_directory}/bin | ディレクトリ | インストールされたネイティブツールのバイナリ格納先 |
| 標準出力 | テキスト | インストール進捗とステータスメッセージ |
| Azure DevOps変数 | task.prependpath | インストールディレクトリをPATHに追加 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | ツール依存（例: cmake） |
| 出力先 | {native_base_dir}/bin |
| 文字コード | N/A（バイナリ） |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 引数解析
   └─ コマンドライン引数を解析してオプション変数に設定
2. 依存スクリプトの読み込み
   └─ pipeline-logging-functions.shとnative/common-library.shをソース
3. インストールディレクトリの決定
   └─ 引数指定 > 環境変数 > デフォルト値の優先順位で決定
4. global.json解析（ReadGlobalJsonNativeTools関数）
   └─ jqが利用可能ならjqで解析、そうでなければBashで手動パース
5. ネイティブツールのインストールループ
   └─ 各ツールに対してinstall-{TOOL}.shを呼び出し
6. 結果検証
   └─ インストールディレクトリの存在確認とPATH設定出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[引数解析]
    B --> C[依存スクリプト読み込み]
    C --> D[インストールディレクトリ決定]
    D --> E[global.json解析]
    E --> F{native-tools定義あり?}
    F -->|なし| G[メッセージ出力して終了]
    F -->|あり| H[ツールループ開始]
    H --> I{インストーラー存在?}
    I -->|あり| J[インストーラー実行]
    I -->|なし| K{中断設定?}
    J --> L{実行成功?}
    L -->|成功| M[次のツールへ]
    L -->|失敗| K
    K -->|中断| N[エラー終了]
    K -->|継続| M
    M --> O{全ツール完了?}
    O -->|いいえ| H
    O -->|はい| P{cleanモード?}
    P -->|はい| Q[正常終了]
    P -->|いいえ| R{インストールディレクトリ存在?}
    R -->|はい| S[PATH追加出力]
    R -->|なし| T{インストール実行した?}
    T -->|はい| N
    T -->|いいえ| Q
    S --> Q
    G --> Q
```

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

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

このバッチはデータベース操作を行いません。

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

### テーブル別操作詳細

データベース操作はありません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | インストーラー実行失敗 | install-{TOOL}.shの実行が失敗 | ネットワーク接続確認、リトライオプション調整 |
| 1 | インストーラー不在 | 対応するinstall-{TOOL}.shが存在しない | global.jsonのツール定義を確認 |
| 1 | ディレクトリ不在 | インストール後にbinディレクトリが存在しない | ディスク容量・権限を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 5回（--downloadretriesで変更可能） |
| リトライ間隔 | 30秒（--retrywaittimesecondsで変更可能） |
| リトライ対象エラー | ネットワークダウンロードエラー |

### 障害時対応

1. --forceオプションで強制再インストールを試行
2. --cleanオプションでクリーンアップ後に再実行
3. 手動でインストールディレクトリを削除して再実行
4. ネットワーク接続とプロキシ設定を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイルシステム操作のみ） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A（--cleanオプションで手動クリーンアップ） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1-5ツール程度 |
| 目標処理時間 | ネットワーク状況依存（通常1-5分） |
| メモリ使用量上限 | 最小限（Bashスクリプト） |

## 排他制御

同時実行は推奨されません。同一インストールディレクトリへの同時書き込みによりファイル破損の可能性があります。CI/CD環境では各ジョブが独立したワークスペースを使用することで排他制御されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各インストーラー呼び出し前 | インストーラーコマンドライン |
| 進捗ログ | インストール成功時 | installed_any = true |
| 終了ログ | バッチ終了時 | Native tools are available from {path} |
| エラーログ | エラー発生時 | Write-PipelineTelemetryErrorによるカテゴリ付きエラー |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDパイプライン |
| インストール時間 | 10分超過 | CI/CDパイプライン |

## 備考

- Arcadeフレームワーク（eng/common）の標準コンポーネントとして、.NET関連プロジェクト間で共有されています
- jqコマンドが利用可能な環境ではより堅牢なJSON解析が行われます
- Azure DevOpsパイプラインとの統合のため、##vso形式のログ出力をサポートしています
