# 画面設計書 1-nimコンパイラメイン画面

## 概要

本ドキュメントは、NimコンパイラのメインエントリーポイントであるnimコマンドのCLIインターフェース設計書です。

### 本画面の処理概要

nimコンパイラメイン画面は、Nim言語で書かれたソースコードをコンパイルするためのメインCLIインターフェースです。ユーザーがターミナルから`nim`コマンドを実行すると、この画面がコマンドライン引数を受け取り、適切なサブコマンド（c, cpp, js, doc等）に処理を振り分けます。

**業務上の目的・背景**：Nimプログラミング言語のコンパイル作業を行うための統一されたエントリーポイントを提供します。開発者がNimソースコードを各種バックエンド（C、C++、JavaScript等）向けにコンパイルする際の主要なインターフェースとなります。

**画面へのアクセス方法**：ターミナル（コマンドプロンプト、シェル）から`nim`コマンドを実行することでアクセスします。引数なしで実行すると使用方法が表示されます。

**主要な操作・処理内容**：
1. コマンドライン引数の解析（parseopt.initOptParser）
2. 設定ファイル（nim.cfg, config.nims）の読み込み
3. サブコマンドの判定とディスパッチ
4. コンパイルオプションの設定と検証
5. モジュールグラフの構築とコンパイル実行
6. エラーメッセージや警告の出力
7. コンパイル結果の生成と後処理

**画面遷移**：
- 入力元：ターミナル（シェル）からの直接実行
- 遷移先：各サブコマンド（nim c, nim cpp, nim js, nim doc, nim r, nim e, nim check, nim dump等）

**権限による表示制御**：CLIツールであり、OSのファイルシステム権限に依存します。特定のディレクトリへの書き込みや実行権限が必要な場合があります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Nimコンパイラ本体 | 主機能 | コマンドライン引数を解析し、各種コンパイルコマンドを振り分けるメイン処理 |
| 2 | レキサー（字句解析） | 補助機能 | ソースコードの字句解析処理を呼び出し |
| 3 | パーサー（構文解析） | 補助機能 | 字句解析結果からASTを構築する処理を呼び出し |
| 4 | セマンティック解析 | 補助機能 | 型チェック・名前解決・マクロ展開の呼び出し |
| 10 | モジュールグラフ管理 | 補助機能 | モジュール間依存関係の管理処理 |

## 画面種別

CLIメインエントリーポイント（コマンドディスパッチャー）

## URL/ルーティング

```
nim [command] [options] [projectfile] [arguments]
```

コマンド例：
- `nim c hello.nim` - Cバックエンドでコンパイル
- `nim cpp hello.nim` - C++バックエンドでコンパイル
- `nim js hello.nim` - JavaScriptにコンパイル
- `nim r hello.nim` - コンパイルして実行
- `nim --help` - ヘルプ表示
- `nim --version` - バージョン表示

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| command | string | 入力 | いいえ | サブコマンド（c, cpp, js, doc, r, e, check, dump等） |
| options | string[] | 入力 | いいえ | コンパイラオプション（--opt:speed, -d:release等） |
| projectfile | string | 入力 | 条件付き | コンパイル対象のNimソースファイル |
| arguments | string[] | 入力 | いいえ | 実行時引数（-rオプション使用時） |
| 標準出力 | text | 出力 | - | コンパイル進捗、警告、ヒント |
| 標準エラー | text | 出力 | - | エラーメッセージ |
| 終了コード | int8 | 出力 | - | 0:成功、非0:エラー |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| コンパイル進捗 | 処理中のファイル名やフェーズ | --verbosity:1以上 |
| ヒントメッセージ | 最適化提案や情報 | --hints:on |
| 警告メッセージ | 潜在的問題の通知 | --warnings:on |
| エラーメッセージ | コンパイルエラーの詳細 | エラー発生時 |
| 成功メッセージ | コンパイル完了通知 | 正常完了時 |
| GC統計情報 | ガベージコレクション統計 | hintGCStats有効時 |

