# バッチ設計書 3-fetch-zig-cache.sh

## 概要

本ドキュメントは、Zigの依存関係をbuild.zig.zon.txtから取得するパッケージメンテナー向けスクリプト `fetch-zig-cache.sh` の設計仕様を記載する。

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

本バッチは、Zigビルドシステムの依存関係を事前にダウンロードしてキャッシュに格納するスクリプトである。

**業務上の目的・背景**：Zigの `zig build --fetch` コマンドは現在、推移的依存関係（依存先がさらに依存しているパッケージ）を取得しないという既知の問題がある（ziglang/zig#20976）。これにより、パッケージメンテナーがオフラインビルド環境を構築する際に問題が発生する。本スクリプトは、build.zig.zon.txtに記載された全依存関係URLを明示的に取得することで、この問題を回避する。将来的にZigの問題が解決されれば、本スクリプトは不要になる見込みである。

**バッチの実行タイミング**：パッケージメンテナーによる手動実行時（Nixパッケージビルド前など）

**主要な処理内容**：
1. ZIG_GLOBAL_CACHE_DIR環境変数の存在チェック
2. build.zig.zon.txtファイルのパス解決
3. ファイル内の各URLを行ごとに読み取り
4. zig fetchコマンドで各URLの依存関係を取得

**前後の処理との関連**：check-zig-cache.shにより生成されたbuild.zig.zon.txtを入力として使用する。本スクリプト実行後、オフライン環境でのZigビルドが可能になる。

**影響範囲**：ZIG_GLOBAL_CACHE_DIRで指定されたZigグローバルキャッシュディレクトリ

## バッチ種別

依存関係取得 / キャッシュ生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ZIG_GLOBAL_CACHE_DIR | 環境変数が設定されていること |
| zig | zigコマンドが利用可能であること |
| build.zig.zon.txt | ファイルが存在すること |
| ネットワーク接続 | 依存関係をダウンロードするためのインターネット接続 |

### 実行可否判定

- ZIG_GLOBAL_CACHE_DIR環境変数が未設定の場合、エラー終了

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数なし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| build.zig.zon.txt | テキスト | 依存関係URLリスト（1行1URL） |
| ZIG_GLOBAL_CACHE_DIR | 環境変数 | Zigキャッシュディレクトリパス |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ZIG_GLOBAL_CACHE_DIR | バイナリ/アーカイブ | ダウンロードされた依存関係 |
| 標準出力 | テキスト | Fetching: URL メッセージ |
| 標準エラー | テキスト | エラーメッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | Zigが管理（ハッシュベース） |
| 出力先 | ZIG_GLOBAL_CACHE_DIR |
| 文字コード | - |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. 環境変数チェック
   └─ ZIG_GLOBAL_CACHE_DIR が設定されていなければエラー終了
2. パス解決
   └─ スクリプト位置から build.zig.zon.txt のパスを算出
3. URL取得ループ
   └─ build.zig.zon.txt を1行ずつ読み取り
   └─ 各URLについて zig fetch を実行
   └─ 失敗した場合はエラーメッセージを出力して終了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{ZIG_GLOBAL_CACHE_DIR設定?}
    B -->|未設定| C[エラー出力・終了]
    B -->|設定済| D[パス解決]
    D --> E[build.zig.zon.txt読み取り]
    E --> F{次のURLあり?}
    F -->|あり| G[Fetching: URL 出力]
    G --> H[zig fetch URL 実行]
    H --> I{成功?}
    I -->|成功| F
    I -->|失敗| J[Failed to fetch エラー・終了]
    F -->|なし| K[正常終了]
```

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

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

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 環境変数未設定 | ZIG_GLOBAL_CACHE_DIR未設定 | 環境変数を設定 |
| 1 | 取得失敗 | URLからのダウンロード失敗 | ネットワーク接続確認、URL有効性確認 |

### リトライ仕様

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

### 障害時対応

1. 環境変数未設定エラー: `export ZIG_GLOBAL_CACHE_DIR=/path/to/cache` を実行
2. 取得失敗エラー: ネットワーク接続を確認し、URLが有効か検証

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 各URL取得完了時 |
| ロールバック条件 | 途中失敗時、取得済みファイルはそのまま残る |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十URL |
| 目標処理時間 | ネットワーク速度依存（数分程度） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同一キャッシュディレクトリへの同時実行は推奨しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | - |
| 進捗ログ | 各URL取得開始時 | Fetching: URL |
| 終了ログ | なし | - |
| エラーログ | 取得失敗時 | Failed to fetch: URL |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | != 0 | 手動実行のため特になし |

## 備考

- 本スクリプトは一時的なワークアラウンドであり、将来的にZigの `zig build --fetch` が推移的依存関係を取得するようになれば不要となる（Issue: ziglang/zig#20976）
- zig fetchの出力は `/dev/null` にリダイレクトされ、エラー時のみ標準エラーに出力される
- CDPATH変数をクリアしてcd動作を予測可能にしている
