# 画面設計書 10-kochメイン画面

## 概要

本ドキュメントは、Nimプロジェクトのビルド・保守用CLIツール`koch`のメインインターフェース設計書です。

### 本画面の処理概要

`koch`は、Nimコンパイラ自身のビルドやメンテナンスを行うためのCLIツールです。コンパイラのブートストラップ、関連ツールのビルド、ドキュメント生成、テスト実行、配布パッケージの作成など、Nimプロジェクトの開発・保守に必要な様々な機能を提供します。

**業務上の目的・背景**：Nimコンパイラの開発者やコントリビューターが、コンパイラ自体のビルドや各種開発タスクを効率的に実行できるようにします。Nimのセルフホスティング（自分自身でコンパイラをビルドする）を実現する中核ツールです。

**画面へのアクセス方法**：ターミナルから`koch <command> [options]`を実行します。

**主要な操作・処理内容**：
1. コマンドライン引数の解析
2. 指定されたコマンドの実行
3. 外部ツール（nim, nimble等）の呼び出し
4. ビルド・テスト結果の報告

**画面遷移**：
- 入力元：ターミナルから直接実行
- 遷移先：各サブコマンドに応じた処理（boot, tools, docs, tests等）

**権限による表示制御**：OSのファイルシステム権限および実行権限に依存。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | Koch | 主機能 | Nimのビルドシステムおよびメンテナンスツールのメイン処理 |

## 画面種別

CLIメインコマンド（ビルドツール）

## URL/ルーティング

```
koch [options] command [options for command]
```

主要コマンド：
- `koch boot [options]` - コンパイラのブートストラップ
- `koch tools` - 関連ツール群のビルド
- `koch docs [options]` - ドキュメント全体の生成
- `koch tests [options]` - テストスイートの実行
- `koch csource` - Cソースファイルの生成
- `koch zip` - インストール用ZIPパッケージの作成
- `koch xz` - インストール用tar.xzパッケージの作成
- `koch nimble` - Nimbleパッケージマネージャのビルド
- `koch atlas` - Atlasツールのビルド

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| command | string | 入力 | はい | 実行するコマンド名 |
| --help, -h | flag | 入力 | いいえ | ヘルプ表示 |
| --latest | flag | 入力 | いいえ | 最新版の外部コンポーネントを使用 |
| --stable | flag | 入力 | いいえ | 安定版の外部コンポーネントを使用（デフォルト） |
| --nim:path | string | 入力 | いいえ | 使用するnimバイナリのパス |
| --localdocs[:path] | string | 入力 | いいえ | ローカルドキュメントのみビルド |
| --skipIntegrityCheck | flag | 入力 | いいえ | ブート時の整合性チェックをスキップ |
| 標準出力 | text | 出力 | - | ビルド進捗・結果 |
| 標準エラー | text | 出力 | - | エラー出力 |
| 終了コード | int | 出力 | - | 0:成功、非0:エラー |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| バージョン情報 | kochのバージョン | --help時 |
| ビルド時刻 | コンパイル日時 | --help時 |
| 利用可能コマンド | コマンド一覧 | --help時 |
| 進捗メッセージ | ビルド・テスト進捗 | コマンド実行時 |
| 成功/失敗メッセージ | 実行結果 | コマンド完了時 |

## イベント仕様

### 1-初期化処理

`koch.nim`の初期化（行130-131）：

```nim
let origDir = getCurrentDir()
setCurrentDir(getAppDir())
```

作業ディレクトリをkochの実行ファイルがあるディレクトリに変更。

### 2-コマンドライン解析

`when isMainModule`ブロック（行720-791）でコマンドライン解析：

```nim
var op = initOptParser()
var
  latest = false
  localDocsOnly = false
  localDocsOut = ""
  skipIntegrityCheck = false
while true:
  op.next()
  case op.kind
  of cmdLongOption, cmdShortOption:
    case normalize(op.key)
    of "help", "h": showHelp(success = true)
    of "latest": latest = true
    of "stable": latest = false
    of "nim": nimExe = op.val.absolutePath
    ...
```

