# 画面設計書 42-koch --help

## 概要

本ドキュメントは、Nimビルドツール「koch」の`koch --help`コマンドによるヘルプ表示画面の設計書である。

### 本画面の処理概要

この画面は、kochビルドツールの使用方法を表示するCLIヘルプ画面である。kochはNimコンパイラ自体のビルドやメンテナンスを行うためのツールであり、開発者がビルド手順やオプションを確認するために使用する。

**業務上の目的・背景**：kochはNimプロジェクトの中核的なビルドツールであり、コンパイラのブートストラップ、ツール群のビルド、ドキュメント生成、テスト実行、配布パッケージの作成など、多岐にわたる機能を持つ。開発者やコントリビュータがこれらの機能を正しく使用するためには、包括的なヘルプ情報が必要である。

**画面へのアクセス方法**：
- `koch --help` または `koch -h` コマンドを実行
- 不明なコマンドを指定した場合もヘルプが表示される

**主要な操作・処理内容**：
1. コマンドライン引数の解析（`--help` または `-h` の検出）
2. HelpText定数からヘルプメッセージを取得
3. バージョン情報、ビルド日時の挿入
4. 標準出力へのヘルプメッセージの表示
5. 成功終了コード（QuitSuccess）でのプログラム終了

**画面遷移**：
- この画面へ遷移：コマンドラインから直接アクセス
- この画面から遷移：なし（ヘルプ表示後にプログラム終了）

**権限による表示制御**：なし（すべてのユーザーが同一のヘルプを閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | Koch | 主機能 | kochコマンドのヘルプ表示処理 |

## 画面種別

ヘルプ表示（情報出力）

## URL/ルーティング

```
koch --help
koch -h
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| --help | フラグ | - | ヘルプ表示を要求するオプション |
| -h | フラグ | - | ヘルプ表示を要求するオプション（短縮形） |

### 出力項目

| 項目名 | 説明 |
|--------|------|
| タイトルバナー | Maintenance program for Nimのタイトル |
| バージョン情報 | kochのバージョン番号 |
| ビルド日時 | コンパイル日時 |
| Usage | 基本的な使用法パターン |
| Options | 利用可能なオプション一覧 |
| Possible Commands | 利用可能なコマンド一覧 |
| Boot options | ブートストラップ用オプション一覧 |
| Commands for core developers | コア開発者向けコマンド一覧 |

## 表示項目

### ヘルプメッセージ構成

```
+-----------------------------------------------------------------+
|         Maintenance program for Nim                             |
|             Version X.X.X                                       |
|             (c) 2024 Andreas Rumpf                              |
+-----------------------------------------------------------------+
Build time: YYYY-MM-DD, HH:MM:SS

Usage:
  koch [options] command [options for command]
Options:
  --help, -h               shows this help and quits
  --latest                 bundle the installers with bleeding edge versions of
                           external components.
  --stable                 bundle the installers with stable versions of
                           external components (default).
  --nim:path               use specified path for nim binary
  --localdocs[:path]       only build local documentations. If a path is not
                           specified (or empty), the default is used.
  --skipIntegrityCheck     skips integrity check when booting the compiler
Possible Commands:
  boot [options]           bootstraps with given command line options
  distrohelper [bindir]    helper for distro packagers
  tools                    builds Nim related tools
  toolsNoExternal          builds Nim related tools (except external tools,
                           e.g. nimble)
                           doesn't require network connectivity
  nimble                   builds the Nimble tool
  atlas                    builds the Atlas tool
  checksums                installs the checksums dependency
  fusion                   installs fusion via Nimble

Boot options:
  -d:release               produce a release version of the compiler
  -d:nimUseLinenoise       use the linenoise library for interactive mode
  -d:leanCompiler          produce a compiler without JS codegen or
                           documentation generator
  -d:nimHasLibFFI          adds FFI support for VM

Commands for core developers:
  runCI                    runs continuous integration (CI)
  docs [options]           generates the full documentation
  csource -d:danger        builds the C sources for installation
  pdf                      builds the PDF documentation
  zip                      builds the installation zip package
  xz                       builds the installation tar.xz package
  testinstall              test tar.xz package; Unix only!
  installdeps [options]    installs external dependency
  tests [options]          run the testsuite
  temp options             creates a temporary compiler for testing
