# 機能設計書 20-Koch

## 概要

本ドキュメントは、NimのビルドシステムおよびメンテナンスツールであるKochの設計仕様を記述する。

### 本機能の処理概要

Koch（koch.nim）は、Nimコンパイラのビルド、テスト、リリース管理を行うメンテナンスプログラムである。ブートストラッピング、ドキュメント生成、パッケージ作成、テスト実行などの機能を提供する。

**業務上の目的・背景**：Nimコンパイラ自体がNimで書かれているため、ブートストラッピング（自己コンパイル）プロセスが必要である。Kochはこのプロセスを管理し、開発者が一貫した方法でコンパイラをビルド・テストできるようにする。また、リリースパッケージの作成や依存関係の管理も担当する。

**機能の利用シーン**：Nimコンパイラの開発、ビルド、テスト、リリース作成時に使用される。`koch boot`でコンパイラをビルドし、`koch tests`でテストを実行する。

**主要な処理内容**：
1. ブートストラッピング（3段階の自己コンパイル）
2. ツールのビルド（nimsuggest、nimble、atlas等）
3. ドキュメント生成
4. テスト実行
5. リリースパッケージ作成（zip、tar.xz、NSIS）
6. 依存関係のインストール

**関連システム・外部連携**：csources（Cソースからの初期ビルド）、nimble（パッケージマネージャ）、testament（テストフレームワーク）。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | すべてのkochコマンド |

## 機能種別

ビルドシステム / メンテナンスツール

## 入力仕様

### 入力パラメータ（コマンドライン）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| command | string | Yes | 実行するコマンド（boot, tests等） | 有効なコマンド |
| --help, -h | flag | No | ヘルプ表示 | - |
| --latest | flag | No | 最新版の外部コンポーネント使用 | - |
| --stable | flag | No | 安定版の外部コンポーネント使用（デフォルト） | - |
| --nim:path | string | No | nimバイナリのパス指定 | 有効なパス |
| --skipIntegrityCheck | flag | No | ブート時の整合性チェック省略 | - |

### 入力データソース

- コマンドライン引数
- 環境変数（PATH、NIM_COMPILE_TO_CPP等）
- 設定ファイル（installer.ini）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| nim.exe | 実行ファイル | コンパイルされたNimコンパイラ |
| ツール群 | 実行ファイル | nimsuggest、nimble等 |
| ドキュメント | HTML/PDF | 生成されたドキュメント |
| パッケージ | zip/tar.xz | リリースパッケージ |

### 出力先

- bin/ ディレクトリ（実行ファイル）
- doc/ ディレクトリ（ドキュメント）
- web/upload/ ディレクトリ（リリースパッケージ）

## 処理フロー

### 処理シーケンス（ブートストラップ）

```
1. 初期コンパイラ検索
   └─ findStartNim()でnim1を取得
2. 第1段階コンパイル
   └─ nim1でcompiler/nim.nimをコンパイル → nim2
3. 第2段階コンパイル
   └─ nim2でcompiler/nim.nimをコンパイル → nim3
4. 整合性チェック
   └─ nim2とnim3のバイナリ比較
5. 最終コピー
   └─ bin/nim.exeに配置
```

### フローチャート

