# 画面設計書 11-koch boot

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`koch boot`サブコマンドの画面設計書です。kochツールのブートストラップ機能について、その処理内容、入出力仕様、および関連するコードの構造を説明します。

### 本画面の処理概要

`koch boot`は、Nimコンパイラ自体をビルドするためのブートストラップ処理を実行するCLIサブコマンドです。このコマンドは、既存のNimコンパイラ（またはCソースからビルドされた初期コンパイラ）を使用して、新しいNimコンパイラをビルドする一連のプロセスを自動化します。

**業務上の目的・背景**：ブートストラップは、Nimコンパイラの開発・保守において最も重要なプロセスの一つです。Nimコンパイラ自身がNim言語で書かれているため、コンパイラをビルドするにはコンパイラが必要という「鶏と卵」の問題を解決します。この問題を解決するため、CソースからビルドされたNim（nim1）を使って新しいNim（nim2）をビルドし、さらにnim2でnim3をビルドして整合性を確認する3段階のプロセスを実行します。これにより、コンパイラの品質保証と自己ホスティング能力が確保されます。

**画面へのアクセス方法**：ターミナルから以下のコマンドを実行します。
```
koch boot [options]
```

**主要な操作・処理内容**：
1. 初期Nimコンパイラの検出（bin/nim、PATH上のnim、またはbuild.shによるビルド）
2. checksumsパッケージのバンドル処理
3. libffiの依存関係インストール（--d:nimHasLibFFI指定時）
4. 3段階のコンパイル実行（nim1→nim2→nim3）
5. 各段階でのコンパイルオプション適用（--compileOnly、jsonscript）
6. 実行可能ファイルの比較による整合性チェック
7. 最終的なコンパイラをbin/nim.exeとしてインストール

**画面遷移**：
- 遷移元: kochメイン画面（No.10）からサブコマンドとして呼び出し
- 遷移先: なし（ビルド完了後は自動的に終了）
- 関連: 生成されたコンパイラ（bin/nim）は他のすべてのNimコマンド（No.1〜9）の基盤となる

**権限による表示制御**：特別な権限制御はありません。ファイルシステムへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | ブートストラップ | 主機能 | Cソースからコンパイラをブートストラップビルドする処理 |
| 1 | Nimコンパイラ本体 | 遷移先機能 | ブートストラップ完了後のコンパイラ生成 |

## 画面種別

CLIコマンド実行画面（バッチ処理型）

## URL/ルーティング

```
koch boot [options]
```

コマンドラインオプション:
- `-d:release`: リリースビルドを生成
- `-d:danger`: 最大最適化でビルド
- `-d:nimUseLinenoise`: lineoiseライブラリを使用
- `-d:leanCompiler`: 軽量コンパイラをビルド（JS生成、ドキュメント生成なし）
- `-d:nimHasLibFFI`: FFIサポートを追加
- `--skipIntegrityCheck`: 整合性チェックをスキップ

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| options | string | いいえ | コンパイラに渡すオプション文字列 |
| --skipIntegrityCheck | flag | いいえ | 整合性チェックをスキップするフラグ |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| bin/nim | executable | 生成されたNimコンパイラ |
| compiler/nim0.exe | executable | 第1段階の中間コンパイラ |
| compiler/nim1.exe | executable | 第2段階の中間コンパイラ |
| compiler/nim2.exe | executable | 第3段階の中間コンパイラ |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| iteration | 現在のビルド段階（iteration: 1, 2, 3） |
| コンパイルコマンド | 実行されるnimコンパイルコマンド |
| SUCCESS | 整合性チェック成功メッセージ |
| Warning | 整合性チェック失敗時の警告（Unix環境のみ） |

## イベント仕様

### 1-ブートストラップ開始

```
koch boot -d:release
```

1. `findStartNim()`で初期Nimコンパイラを検出
2. `bundleChecksums(false)`でchecksumsパッケージをクローン
3. libffiが必要な場合は`installDeps("libffi")`を実行
4. 3段階のビルドループを開始

### 2-各段階のコンパイル

各iterationで以下を実行：
1. `--compileOnly`オプションでNimソースをCに変換
2. `jsonscript`でCコードからバイナリを生成
3. 生成された実行ファイルを比較

### 3-整合性チェック

- nim2とnim3が同一の場合: "executables are equal: SUCCESS!"を出力
- 異なる場合: 警告を表示（`--skipIntegrityCheck`未指定時）

## データベース更新仕様

本コマンドはデータベースを使用しません。

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

