# 画面設計書 6-nim r（コンパイル＆実行）

## 概要

本ドキュメントは、Nimソースコードをコンパイルして即座に実行するサブコマンド`nim r`のCLIインターフェース設計書です。

### 本画面の処理概要

`nim r`コマンドは、Nimソースコードのコンパイルと実行を一度のコマンドで行うサブコマンドです。開発中の動作確認やスクリプト的なNim利用に便利で、`nim c -r`のショートカットとして機能します。コンパイル結果はnimcacheディレクトリに保存され、再実行時には増分ビルドの恩恵を受けることができます。

**業務上の目的・背景**：開発サイクルを高速化するため、コンパイルと実行を一つのコマンドで完結させます。従来の`nim c hello.nim && ./hello`という2ステップを`nim r hello.nim`の1ステップに短縮できます。また、nimcacheに出力することでプロジェクトディレクトリを汚さずに実行できます。

**画面へのアクセス方法**：ターミナルから`nim r <filename.nim>`を実行します。

**主要な操作・処理内容**：
1. コンパイルの実行（`nim c`と同等）
2. 生成されたバイナリの自動実行
3. コマンドライン引数の実行バイナリへの転送
4. 実行結果の標準出力/標準エラーへの出力

**画面遷移**：
- 入力元：`nim`メインコマンドから`cmdCrun`として呼び出し
- 遷移先：コンパイル後、生成されたバイナリが実行される

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Nimコンパイラ本体 | 主機能 | コンパイル処理を実行 |
| 5 | Cコード生成 | 補助機能 | Cコード生成後に即座に実行 |
| 11 | 外部Cコンパイラ連携 | 補助機能 | 外部コンパイラでバイナリを生成し実行 |

## 画面種別

CLIサブコマンド（コンパイル＆実行）

## URL/ルーティング

```
nim r [options] <projectfile.nim> [-- arguments]
```

オプション例：
- `nim r hello.nim` - コンパイルして実行
- `nim r -d:release hello.nim` - リリースビルドで実行
- `nim r hello.nim -- arg1 arg2` - 引数付きで実行
- `nim r --backend:js hello.nim` - JSバックエンドで実行

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| projectfile | string | 入力 | はい | コンパイル・実行対象のNimソースファイル |
| -- arguments | string[] | 入力 | いいえ | 実行バイナリに渡す引数 |
| -d:NAME | string | 入力 | いいえ | 条件コンパイルシンボル定義 |
| --backend:TYPE | enum | 入力 | いいえ | バックエンド指定（c/cpp/js） |
| 標準出力 | text | 出力 | - | 実行結果 |
| 標準エラー | text | 出力 | - | エラー出力 |
| 終了コード | int | 出力 | - | 実行バイナリの終了コード |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| コンパイル進捗 | コンパイル中のメッセージ | デフォルト |
| 実行出力 | 実行バイナリの出力 | 実行時 |

## イベント仕様

### 1-コマンド処理開始

`main.nim`で`cmdCrun`として処理されます：

1. **main.nim 行306**: `conf.globalOptions.incl {optRun, optUseNimcache}`
2. `compileToBackend()`でコンパイル実行
3. コンパイル成功後に自動実行

### 2-コンパイル処理

通常の`nim c`と同様のコンパイルフローを実行：
- `commandCompileToC(graph)`でCコード生成
- `callCCompiler(conf)`で外部コンパイラ呼び出し
- バイナリをnimcacheディレクトリに生成

### 3-実行処理

`nim.nim`の`handleCmdLine`で実行処理：
- **行131-158**: `optRun in conf.globalOptions`の場合
- **行132**: `conf.absOutFile`で出力パス取得
- **行134-150**: バックエンドに応じた実行方法選択
- **行149-150**: `execExternalProgram`で実行

### 4-バックエンド別実行