```mermaid
flowchart TD
    A[koch boot開始] --> B[bundleChecksums]
    B --> C[findStartNim: 初期nimを検索]
    C --> D{nim見つかった?}
    D -->|No| E[build.sh/batを実行]
    D -->|Yes| F[iteration 0: nim1でnim2をビルド]
    E --> F
    F --> G[iteration 1: nim2でnim3をビルド]
    G --> H{整合性チェック?}
    H -->|Yes| I[iteration 2: nim3でnim4をビルド]
    H -->|No| J[バイナリ比較]
    I --> J
    J --> K{同一?}
    K -->|Yes| L[SUCCESS: bin/nimにコピー]
    K -->|No| M[Warning表示、bin/nimにコピー]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-20-01 | 3段階ブート | 整合性チェックありで3回、なしで2回コンパイル | boot時 |
| BR-20-02 | バイナリ整合性 | 連続するビルド結果が同一であること確認 | boot時 |
| BR-20-03 | 安定版デフォルト | 外部依存は安定版コミットを使用 | 常時 |
| BR-20-04 | nimcacheパス | release/dangerとdebugで異なるキャッシュ | コンパイル時 |

### コミット定数

| 依存関係 | 安定版コミット | 用途 |
|---------|--------------|------|
| Nimble | NimbleStableCommit | パッケージマネージャ |
| Atlas | AtlasStableCommit | ワークスペースマネージャ |
| Checksums | ChecksumsStableCommit | チェックサム計算 |
| Sat | SatStableCommit | SAT ソルバー |
| Nimony | NimonyStableCommit | Nimonyツール |

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FAILURE | 致命的エラー | nimが見つからない | build.sh/batの確認 |
| tests failed | テストエラー | テスト失敗 | テスト結果の確認 |
| git diff not empty | エラー | リリース時にgit未コミット | 変更をコミット |

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

該当なし。

## パフォーマンス要件

- ブートストラップは大規模コンパイルのため数分かかる
- --compileOnlyとjsonscriptで2段階ビルドしメモリ使用量を削減

## セキュリティ考慮事項

- 外部依存のコミットハッシュを固定しサプライチェーン攻撃を防止
- gitクローン時にHTTPSを使用

## 備考

- `koch temp`で一時的なデバッグビルドを作成可能
- `koch runCI`でCI/CDパイプラインを実行
- Windows向けにvccexeツールを提供

---

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

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

### 推奨読解順序

#### Step 1: 定数と設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | 安定版コミット定数（12-19行目）: NimbleStableCommit等 |
| 1-2 | koch.nim | `koch.nim` | HelpText定数（56-111行目）: コマンド一覧 |

#### Step 2: ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | kochExec/kochExecFold（116-120行目）: koch再帰呼び出し |
| 2-2 | koch.nim | `koch.nim` | withDir テンプレート（122-128行目）: ディレクトリ変更 |
| 2-3 | koch.nim | `koch.nim` | tryExec関数（133-135行目）: コマンド実行 |
| 2-4 | koch.nim | `koch.nim` | copyExe関数（144-147行目）: 実行ファイルコピー |

#### Step 3: ビルド関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | csource関数（153-156行目）: Cソース生成 |
| 3-2 | koch.nim | `koch.nim` | bundleNimbleExe関数（163-172行目）: Nimbleビルド |
| 3-3 | koch.nim | `koch.nim` | bundleAtlasExe関数（174-182行目）: Atlasビルド |
| 3-4 | koch.nim | `koch.nim` | bundleChecksums関数（184-194行目）: チェックサム依存 |
| 3-5 | koch.nim | `koch.nim` | buildTools関数（256-271行目）: ツール群ビルド |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | koch.nim | `koch.nim` | findStartNim関数（321-339行目）: 初期nim検索 |
| 4-2 | koch.nim | `koch.nim` | thVersion関数（341-342行目）: バージョン付きパス |
| 4-3 | koch.nim | `koch.nim` | boot関数（346-406行目）: ブートストラッピング本体 |

#### Step 5: テストとリリースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | koch.nim | `koch.nim` | tests関数（500-507行目）: テスト実行 |
| 5-2 | koch.nim | `koch.nim` | zip関数（226-236行目）: zipパッケージ作成 |
| 5-3 | koch.nim | `koch.nim` | xz関数（245-250行目）: tar.xzパッケージ作成 |
| 5-4 | koch.nim | `koch.nim` | clean関数（443-450行目）: クリーンアップ |

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

```
main()
    │
    ├─ parseopt処理
    │
    └─ コマンド分岐
           │
           ├─ boot(args, skipIntegrityCheck)
           │      ├─ bundleChecksums()
           │      ├─ findStartNim()
           │      └─ 3段階コンパイルループ
           │             └─ nimexec("c ... compiler/nim.nim")
           │
           ├─ tools(args)
           │      ├─ bundleNimsuggest()
           │      ├─ bundleNimpretty()
           │      └─ nimCompileFold()
           │
           ├─ tests(args)
           │      └─ testament実行
           │
           ├─ docs(args)
           │      └─ buildDocs()
           │
           └─ zip/xz/nsis(args)
                  ├─ bundleChecksums()
                  ├─ bundleNimbleExe()
                  ├─ bundleAtlasExe()
                  └─ niminst実行
```

### データフロー図

```
[コマンドライン入力]
         │
         ▼
[parseopt: 引数解析]
  --help, --latest, --stable, --nim:path
         │
         ▼
[コマンド判定]
         │
    ┌────┼────┬────┬────┐
    ▼    ▼    ▼    ▼    ▼
 [boot] [tools] [tests] [docs] [zip/xz]
    │
    ▼
[findStartNim]
  検索順序:
  1. nimExe環境変数
  2. bin/nim
  3. PATH上のnim
  4. build.sh/bat実行
         │
         ▼
[3段階ブートストラップ]
  nim1 → nim2 → nim3
         │
         ▼
[バイナリ比較]
  sameFileContent(nim2, nim3)
         │
         ▼
[出力: bin/nim.exe]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | メンテナンスツールメイン（約600行） |
| tools/kochdocs.nim | `tools/kochdocs.nim` | ソース | ドキュメント生成支援 |
| tools/deps.nim | `tools/deps.nim` | ソース | 依存関係管理 |
| tools/niminst/niminst.nim | `tools/niminst/niminst.nim` | ソース | インストーラー生成 |
| testament/testament.nim | `testament/testament.nim` | ソース | テストフレームワーク |
| compiler/installer.ini | `compiler/installer.ini` | 設定 | インストーラー設定 |