該当なし（ファイルシステム操作のみ）

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ビルド | compiler/nim.exe | CREATE | コンパイラ実行ファイル生成 |
| コピー | bin/nim.exe | CREATE/UPDATE | 最終的なコンパイラのインストール |
| 生成 | nimcache/* | CREATE | コンパイル中間ファイル |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | iteration: N | 各ビルド段階の開始時 |
| MSG002 | 成功 | executables are equal: SUCCESS! | 整合性チェック成功時 |
| MSG003 | 警告 | [Warning] executables are still not equal | 整合性チェック失敗時（Unix） |
| MSG004 | エラー | Found no nim compiler and every attempt to build one failed! | 初期コンパイラが見つからない場合 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| コンパイラ未検出 | nim実行ファイルが見つからない | build.shの実行を試行後、エラー終了 |
| コンパイルエラー | ソースコードにエラーがある | エラーメッセージを表示して終了 |
| 権限エラー | bin/ディレクトリへの書き込み権限がない | OSエラーを表示 |

## 備考

- ブートストラップは通常2〜3分程度かかります
- `--skipIntegrityCheck`を指定するとビルド時間が短縮されますが、品質保証は低下します
- 環境変数`NIM_COMPILE_TO_CPP=true`でC++としてコンパイル可能

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

kochのブートストラップ処理で使用される主要な定数と変数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | 定数定義（L12-30）: NimbleStableCommit、ChecksumsStableCommit等のバージョン管理用定数 |
| 1-2 | koch.nim | `koch.nim` | HelpText定数（L56-111）: コマンドヘルプとオプション一覧 |

**読解のコツ**: Nimの定数は`const`ブロックで定義され、コンパイル時に評価されます。バージョン管理用のコミットハッシュは依存関係の固定に使用されます。

#### Step 2: エントリーポイントを理解する

kochコマンドのメイン処理とブートストラップへの分岐を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | isMainModule（L720-792）: コマンドライン引数の解析とサブコマンドへの分岐 |
| 2-2 | koch.nim | `koch.nim` | L745: "boot"コマンドの呼び出し `boot(op.cmdLineRest, skipIntegrityCheck)` |

**主要処理フロー**:
1. **L721**: `initOptParser()`でコマンドライン解析を初期化
2. **L727-742**: オプション（--latest, --stable, --nim, --skipIntegrityCheck）の処理
3. **L745**: `boot()`関数を呼び出してブートストラップを開始

#### Step 3: ブートストラップ処理を理解する

boot関数の詳細な処理フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | boot関数（L346-407）: ブートストラップのメインロジック |
| 3-2 | koch.nim | `koch.nim` | findStartNim関数（L321-339）: 初期コンパイラの検出 |

**主要処理フロー**:
- **L346-353**: 関数シグネチャとブートストラップの概要コメント
- **L354-359**: 出力先と中間ファイル名の設定
- **L361**: `bundleChecksums(false)`でchecksumsの依存関係を取得
- **L363-365**: libffiの依存関係処理
- **L367-368**: 初期コンパイラの検出とビルド回数の計算
- **L369-402**: 3段階のビルドループ

#### Step 4: 依存関係管理を理解する

外部依存関係（checksums、libffi等）の取得処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | tools/deps.nim | `tools/deps.nim` | cloneDependency関数（L23-48）: Gitリポジトリのクローン処理 |
| 4-2 | koch.nim | `koch.nim` | bundleChecksums関数（L184-194）: checksumsとnimonyのバンドル |
| 4-3 | koch.nim | `koch.nim` | installDeps関数（L303-317）: 外部依存関係のインストール |

**主要処理フロー**:
- **deps.nim L23-48**: Gitリポジトリをクローンし、指定コミットをチェックアウト
- **koch.nim L184-194**: checksums、nimony、nifler、nifmakeをビルド

### プログラム呼び出し階層図

```
koch boot
    │
    ├─ findStartNim()                    # 初期コンパイラの検出
    │      └─ findNimImpl()              # tools/kochdocs.nim
    │
    ├─ bundleChecksums(false)            # 依存関係の取得
    │      ├─ cloneDependency()          # tools/deps.nim
    │      ├─ nimCompileFold("nifler")   # niflerのビルド
    │      └─ nimCompileFold("nifmake")  # nifmakeのビルド
    │
    ├─ installDeps("libffi")             # オプション: FFI依存
    │      └─ cloneDependency()
    │
    └─ [ビルドループ x3]
           ├─ exec("nim c --compileOnly")  # Cコード生成
           ├─ exec("nim jsonscript")        # バイナリ生成
           ├─ sameFileContent()             # 整合性チェック
           └─ copyExe()                     # ファイルコピー
```

### データフロー図

```
[入力]                    [処理]                         [出力]

コマンドライン引数 ──────▶ parseopt.initOptParser() ──▶ オプション解析

csources/nim ─────────────▶ findStartNim() ─────────────▶ nim1 (初期コンパイラ)

nim1 + compiler/nim.nim ──▶ exec("nim c --compileOnly") ─▶ nimcache/*.c

nimcache/*.c ─────────────▶ exec("nim jsonscript") ─────▶ compiler/nim.exe

compiler/nim.exe ─────────▶ sameFileContent() ──────────▶ 整合性チェック結果

compiler/nim.exe ─────────▶ copyExe() ──────────────────▶ bin/nim.exe
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | kochメインプログラム、boot関数を含む |
| deps.nim | `tools/deps.nim` | ソース | 外部依存関係のクローン・更新処理 |
| kochdocs.nim | `tools/kochdocs.nim` | ソース | ビルドユーティリティ関数（findNim, exec等） |
| nim.nim | `compiler/nim.nim` | ソース | ブートストラップ対象のNimコンパイラ本体 |
| installer.ini | `compiler/installer.ini` | 設定 | インストーラ設定（バージョン情報等） |
| build.sh | `build.sh` | スクリプト | 初期コンパイラビルド用シェルスクリプト（Unix） |
| build.bat | `build.bat` | スクリプト | 初期コンパイラビルド用バッチファイル（Windows） |