### 3-コマンド振り分け

行743-788でコマンドを各処理関数に振り分け：

| コマンド | 処理関数 | 説明 |
|----------|----------|------|
| boot | `boot(op.cmdLineRest, skipIntegrityCheck)` | ブートストラップ |
| clean | `clean(op.cmdLineRest)` | クリーンアップ |
| doc, docs | `buildDocs(...)` | ドキュメント生成 |
| csource, csources | `csource(op.cmdLineRest)` | Cソース生成 |
| zip | `zip(latest, op.cmdLineRest)` | ZIPパッケージ作成 |
| xz | `xz(latest, op.cmdLineRest)` | tar.xzパッケージ作成 |
| nsis | `nsis(latest, op.cmdLineRest)` | NSISインストーラ作成 |
| tests | `tests(op.cmdLineRest)` | テスト実行 |
| tools | `buildTools(...)` | ツールビルド |
| nimble | `bundleNimbleExe(latest, op.cmdLineRest)` | Nimbleビルド |
| atlas | `bundleAtlasExe(latest, op.cmdLineRest)` | Atlasビルド |
| checksums | `bundleChecksums(latest)` | checksums依存インストール |
| runci | `runCI(op.cmdLineRest)` | CI実行 |

### 4-ブートストラップ処理

`boot`関数（行346-407）：

1. **行354-355**: 出力先設定（`compiler/nim.exe`と`bin/nim.exe`）
2. **行358-359**: nimcacheディレクトリ決定（release/debug）
3. **行361**: `bundleChecksums(false)` - 依存関係インストール
4. **行367**: `findStartNim()` - 初期nimコンパイラ検索
5. **行369-402**: 3回のイテレーションでブートストラップ
   - nim1.exe: csourcesからビルド
   - nim2.exe: nim1.exeでビルド
   - nim3.exe: nim2.exeでビルド（整合性確認）

### 5-ツールビルド処理

`buildTools`関数（行256-271）：

```nim
proc buildTools(args: string = "") =
  bundleNimsuggest(args)
  nimCompileFold("Compile nimgrep", "tools/nimgrep.nim", ...)
  when defined(windows): buildVccTool(args)
  bundleNimpretty(args)
  nimCompileFold("Compile testament", "testament/testament.nim", ...)
  nimCompileFold("Compile nim_dbg", "compiler/nim.nim", ...)
```

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

本CLIツールはデータベースを使用しません。

