# バッチ設計書 4-ci/build_autogen.bat

## 概要

本ドキュメントは、Windows用csourcesビルドスクリプト `ci/build_autogen.bat` の設計仕様を定義するものである。

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

このバッチは、Windows環境のCI（主にGitHub Actions）においてcsourcesからNimコンパイラのブートストラップビルドを行うためのスクリプトである。`build_all.bat` と同様の処理を行うが、CI環境での使用に特化した設計となっている。

**業務上の目的・背景**：GitHub ActionsなどのCI環境において、Windows上でNimコンパイラをゼロからビルドする必要がある。`ci/funs.sh` はUNIX系環境向けであるため、Windows CI環境では別途このバッチファイルを使用する。CI docsワークフローなどで、Windows環境でのドキュメントビルド前にコンパイラをビルドする際に使用される。

**バッチの実行タイミング**：GitHub Actions CI docsワークフロー（`.github/workflows/ci_docs.yml`）のWindowsジョブで実行される。csourcesからのブートストラップNimコンパイラが必要な場合に、他のCI処理の前段として実行される。

**主要な処理内容**：
1. `config/build_config.txt` からcsourcesの設定情報を読み込む
2. csourcesディレクトリが存在しない場合、Gitでクローンする
3. nim_csources_{hash}.exe が存在しない場合、csourcesをビルドする
4. ビルドしたNimコンパイラをキャッシュとして保存する

**前後の処理との関連**：このスクリプトは `config/build_config.txt` に定義された設定情報に依存している。`.github/workflows/ci_docs.yml` のWindows環境でのビルドステップから呼び出される。ビルド完了後は、後続のkochビルドやドキュメント生成処理が実行される。

**影響範囲**：`bin\` ディレクトリ配下にNimコンパイラ（nim.exe）およびキャッシュファイル（nim_csources_{hash}.exe）が生成される。csourcesディレクトリが存在しない場合は自動的にクローンされる。

## バッチ種別

CI/CDビルド処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | CI実行時（プッシュ/PR時） |
| 実行時刻 | CI実行タイミング |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actions（ci_docs.yml） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| OS | Windows |
| Git | csourcesリポジトリのクローンに必要 |
| Cコンパイラ | Visual C++ または MinGW |
| CI環境 | GitHub ActionsのWindowsランナー |

### 実行可否判定

- `bin\nim_csources_{hash}.exe` が存在する場合、csourcesのビルドはスキップされる
- csourcesディレクトリが存在する場合、git cloneはスキップされる
- スクリプトは安全に再実行可能（冪等性を持つ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| PROCESSOR_ARCHITECTURE | 環境変数 | No | 自動検出 | CPUアーキテクチャ（AMD64等） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| config/build_config.txt | テキスト | csourcesのバージョン情報（nim_csourcesHash、nim_csourcesBranch、nim_csourcesUrl、nim_csourcesDir） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| bin\nim.exe | 実行可能ファイル | ビルドされたNimコンパイラ |
| bin\nim_csources_{hash}.exe | 実行可能ファイル | ブートストラップに使用したNimコンパイラのキャッシュ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | nim.exe, nim_csources_{hash}.exe |
| 出力先 | bin\ |
| 文字コード | N/A（バイナリファイル） |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 設定読み込み
   └─ config/build_config.txt から変数を読み込み（for /f ループ）
2. nim_csources変数の設定
   └─ bin\nim_csources_{hash}.exe のパスを設定
3. 進捗ログ出力
   └─ "building from csources: {path}" を表示
4. csourcesディレクトリの確認
   └─ 存在しない場合、git clone を実行
5. nim_csources.exe存在確認
   └─ 存在する場合はスキップ
6. csourcesディレクトリに移動
   └─ cd %nim_csourcesDir%
7. ハッシュをチェックアウト
   └─ git checkout %nim_csourcesHash%
8. アーキテクチャ設定
   └─ AMD64の場合、ARCH=64
9. build.bat実行
   └─ csourcesのbuild.batを呼び出し
10. キャッシュ保存
    └─ bin\nim.exe を nim_csources_{hash}.exe にコピー
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[config/build_config.txt読み込み]
    B --> C[nim_csources変数設定]
    C --> D[進捗ログ出力]
    D --> E{csourcesディレクトリ存在?}
    E -->|なし| F[git clone csources]
    E -->|あり| G{nim_csources.exe存在?}
    F --> G
    G -->|あり| H[処理終了]
    G -->|なし| I[cd csourcesDir]
    I --> J[git checkout hash]
    J --> K[アーキテクチャ確認]
    K --> L{AMD64?}
    L -->|Yes| M[ARCH=64設定]
    L -->|No| N[build.bat実行]
    M --> N
    N --> O[cd ..]
    O --> P[nim.exeをキャッシュにコピー]
    P --> H
```

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

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

該当なし（このバッチはデータベースを使用しない）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | git clone失敗 | ネットワークエラー、認証エラー | CI再実行、ネットワーク確認 |
| 1 | git checkout失敗 | 指定ハッシュが存在しない | csourcesのバージョンを確認 |
| 1 | build.bat失敗 | Cコンパイラエラー | CI環境のコンパイラ設定を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし、CI側で制御） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. CIログを確認し、失敗したコマンドを特定
2. 一般的な対処：
   - CIを再実行
   - csourcesのバージョン（ハッシュ）が正しいか確認
   - Windows CI環境のコンパイラ設定を確認
3. ローカルでの再現テストを実施

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース不使用） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | N/A |
| 目標処理時間 | 約3-5分（CI環境依存） |
| メモリ使用量上限 | 約2GB（コンパイル時） |

## 排他制御

- CI環境では各ジョブが独立したワークスペースで実行されるため、排他制御は不要
- 同一ワークスペースでの同時実行は想定されていない

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 処理開始時 | "building from csources: {path}" |
| アーキテクチャログ | ビルド前 | PROCESSOR_ARCHITECTURE の値 |
| エラーログ | エラー発生時 | コマンドプロンプトの標準エラー出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 60分（CIタイムアウト） | GitHub Actionsの失敗通知 |
| 終了コード | 0以外 | GitHub Actionsの失敗通知 |

## 備考

- このスクリプトは `nim r tools/ci_generate.nim` により自動生成される
- `ci/funs.sh` のWindows版の最小実装として機能
- kochビルドやtools ビルドは含まれず、csourcesからのブートストラップのみを行う
- `.github/workflows/ci_docs.yml` の `Build csourcesAny (windows)` ステップで使用される
- UNIX/Linux/macOS環境では代わりに `ci/funs.sh` の `nimBuildCsourcesIfNeeded` 関数を使用する