- **C/C++/ObjC**: 生成バイナリを直接実行
- **JavaScript**: Node.jsを使用して実行
- **mingwモード**: wineを使用して実行（クロスコンパイル時）

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

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

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

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| コンパイル | *.nim | READ | Nimソースファイル読み込み |
| コンパイル | nimcache/* | WRITE | 中間ファイルと実行ファイル出力 |
| 実行 | 実行ファイル | EXEC | コンパイル結果の実行 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| ヒント | コンパイル成功メッセージ | コンパイル成功時 |
| エラー | コンパイルエラー | コンパイル失敗時 |
| エラー | 実行時エラー | 実行失敗時 |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| ソースファイル不在 | "cannot open file: $1" | エラー終了 |
| コンパイルエラー | コンパイラエラーメッセージ | エラー終了 |
| 実行失敗 | 実行時エラーメッセージ | プログラム終了コードを返す |

## 備考

- `nimcache`ディレクトリに出力するため、プロジェクトディレクトリは汚れない
- 増分ビルドにより、変更がない場合は再コンパイルをスキップ
- `--backend:js`でJavaScriptモードでも実行可能
- mingw定義時はwine/wine64で実行（クロスコンパイル）
- 終了コードは実行バイナリの終了コードがそのまま返される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.nim | `compiler/options.nim` | optRun、optUseNimcache（TGlobalOption） |
| 1-2 | options.nim | `compiler/options.nim` | cmdCrun（Command列挙型行155） |

**読解のコツ**: `optRun`フラグがコンパイル後実行を制御、`optUseNimcache`がnimcacheへの出力を制御。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.nim | `compiler/main.nim` | cmdCrunの前処理（行306） |
| 2-2 | commands.nim | `compiler/commands.nim` | parseCommand "r" -> cmdCrun（行479） |

**主要処理フロー**:
1. **main.nim 行306**: `cmdCrun`の場合、`optRun`と`optUseNimcache`を設定
2. **main.nim 行307**: `customizeForBackend(backendC)`がデフォルトでない場合のみ設定
3. **main.nim 行321-322**: `cmdBackends`ケースで`compileToBackend()`呼び出し

#### Step 3: 実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nim.nim | `compiler/nim.nim` | optRun処理（行131-158） |
| 3-2 | nim.nim | `compiler/nim.nim` | getNimRunExe関数（行88-96） |

**主要処理フロー**:
- **行131**: `optRun in conf.globalOptions`の判定
- **行132**: `conf.absOutFile`で出力パス取得
- **行134-150**: バックエンドごとの実行処理分岐
- **行143-144**: JSバックエンドの場合、Node.jsを使用

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

```
nim.nim::handleCmdLine()
    │
    ├─ mainCommand()
    │      │
    │      └─ case cmdCrun
    │             │
    │             ├─ conf.globalOptions.incl {optRun, optUseNimcache}
    │             │
    │             └─ compileToBackend()
    │                    │
    │                    └─ commandCompileToC()
    │                           │
    │                           ├─ compilePipelineProject()
    │                           │
    │                           └─ callCCompiler()
    │
    └─ if optRun in conf.globalOptions
           │
           ├─ getNimRunExe()  # mingw時のwine設定
           │
           └─ execExternalProgram()
                  │
                  └─ 生成バイナリ実行
```

### データフロー図

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

*.nim ───▶ コンパイル処理 ───▶ nimcache/実行ファイル
                 │
コマンドライン引数 ───▶ conf.arguments に格納
                 │
                 ▼
実行ファイル + 引数 ───▶ execExternalProgram() ───▶ 標準出力/エラー
                 │
                 ▼
             終了コード ───▶ msgQuit()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nim.nim | `compiler/nim.nim` | ソース | optRun処理、実行呼び出し |
| main.nim | `compiler/main.nim` | ソース | cmdCrun前処理、optRun/optUseNimcache設定 |
| commands.nim | `compiler/commands.nim` | ソース | parseCommand "r" -> cmdCrun |
| options.nim | `compiler/options.nim` | ソース | optRun、cmdCrun定義 |
| extccomp.nim | `compiler/extccomp.nim` | ソース | 外部プログラム実行 |
