# 画面設計書 12-koch tools

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`koch tools`サブコマンドの画面設計書です。Nim関連ツール群（nimsuggest、nimgrep、nimpretty、testament等）をビルドする処理について説明します。

### 本画面の処理概要

`koch tools`は、Nimコンパイラプロジェクトに付属する開発支援ツール群をまとめてビルドするCLIサブコマンドです。このコマンドにより、IDE連携ツール、コード整形ツール、検索ツール、テストフレームワークなど、開発者が日常的に使用する各種ツールが生成されます。

**業務上の目的・背景**：Nimコンパイラだけでは開発体験は不完全です。実際の開発では、コード補完（nimsuggest）、コードフォーマット（nimpretty）、テスト実行（testament）、コード検索（nimgrep）などのツールが必要です。`koch tools`はこれらのツールを一括でビルドし、開発環境を整備します。また、Nimble（パッケージマネージャ）とAtlas（依存関係管理ツール）もビルドされ、パッケージ管理機能も利用可能になります。

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

**主要な操作・処理内容**：
1. checksumsパッケージのバンドル（nimsuggestの依存関係）
2. nimsuggestのビルド（-d:dangerオプション付き）
3. nimgrepのビルド（-d:releaseオプション付き）
4. vccexeのビルド（Windows環境のみ）
5. nimprettyのビルド（-d:releaseオプション付き）
6. testamentのビルド（-d:releaseオプション付き）
7. nim_dbgのビルド（デバッグ用コンパイラ）
8. Nimbleのビルド（外部ツール）
9. Atlasのビルド（外部ツール）

**画面遷移**：
- 遷移元: kochメイン画面（No.10）からサブコマンドとして呼び出し
- 遷移先: 生成されたツール群（No.20 nimsuggest、No.27 nimpretty、No.28 nimgrep、No.29 testament）

**権限による表示制御**：特別な権限制御はありません。ネットワーク接続が必要です（NimbleとAtlasのクローン用）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | Nimsuggest | 遷移先機能 | nimsuggestツールのビルド処理 |
| 26 | Nimpretty | 遷移先機能 | nimprettyツールのビルド処理 |
| 27 | Testament | 遷移先機能 | testamentツールのビルド処理 |
| 29 | Nimgrep | 遷移先機能 | nimgrepツールのビルド処理 |

## 画面種別

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

## URL/ルーティング

```
koch tools [options]
koch toolsNoExternal [options]  # 外部ツール（Nimble, Atlas）なし
```

コマンドラインオプション:
- 標準のNimコンパイラオプションがそのまま渡される

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| options | string | いいえ | コンパイラに渡すオプション文字列 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| bin/nimsuggest | executable | IDE支援ツール |
| bin/nimgrep | executable | 検索・置換ツール |
| bin/nimpretty | executable | コードフォーマッター |
| bin/testament | executable | テストフレームワーク |
| bin/nim_dbg | executable | デバッグ用コンパイラ |
| bin/nimble | executable | パッケージマネージャ（toolsコマンド時のみ） |
| bin/atlas | executable | 依存関係管理ツール（toolsコマンド時のみ） |
| bin/vccexe | executable | Visual C++ラッパー（Windowsのみ） |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| Compile XXX | 各ツールのコンパイル開始メッセージ |
| コンパイルコマンド | 実行されるnimコンパイルコマンド |

## イベント仕様

### 1-ツールビルド開始

```
koch tools
```

1. `buildTools()`関数が呼び出される
2. 各ツールが順番にビルドされる
3. 外部ツール（Nimble、Atlas）がビルドされる

### 2-内部ツールのみビルド

```
koch toolsNoExternal
```

1. `buildTools()`関数のみが呼び出される
2. Nimble、Atlasはビルドされない
3. ネットワーク接続が不要

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

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

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ビルド | bin/nimsuggest | CREATE/UPDATE | IDE支援ツール生成 |
| ビルド | bin/nimgrep | CREATE/UPDATE | 検索ツール生成 |
| ビルド | bin/nimpretty | CREATE/UPDATE | フォーマッター生成 |
| ビルド | bin/testament | CREATE/UPDATE | テストツール生成 |
| ビルド | bin/nim_dbg | CREATE/UPDATE | デバッグ用コンパイラ生成 |
| クローン | dist/nimble | CREATE | Nimbleリポジトリ |
| クローン | dist/atlas | CREATE | Atlasリポジトリ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | Compile nimsuggest | nimsuggestのビルド開始時 |
| MSG002 | 情報 | Compile nimgrep | nimgrepのビルド開始時 |
| MSG003 | 情報 | Compile nimpretty | nimprettyのビルド開始時 |
| MSG004 | 情報 | Compile testament | testamentのビルド開始時 |
| MSG005 | 情報 | Compile nim_dbg | nim_dbgのビルド開始時 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| ネットワークエラー | 外部リポジトリへの接続失敗 | toolsNoExternalを使用するか、ネットワーク設定を確認 |
| コンパイルエラー | ソースコードにエラーがある | エラーメッセージを表示して終了 |
| 依存関係エラー | checksumsが見つからない | bundleChecksumsを先に実行 |

## 備考

- `koch toolsNoExternal`を使用すると、ネットワーク接続なしでビルド可能
- nimsuggestは`-d:danger`でビルドされ、最大パフォーマンスで動作
- nim_dbgはデバッグ情報付きでビルドされ、問題調査に使用