## イベント仕様

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

ユーザーがnimコマンドを実行すると、`handleCmdLine`関数が呼び出され以下の処理が行われます：

1. `NimProg`インスタンスを作成し、`processCmdLine`コールバックを設定
2. パラメータが0個の場合、使用方法を表示して終了
3. `processCmdLineAndProjectPath`でコマンドラインとプロジェクトパスを処理
4. `newModuleGraph`でモジュールグラフを生成
5. `loadConfigsAndProcessCmdLine`で設定を読み込み
6. `mainCommand`でメインコマンドを実行

### 2-サブコマンドディスパッチ

`main.nim`の`mainCommand`関数でコマンドに応じた処理に分岐：

- `cmdBackends` (c, cpp, objc, js): `compileToBackend()`
- `cmdCheck`: `commandCheck(graph)`
- `cmdDoc`: `commandDoc2(graph, HtmlExt)`
- `cmdNimscript` (e): NimScript実行
- `cmdDump`: 設定情報ダンプ
- その他多数のコマンド

### 3-実行オプション処理

`--run`または`-r`オプション指定時、コンパイル後に以下を実行：
- バックエンドに応じた実行方法を選択（C系は直接実行、JSはNode.js経由）
- ドキュメント系コマンドの場合はデフォルトブラウザで開く

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