```

## イベント仕様

### 1-ヘルプオプション検出

**トリガー**: コマンドライン引数に`--help`または`-h`が指定された場合

**処理フロー**:
1. `initOptParser`でコマンドライン引数を解析
2. オプションのnormalizeで"help"または"h"を検出
3. `showHelp(success = true)`関数を呼び出し
4. HelpText定数をフォーマットして出力
5. `QuitSuccess`で正常終了

### 2-不明コマンド実行

**トリガー**: 認識できないコマンドが指定された場合

**処理フロー**:
1. コマンド引数のnormalizeでマッチするコマンドを検索
2. マッチしない場合、`showHelp(success = false)`を呼び出し
3. ヘルプメッセージを表示
4. `QuitFailure`で異常終了

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

該当なし（データベース操作を行わない画面）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| - | 情報 | HelpText全文 | --helpまたは-hオプション指定時 |
| - | エラー | HelpText全文 | 不明なコマンド指定時（終了コードが異なる） |

## 例外処理

| 例外条件 | 処理内容 |
|----------|---------|
| 不明なコマンド | ヘルプを表示し、QuitFailure（1）で終了 |

## 備考

- kochはNimプロジェクトのメンテナンスツールであり、一般的なNimアプリケーション開発では直接使用しない
- ヘルプメッセージはソースコード内のHelpText定数として定義されている
- バージョン番号はsystem.NimVersionを使用（VersionAsString）

---

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

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

### 推奨読解順序

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

まず、kochの定数とグローバル変数を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | HelpText定数、VersionAsString、各種コミットハッシュ定数 |

**読解のコツ**: kochはコンパイラのビルドツールであるため、外部依存のバージョン管理用の定数（NimbleStableCommit等）も多数定義されている。

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

処理の起点となる部分を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | isMainModule内のmain処理（行720以降） |

**主要処理フロー**:
1. **行720-721**: `isMainModule`ブロック開始、`initOptParser()`の呼び出し
2. **行730-732**: "--help", "-h"オプションの処理で`showHelp(success = true)`を呼び出し
3. **行788-791**: cmdEnd（引数なし）の場合、`showHelp(success = false)`を呼び出し

#### Step 3: ヘルプ表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | showHelp関数とHelpText定数 |

**主要処理フロー**:
- **行56-111**: HelpText定数 - ヘルプメッセージ全文の定義
- **行709-711**: `showHelp`関数 - HelpTextをフォーマットして出力、終了処理

#### Step 4: コマンド処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | koch.nim | `koch.nim` | cmdArgumentケースの各コマンド処理 |

**主要処理フロー**:
- **行743-788**: 各コマンド（boot, clean, docs等）の分岐処理

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

```
koch (エントリーポイント)
    │
    ├─ isMainModule (koch.nim:720)
    │      │
    │      ├─ initOptParser()
    │      │
    │      ├─ cmdLongOption/cmdShortOption の処理
    │      │      └─ "help", "h" の場合
    │      │              └─ showHelp(success = true) (koch.nim:709)
    │      │                      ├─ HelpText % [VersionAsString, CompileDate, CompileTime]
    │      │                      └─ quit(QuitSuccess)
    │      │
    │      └─ cmdEnd（引数なし）の場合
    │              └─ showHelp(success = false)
    │                      └─ quit(QuitFailure)
```

### データフロー図

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

コマンドライン引数 ───▶ initOptParser ───────────▶ OptParser
        │
        ▼
    引数解析 ───────────▶ op.kind による分岐
        │
        ├─ cmdLongOption/cmdShortOption
        │      │
        │      └─ normalize(op.key) == "help" or "h"
        │              │
        │              ▼
        │         showHelp(success=true) ─────────▶ stdout
        │              │
        │              ▼
        │         quit(QuitSuccess) ──────────────▶ 終了コード 0
        │
        └─ cmdEnd（引数なし）
               │
               ▼
          showHelp(success=false) ────────────────▶ stdout
               │
               ▼
          quit(QuitFailure) ──────────────────────▶ 終了コード 1
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | kochビルドツールのメインソース |
| tools/kochdocs.nim | `tools/kochdocs.nim` | ソース | ドキュメント生成関連のヘルパー |
| tools/deps.nim | `tools/deps.nim` | ソース | 依存関係管理のヘルパー |