---

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

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

### 推奨読解順序

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

ツールビルドで使用されるパスと定数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | 定数定義（L14-16）: NimbleStableCommit、AtlasStableCommit |
| 1-2 | koch.nim | `koch.nim` | L150-151: compileNimInst、distDir定数 |

**読解のコツ**: 外部ツールのバージョンはコミットハッシュで固定されており、`--latest`オプションでHEADを使用可能。

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

toolsコマンドの呼び出し処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | L772-775: "tools"コマンドの処理 |
| 2-2 | koch.nim | `koch.nim` | L770-771: "toolsNoExternal"コマンドの処理 |

**主要処理フロー**:
1. **L772**: `buildTools(op.cmdLineRest)`で内部ツールをビルド
2. **L773**: `bundleNimbleExe(latest, op.cmdLineRest)`でNimbleをビルド
3. **L774**: `bundleAtlasExe(latest, op.cmdLineRest)`でAtlasをビルド

#### Step 3: 各ツールのビルド処理を理解する

buildTools関数と個別のビルド関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | buildTools関数（L256-271）: ツールビルドのメインロジック |
| 3-2 | koch.nim | `koch.nim` | bundleNimsuggest関数（L196-199）: nimsuggestのビルド |
| 3-3 | koch.nim | `koch.nim` | bundleNimpretty関数（L210-212）: nimprettyのビルド |

**主要処理フロー**:
- **L257**: `bundleNimsuggest(args)`でnimsuggestをビルド
- **L258-259**: `nimCompileFold`でnimgrepをビルド
- **L260**: Windowsの場合、vccexeをビルド
- **L261**: `bundleNimpretty(args)`でnimprettyをビルド
- **L262**: `nimCompileFold`でtestamentをビルド
- **L269-271**: `nimCompileFold`でnim_dbgをビルド

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

Nimble、Atlasのビルド処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | koch.nim | `koch.nim` | bundleNimbleExe関数（L163-172）: Nimbleのビルド |
| 4-2 | koch.nim | `koch.nim` | bundleAtlasExe関数（L174-182）: Atlasのビルド |

**主要処理フロー**:
- **L165-167**: Nimbleリポジトリのクローンとサブモジュール更新
- **L168-169**: Nimbleのコンパイル
- **L176-182**: Atlasリポジトリのクローンとコンパイル

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

```
koch tools
    │
    ├─ buildTools(args)                    # 内部ツールのビルド
    │      │
    │      ├─ bundleNimsuggest(args)       # nimsuggestビルド
    │      │      ├─ bundleChecksums()     # 依存関係取得
    │      │      └─ nimCompileFold()      # コンパイル実行
    │      │
    │      ├─ nimCompileFold("nimgrep")    # nimgrepビルド
    │      │
    │      ├─ buildVccTool(args)           # Windows: vccexeビルド
    │      │
    │      ├─ bundleNimpretty(args)        # nimprettyビルド
    │      │      └─ nimCompileFold()
    │      │
    │      ├─ nimCompileFold("testament")  # testamentビルド
    │      │
    │      └─ nimCompileFold("nim_dbg")    # デバッグ用コンパイラ
    │
    ├─ bundleNimbleExe(latest, args)       # Nimbleビルド
    │      ├─ cloneDependency()            # リポジトリクローン
    │      ├─ updateSubmodules()           # サブモジュール更新
    │      └─ nimCompile()                 # コンパイル実行
    │
    └─ bundleAtlasExe(latest, args)        # Atlasビルド
           ├─ cloneDependency("atlas")     # Atlasクローン
           ├─ cloneDependency("sat")       # sat依存関係クローン
           └─ nimCompile()                 # コンパイル実行
```

### データフロー図

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

コマンドライン引数 ──────▶ parseopt処理 ────────────────▶ args, latest

nimsuggest/nimsuggest.nim ─▶ bundleNimsuggest() ────────▶ bin/nimsuggest

tools/nimgrep.nim ─────────▶ nimCompileFold() ──────────▶ bin/nimgrep

nimpretty/nimpretty.nim ───▶ bundleNimpretty() ─────────▶ bin/nimpretty

testament/testament.nim ───▶ nimCompileFold() ──────────▶ bin/testament

compiler/nim.nim ──────────▶ nimCompileFold(nim_dbg) ───▶ bin/nim_dbg

GitHub/nimble ─────────────▶ cloneDependency() + nimCompile() ─▶ bin/nimble

GitHub/atlas ──────────────▶ cloneDependency() + nimCompile() ─▶ bin/atlas
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | kochメインプログラム、buildTools関数を含む |
| nimsuggest.nim | `nimsuggest/nimsuggest.nim` | ソース | IDE支援ツールのソースコード |
| nimgrep.nim | `tools/nimgrep.nim` | ソース | 検索・置換ツールのソースコード |
| nimpretty.nim | `nimpretty/nimpretty.nim` | ソース | コードフォーマッターのソースコード |
| testament.nim | `testament/testament.nim` | ソース | テストフレームワークのソースコード |
| nim.nim | `compiler/nim.nim` | ソース | コンパイラ本体（nim_dbg用） |
| deps.nim | `tools/deps.nim` | ソース | 外部依存関係のクローン処理 |
| kochdocs.nim | `tools/kochdocs.nim` | ソース | ビルドユーティリティ関数 |
