# バッチ設計書 17-koch.nim（tools）

## 概要

本ドキュメントは、Nimコンパイラに関連するツール群をビルドする `koch tools` コマンドの設計書です。このコマンドはnimsuggest、nimgrep、nimpretty、testament、nim_dbgなどの開発支援ツールをビルドします。

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

このバッチは、Nim開発エコシステムを構成する重要なツール群を一括でビルドします。これらのツールは、コード補完（nimsuggest）、テキスト検索（nimgrep）、コードフォーマット（nimpretty）、テスト実行（testament）、デバッグ（nim_dbg）など、Nim開発者の日常的な作業を支援します。

**業務上の目的・背景**：Nimコンパイラ本体だけでなく、開発者の生産性を向上させるための周辺ツールが重要です。これらのツールはエディタ統合、コード品質維持、テスト自動化などに不可欠であり、一括でビルドすることで開発環境のセットアップを効率化します。また、外部パッケージ管理ツール（nimble、atlas）も同時にビルドすることで、完全な開発環境を構築できます。

**バッチの実行タイミング**：以下のタイミングで実行されます：
- Nimの初回インストール後
- コンパイラのブートストラップ（koch boot）後
- CI/CDパイプラインでのツールビルド時
- ツールのソースコードを変更した後

**主要な処理内容**：
1. nimsuggestのビルド（コード補完・解析ツール）
2. nimgrepのビルド（Nim対応検索ツール）
3. vccexeのビルド（Windows VCCコンパイラ用、Windowsのみ）
4. nimprettyのビルド（コードフォーマッター）
5. testamentのビルド（テストランナー）
6. nim_dbgのビルド（デバッグ用コンパイラ）
7. nimbleのビルド（パッケージマネージャー、外部依存）
8. atlasのビルド（プロジェクト管理ツール、外部依存）

**前後の処理との関連**：`koch boot`でNimコンパイラがビルドされている必要があります。ツールビルド後は、各ツールがbin/ディレクトリに配置され、すぐに使用可能になります。

**影響範囲**：bin/nimsuggest、bin/nimgrep、bin/nimpretty、bin/testament、bin/nim_dbg、bin/nimble、bin/atlasなどの実行ファイルに影響します。

## バッチ種別

ビルド / ツールビルド

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Nimコンパイラがビルド済み | bin/nimが存在し実行可能であること |
| koch.nimがコンパイル済み | kochコマンドが実行可能であること |
| checksumsがインストール済み | nimsuggestビルドに必要 |
| ネットワーク接続（nimble/atlas用） | 外部リポジトリからのクローンに必要 |

### 実行可否判定

Nimコンパイラが存在しない場合、ビルドは失敗します。ネットワーク接続がない場合、nimbleとatlasのビルドは失敗しますが、`toolsNoExternal`コマンドで外部依存なしでビルド可能です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| 追加オプション | 文字列 | No | なし | Nimコンパイラに渡す追加オプション |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| nimsuggest/nimsuggest.nim | Nimソースファイル | nimsuggestのソース |
| tools/nimgrep.nim | Nimソースファイル | nimgrepのソース |
| nimpretty/nimpretty.nim | Nimソースファイル | nimprettyのソース |
| testament/testament.nim | Nimソースファイル | testamentのソース |
| compiler/nim.nim | Nimソースファイル | nim_dbgのソース（デバッグビルド） |
| dist/nimble/ | ディレクトリ | nimbleのクローン先 |
| dist/atlas/ | ディレクトリ | atlasのクローン先 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| bin/nimsuggest | 実行ファイル | コード補完・解析ツール |
| bin/nimgrep | 実行ファイル | Nim対応検索ツール |
| bin/nimpretty | 実行ファイル | コードフォーマッター |
| bin/testament | 実行ファイル | テストランナー |
| bin/nim_dbg | 実行ファイル | デバッグ用コンパイラ |
| bin/nimble | 実行ファイル | パッケージマネージャー |
| bin/atlas | 実行ファイル | プロジェクト管理ツール |
| bin/vccexe | 実行ファイル | VCCラッパー（Windowsのみ） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各ツール名（拡張子は環境依存） |
| 出力先 | bin/ |
| 文字コード | バイナリ |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. buildTools関数の実行
   └─ 内部ツールのビルド開始
2. nimsuggestビルド
   └─ bundleChecksums(false)でchecksumsを準備
   └─ nimsuggest/nimsuggest.nimを-d:dangerでコンパイル
3. nimgrepビルド
   └─ tools/nimgrep.nimを-d:releaseでコンパイル
4. vccexeビルド（Windowsのみ）
   └─ tools/vccexe/vccexe.nimをコンパイル
5. nimprettyビルド
   └─ nimpretty/nimpretty.nimを-d:releaseでコンパイル
6. testamentビルド
   └─ testament/testament.nimを-d:releaseでコンパイル
7. nim_dbgビルド
   └─ compiler/nim.nimを--opt:speed --stacktrace -d:debugでコンパイル
   └─ 出力名をnim_dbgに設定
8. nimbleビルド（外部依存）
   └─ bundleNimbleExe(latest, args)でGitHubからクローンしてビルド
9. atlasビルド（外部依存）
   └─ bundleAtlasExe(latest, args)でGitHubからクローンしてビルド
```

### フローチャート

```mermaid
flowchart TD
    A[tools開始] --> B[buildTools関数呼び出し]
    B --> C[bundleNimsuggest]
    C --> D[nimgrep コンパイル]
    D --> E{Windows?}
    E -->|Yes| F[vccexe コンパイル]
    E -->|No| G[nimpretty コンパイル]
    F --> G
    G --> H[testament コンパイル]
    H --> I[nim_dbg コンパイル]
    I --> J[bundleNimbleExe]
    J --> K[bundleAtlasExe]
    K --> L[tools完了]
```

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

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| コンパイルエラー | ソースエラー | 各ツールのコンパイル失敗 | ソースコードを確認 |
| ネットワークエラー | 接続失敗 | nimble/atlasのクローン失敗 | ネットワーク接続を確認、またはtoolsNoExternalを使用 |
| 依存エラー | checksums不足 | checksumsがない | bundleChecksumsを実行 |

### リトライ仕様

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

### 障害時対応

1. コンパイルエラーの場合：エラーメッセージを確認し、依存関係やソースコードを確認
2. ネットワークエラーの場合：`koch toolsNoExternal`を使用して外部依存なしでビルド
3. checksumsエラーの場合：`koch checksums`を先に実行

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

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

## パフォーマンス要件

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

## 排他制御

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各ツールコンパイル時 | "Compile <ツール名>" |
| コマンドログ | コマンド実行時 | 実行されるコンパイルコマンド |
| エラーログ | エラー発生時 | コンパイルエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド結果 | 非ゼロ終了コード | CI/CDシステム |

## 備考

- `koch tools`は`buildTools`に加えて`bundleNimbleExe`と`bundleAtlasExe`を実行します
- `koch toolsNoExternal`または`koch toolsNoNimble`は外部依存なしで内部ツールのみビルドします
- nimsuggestは-d:dangerオプションでビルドされ、最大のパフォーマンスを発揮します
- nim_dbgはデバッグ情報付きでビルドされ、コンパイラ自体のデバッグに使用できます
- nim_dbgは--opt:speedオプションも付与されており、デバッグ可能でありながら実用的な速度を維持します
- nimbleとatlasは特定のコミット（NimbleStableCommit、AtlasStableCommit）でビルドされます
- `--latest`オプションを使用すると、最新版（HEAD）でビルドされます