### ファイルシステム操作

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| ビルド | compiler/*.nim | READ | コンパイラソース読み込み |
| ビルド | bin/* | WRITE | 実行ファイル出力 |
| ビルド | nimcache/* | WRITE | 中間ファイル出力 |
| クローン | dist/* | WRITE | 外部依存のクローン |
| ドキュメント | doc/*.html | WRITE | HTMLドキュメント出力 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| 情報 | "iteration: N" | ブートストラップ各イテレーション |
| 成功 | "executables are equal: SUCCESS!" | ブートストラップ成功 |
| 警告 | "[Warning] executables are still not equal" | 整合性チェック失敗 |
| エラー | "FAILURE" | 致命的エラー |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| nimコンパイラ不在 | "Found no nim compiler and every attempt to build one failed!" | quit |
| 不明なコマンド | ヘルプ表示 | showHelp(success = false) |
| テスト失敗 | "tests failed" | quit(QuitFailure) |

## 備考

- Nimのセルフホスティングを実現する中核ツール
- csourcesリポジトリからの初回ビルドをサポート
- 外部依存（Nimble, Atlas等）の安定版/最新版を選択可能
- `--skipIntegrityCheck`でブートストラップの整合性チェックをスキップ可能
- CIパイプライン用の`runCI`コマンドを提供
- Windows向けにNSISインストーラ生成をサポート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | 定数定義（行12-26）：安定版コミットハッシュ |
| 1-2 | koch.nim | `koch.nim` | HelpText定数（行56-111）：ヘルプメッセージ |

**読解のコツ**: `NimbleStableCommit`, `AtlasStableCommit`等のコミットハッシュが外部依存のバージョン管理に使用される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | when isMainModule（行720-791） |
| 2-2 | koch.nim | `koch.nim` | コマンド振り分け（行743-788） |

**主要処理フロー**:
1. **行720-726**: 変数初期化（latest, localDocsOnly等）
2. **行727-742**: オプション解析ループ
3. **行743-788**: コマンドに応じた関数呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | findStartNim関数（行321-339） |
| 3-2 | koch.nim | `koch.nim` | boot関数（行346-407） |

**主要処理フロー**:
- **行321-339**: 初期nimコンパイラの検索（nimExe, bin/nim, PATH, build.sh/bat）
- **行346-407**: 3回のイテレーションでブートストラップ
  - `--compileOnly`でJSONファイル生成
  - `jsonscript`でバイナリ生成
  - 実行ファイルの一致確認

#### Step 4: ツールビルドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | koch.nim | `koch.nim` | buildTools関数（行256-271） |
| 4-2 | koch.nim | `koch.nim` | bundleNimsuggest関数（行196-199） |
| 4-3 | koch.nim | `koch.nim` | bundleNimbleExe関数（行163-172） |

**主要処理フロー**:
- nimsuggest, nimgrep, nimpretty, testamentをビルド
- nim_dbgデバッグ版コンパイラをビルド
- 外部ツール（nimble, atlas）はcloneDependencyでクローン後ビルド

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

```
koch.nim::main
    │
    ├─ setCurrentDir(getAppDir())
    │
    ├─ initOptParser()
    │
    ├─ オプション解析ループ
    │      │
    │      ├─ --help → showHelp()
    │      ├─ --latest → latest = true
    │      ├─ --stable → latest = false
    │      ├─ --nim:path → nimExe = path
    │      └─ --skipIntegrityCheck → skipIntegrityCheck = true
    │
    └─ コマンド振り分け
           │
           ├─ boot → boot()
           │           │
           │           ├─ bundleChecksums()
           │           ├─ findStartNim()
           │           └─ 3回イテレーション
           │                  ├─ nim c --compileOnly
           │                  └─ nim jsonscript
           │
           ├─ tools → buildTools()
           │           │
           │           ├─ bundleNimsuggest()
           │           ├─ nimCompileFold(nimgrep)
           │           ├─ bundleNimpretty()
           │           ├─ nimCompileFold(testament)
           │           └─ nimCompileFold(nim_dbg)
           │
           ├─ docs → buildDocs()
           │
           ├─ tests → tests()
           │           │
           │           └─ testament実行
           │
           ├─ csource → csource()
           │
           ├─ zip → zip()
           │
           ├─ xz → xz()
           │
           ├─ nimble → bundleNimbleExe()
           │
           ├─ atlas → bundleAtlasExe()
           │
           └─ runci → runCI()
```

### データフロー図

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

コマンドライン ───▶ initOptParser() ───▶ オプション解析
                         │
                         ▼
               ┌─────────────────┐
               │  コマンド振り分け │
               └────────┬────────┘
                        │
    ┌───────────────────┼───────────────────┐
    │                   │                   │
    ▼                   ▼                   ▼
[boot]              [tools]             [docs]
    │                   │                   │
    ▼                   ▼                   ▼
csources ───▶ nim1 ───▶ nim2 ───▶ nim3 → bin/nim.exe
                        │
nimsuggest.nim ───▶ nimCompile ───▶ bin/nimsuggest.exe
nimgrep.nim ───▶ nimCompile ───▶ bin/nimgrep.exe
                        │
                        ▼
                  [tests実行]
                        │
                        ▼
              testament ───▶ テスト結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | メインエントリーポイント、コマンド処理 |
| kochdocs.nim | `tools/kochdocs.nim` | ソース | ドキュメントビルド関連 |
| deps.nim | `tools/deps.nim` | ソース | 依存関係管理、クローン処理 |
| niminst.nim | `tools/niminst/niminst.nim` | ソース | インストーラ生成 |
| testament.nim | `testament/testament.nim` | ソース | テストフレームワーク |
