# バッチ設計書 16-koch.nim（boot）

## 概要

本ドキュメントは、Nimコンパイラのブートストラップ処理を行う `koch boot` コマンドの設計書です。このコマンドはNimコンパイラを自身でコンパイル（セルフホスティング）するための3段階ビルドプロセスを実行します。

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

このバッチは、Nimコンパイラの開発において最も重要なブートストラップ処理を実行します。ブートストラップとは、コンパイラが自身をコンパイルできるようにする自己言及的なビルドプロセスです。初期のCソースからコンパイラを構築し、そのコンパイラで新しいコンパイラをビルドすることを繰り返し、最終的に安定したコンパイラを生成します。

**業務上の目的・背景**：Nimコンパイラは自己ホスティング言語であり、Nim自身でNimコンパイラを記述しています。新しいバージョンのコンパイラをビルドするには、既存のコンパイラを使って新しいソースをコンパイルする必要があります。このブートストラップ処理により、コンパイラの変更が正しく機能することを検証し、安定したビルドを生成します。

**バッチの実行タイミング**：以下のタイミングで実行されます：
- Nimソースコードの初回ビルド時
- コンパイラのソースコードを変更した後
- CI/CDパイプラインでのビルド検証時
- リリースビルドの作成時

**主要な処理内容**：
1. checksums依存パッケージのインストール
2. libffi依存パッケージのインストール（必要な場合）
3. 初期Nimコンパイラ（nim0）の特定または構築
4. nim0を使用してnim1をコンパイル（1回目のブートストラップ）
5. nim1を使用してnim2をコンパイル（2回目のブートストラップ）
6. nim2を使用してnim3をコンパイル（3回目のブートストラップ、整合性チェック用）
7. nim2とnim3が同一であることを確認
8. 最終的なnim.exeをbin/に配置

**前後の処理との関連**：csourcesからの初期ビルド（build.shまたはbuild.bat）が事前に実行されている必要があります。ブートストラップ後は、`koch tools`でツール群のビルド、`koch runCI`でCI実行などが可能になります。

**影響範囲**：compiler/nim.exe、bin/nim.exe、nimcacheディレクトリ、およびcompiler/nim1.exe、compiler/nim2.exe、compiler/nim3.exe（中間ファイル）に影響します。

## バッチ種別

ビルド / コンパイラブートストラップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発時、CI時） |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 / CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| 初期Nimコンパイラが利用可能 | bin/nim、csourcesからビルドしたnim、またはPATH上のnimのいずれか |
| Cコンパイラが利用可能 | GCC、Clang、またはMSVCがインストールされていること |
| compiler/nim.nimが存在 | Nimコンパイラのソースコードが必要 |
| koch.nimがコンパイル済み | kochコマンドが実行可能であること |

### 実行可否判定

初期Nimコンパイラが見つからない場合、build.shまたはbuild.batを自動実行して構築を試みます。それでも失敗した場合はエラー終了します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| -d:release | フラグ | No | なし | リリースビルドを生成 |
| -d:danger | フラグ | No | なし | 最適化優先ビルドを生成 |
| -d:nimUseLinenoise | フラグ | No | なし | linenoiseライブラリを使用 |
| -d:leanCompiler | フラグ | No | なし | 軽量コンパイラをビルド |
| -d:nimHasLibFFI | フラグ | No | なし | FFIサポートを有効化 |
| --skipIntegrityCheck | フラグ | No | なし | 整合性チェックをスキップ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| compiler/nim.nim | Nimソースファイル | Nimコンパイラのメインソース |
| lib/ | ディレクトリ | Nim標準ライブラリ |
| dist/checksums/ | ディレクトリ | checksumsパッケージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| bin/nim.exe | 実行ファイル | 最終的なNimコンパイラ |
| compiler/nim.exe | 実行ファイル | コンパイル直後のNimコンパイラ |
| compiler/nim1.exe | 実行ファイル | 1回目ブートストラップの成果物 |
| compiler/nim2.exe | 実行ファイル | 2回目ブートストラップの成果物 |
| compiler/nim3.exe | 実行ファイル | 3回目ブートストラップの成果物 |
| nimcache/ | ディレクトリ | コンパイルキャッシュ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | nim.exe（または.nimに応じた拡張子なし） |
| 出力先 | bin/ |
| 文字コード | バイナリ |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 依存パッケージの準備
   └─ bundleChecksums(false)でchecksumsをインストール