本CLIツールはデータベースを使用しません。ファイルシステム上のソースファイルを読み込み、バイナリやその他の成果物を出力します。

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

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| nim c | *.nim, *.cfg | READ | ソースファイルと設定ファイル読み込み |
| nim c | nimcache/*.c | WRITE | 中間Cコード生成 |
| nim c | 実行ファイル | WRITE | 最終バイナリ出力 |
| nim doc | *.nim | READ | ドキュメント用ソース読み込み |
| nim doc | *.html | WRITE | HTMLドキュメント出力 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| エラー | "invalid command line option: '$1'" | 不正なオプション指定時 |
| エラー | "cannot open file: $1" | ファイルが見つからない時 |
| エラー | "'$1 cannot handle --run" | --runをサポートしないコマンド |
| 警告 | 各種型・名前解決警告 | コード分析時 |
| ヒント | "GC: ..." | GC統計表示時 |
| 成功 | "Hint: ..." + 実行ファイルパス | コンパイル成功時 |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| 引数なし | (使用方法表示) | 正常終了（コード0） |
| 不明コマンド | "invalid command: $1" | エラー終了 |
| ファイル不在 | "cannot open file: $1" | エラー終了 |
| 構文エラー | (詳細なエラー位置表示) | エラー終了 |
| 型エラー | (詳細な型ミスマッチ情報) | エラー終了 |
| 設定エラー | 設定に関するエラーメッセージ | エラー終了 |

## 備考

- Nimコンパイラは自己ホスティング（Nimで書かれている）
- 複数のバックエンド（C, C++, JavaScript, Objective-C）をサポート
- 増分コンパイル（IC）機能により再コンパイル時間を短縮可能
- nimble.lockファイルが存在する場合、Nimbleパスは自動的に無効化

---

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

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

### 推奨読解順序

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

まず、コンパイラ全体で使用される設定データ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.nim | `compiler/options.nim` | ConfigRef型の定義（行346〜）、TOption/TGlobalOption列挙型（行34〜119） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | TLineInfo型、FileIndex型の定義 |
| 1-3 | modulegraphs.nim | `compiler/modulegraphs.nim` | ModuleGraph型の定義（コンパイル全体を管理） |

**読解のコツ**: ConfigRefはコンパイラ全体の設定を保持する中心的な型。backend、cmd、options、globalOptionsフィールドに注目。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nim.nim | `compiler/nim.nim` | メインモジュール、handleCmdLine関数（行98〜） |

**主要処理フロー**:
1. **行167-169**: `newConfigRef()`で設定を初期化
2. **行169**: `handleCmdLine(newIdentCache(), conf)`を呼び出し
3. **行98-106**: `NimProg`インスタンス生成、引数チェック
4. **行108**: `processCmdLineAndProjectPath`でコマンドライン処理
5. **行110**: `newModuleGraph`でモジュールグラフ生成
6. **行111-112**: 設定読み込み
7. **行124**: `mainCommand(graph)`でメインコマンド実行

#### Step 3: コマンドライン解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | commands.nim | `compiler/commands.nim` | parseCommand関数（行472〜）でコマンド文字列をCommand列挙型に変換 |
| 3-2 | cmdlinehelper.nim | `compiler/cmdlinehelper.nim` | NimProg型とprocessCmdLineAndProjectPath |

**主要処理フロー**:
- **commands.nim 行472-500**: `parseCommand`関数でコマンド名を正規化してCommand列挙型に変換
- **nim.nim 行50-81**: `processCmdLine`でオプションとファイル名を解析

#### Step 4: メインコマンド実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | main.nim | `compiler/main.nim` | mainCommand関数（行254〜）でコマンドディスパッチ |

**主要処理フロー**:
- **行254-256**: 関数開始、設定とキャッシュ取得
- **行261-282**: `customizeForBackend`でバックエンド固有設定
- **行284-293**: `compileToBackend`でバックエンド別コンパイル
- **行320-451**: caseステートメントで各コマンド処理に分岐

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

```
nim.nim (main)
    │
    ├─ handleCmdLine()
    │      │
    │      ├─ NimProg.initDefinesProg()
    │      │
    │      ├─ NimProg.processCmdLineAndProjectPath()
    │      │      └─ processCmdLine()  [nim.nim]
    │      │             └─ processSwitch() / processArgument()
    │      │
    │      ├─ newModuleGraph()
    │      │
    │      ├─ loadConfigsAndProcessCmdLine()
    │      │
    │      └─ mainCommand()  [main.nim]
    │             │
    │             ├─ customizeForBackend()
    │             │
    │             └─ case conf.cmd
    │                    ├─ cmdBackends → compileToBackend()
    │                    │                    └─ commandCompileToC() / commandCompileToJS()
    │                    ├─ cmdCheck → commandCheck()
    │                    ├─ cmdDoc → commandDoc2()
    │                    ├─ cmdDump → (設定出力)
    │                    └─ ...
    │
    └─ msgQuit()
```

### データフロー図

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

コマンドライン引数 ───▶ parseopt.initOptParser() ───▶ 解析済みオプション
                              │
                              ▼
nim.cfg / config.nims ───▶ loadConfigs() ───▶ ConfigRef設定済み
                              │
                              ▼
*.nim ソースファイル ───▶ ModuleGraph構築 ───▶ AST/型情報
                              │
                              ▼
AST ───▶ cgen.nim/jsgen.nim ───▶ nimcache/*.c または *.js
                              │
                              ▼
*.c ───▶ 外部Cコンパイラ ───▶ 実行ファイル / ライブラリ
                              │
                              ▼
                         標準出力/標準エラー ───▶ メッセージ/エラー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nim.nim | `compiler/nim.nim` | ソース | メインエントリーポイント |
| main.nim | `compiler/main.nim` | ソース | mainCommand関数、コマンドディスパッチ |
| commands.nim | `compiler/commands.nim` | ソース | コマンドライン解析、オプション処理 |
| options.nim | `compiler/options.nim` | ソース | ConfigRef型定義、設定管理 |
| cmdlinehelper.nim | `compiler/cmdlinehelper.nim` | ソース | コマンドラインヘルパー関数 |
| modulegraphs.nim | `compiler/modulegraphs.nim` | ソース | ModuleGraph型定義 |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ出力機能 |
| extccomp.nim | `compiler/extccomp.nim` | ソース | 外部Cコンパイラ連携 |
| basicopt.txt | `doc/basicopt.txt` | テンプレート | 基本オプションヘルプテキスト |
| advopt.txt | `doc/advopt.txt` | テンプレート | 詳細オプションヘルプテキスト |