2. libffiインストール（オプション）
   └─ -d:nimHasLibFFI指定時のみdist/libffiをインストール
3. 初期コンパイラの特定
   └─ findStartNim()でnim0を特定（bin/nim、PATH上のnim、またはbuild.shで構築）
4. smartNimcache設定
   └─ release/dangerの場合は"nimcache/r_"、それ以外は"nimcache/d_"プレフィックス
5. 1回目ブートストラップ（イテレーション0）
   └─ nim0でcompiler/nim.nimをコンパイル
   └─ --skipUserCfg --skipParentCfg -d:nimKochBootstrapオプション追加
   └─ --compileOnlyで.jsonファイル生成後、jsonscriptでビルド
6. 2回目ブートストラップ（イテレーション1）
   └─ nim1でcompiler/nim.nimをコンパイル
7. 3回目ブートストラップ（イテレーション2、整合性チェック時のみ）
   └─ nim2でcompiler/nim.nimをコンパイル
8. 整合性チェック
   └─ nim2とnim3が同一内容か確認（sameFileContent）
9. 最終コンパイラ配置
   └─ compiler/nim.exeをbin/nim.exeにコピー
```

### フローチャート

```mermaid
flowchart TD
    A[boot開始] --> B[checksumsインストール]
    B --> C{libffi必要?}
    C -->|Yes| D[libffiインストール]
    C -->|No| E[初期コンパイラ特定]
    D --> E
    E --> F{nim0見つかった?}
    F -->|No| G[build.sh実行]
    G --> H{ビルド成功?}
    H -->|No| Z[エラー終了]
    H -->|Yes| I
    F -->|Yes| I[nim0でnim1をビルド]
    I --> J[nim1でnim2をビルド]
    J --> K{整合性チェック有効?}
    K -->|Yes| L[nim2でnim3をビルド]
    L --> M{nim2 == nim3?}
    M -->|Yes| N[bin/nimにコピー]
    M -->|No| O[警告出力]
    O --> N
    K -->|No| N
    N --> P[boot完了]
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | N/A |

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FAILURE | 初期コンパイラなし | nim0が見つからずbuild.shも失敗 | csourcesが正しく配置されているか確認 |
| コンパイルエラー | ソースエラー | compiler/nim.nimのコンパイル失敗 | ソースコードのエラーを修正 |
| 警告 | 整合性不一致 | nim2とnim3が異なる | コンパイラのバグの可能性、調査が必要 |

### リトライ仕様

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

### 障害時対応

1. 初期コンパイラが見つからない場合：csourcesディレクトリが存在し、build.sh/build.batが実行可能か確認
2. コンパイルエラーの場合：エラーメッセージを確認し、ソースコードを修正
3. 整合性チェック失敗の場合：通常は警告のみで続行。重大な問題がある可能性があるため調査推奨

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回のブートストラップ実行 |
| 目標処理時間 | 数分〜10分程度（環境依存） |
| メモリ使用量上限 | 数GB（コンパイル中のピーク時） |

## 排他制御

同一ディレクトリで同時に複数のbootを実行すると、nimcacheや中間ファイルが競合します。同時実行は非推奨です。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各イテレーション開始時 | "iteration: N" |
| 成功ログ | 整合性チェック成功時 | "executables are equal: SUCCESS!" |
| 警告ログ | 整合性チェック失敗時 | "[Warning] executables are still not equal" |
| コマンドログ | コマンド実行時 | 実行されるコンパイルコマンド |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド結果 | 非ゼロ終了コード | CI/CDシステム |
| 整合性チェック | 不一致時 | 標準出力（警告） |

## 備考

- ブートストラップが3段階なのは、コンパイラの自己整合性を検証するためです
- nim1は古いコンパイラでビルドされるため、新機能を使用できません
- nim2は新しいコンパイラでビルドされ、新機能が使用可能です
- nim3はnim2と同一であるべきで、これによりコンパイラが安定していることを確認できます
- `--skipIntegrityCheck`オプションを使用すると、3回目のイテレーションをスキップして時間を短縮できます
- メモリ削減のため、`--compileOnly`と`jsonscript`の2段階でビルドを行います
- NIM_COMPILE_TO_CPP環境変数を"true"に設定すると、C++バックエンドでコンパイルします
