# 画面設計書 2-nim c（Cコード生成）

## 概要

本ドキュメントは、NimソースコードをC言語にコンパイルするサブコマンド`nim c`のCLIインターフェース設計書です。

### 本画面の処理概要

`nim c`コマンドは、Nim言語で書かれたソースコードをC言語の中間コードに変換し、外部Cコンパイラ（GCC、Clang、MSVC等）を呼び出して最終的な実行ファイルを生成するサブコマンドです。Nimの最も基本的かつ一般的なコンパイル方法であり、クロスプラットフォーム対応のバイナリ生成に使用されます。

**業務上の目的・背景**：Nimプログラムを実行可能なネイティブバイナリに変換するための主要なコンパイルパスです。C言語を中間言語として使用することで、広範なプラットフォームサポートと既存のCツールチェーンの活用が可能になります。これにより、Nim開発者は高水準言語の恩恵を受けながら、C言語レベルの性能と互換性を得ることができます。

**画面へのアクセス方法**：ターミナルから`nim c <filename.nim>`または`nim compile <filename.nim>`を実行します。`nim cc`も同義です。

**主要な操作・処理内容**：
1. Nimソースファイルの字句解析・構文解析
2. 意味解析（型チェック、名前解決、マクロ展開）
3. 中間表現からCコードへの変換（cgen.nim）
4. 生成されたCコードをnimcacheディレクトリに出力
5. 外部Cコンパイラの呼び出し（extccomp.nim）
6. リンカによる実行ファイル生成
7. ビルド指示ファイル（.json）の出力

**画面遷移**：
- 入力元：`nim`メインコマンドから`cmdCompileToC`として呼び出し
- 遷移先：なし（コンパイル完了後終了）、`--run`オプション時は生成バイナリを実行

**権限による表示制御**：OSのファイルシステム権限に依存。nimcacheディレクトリおよび出力先への書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | Cコード生成 | 主機能 | NimコードからCソースコードを生成するバックエンド処理 |
| 11 | 外部Cコンパイラ連携 | 補助機能 | GCC/Clang/MSVCとの連携によるバイナリ生成 |
| 19 | デストラクタ注入 | 補助機能 | ARCメモリ管理のためのデストラクタ自動注入処理 |

## 画面種別

CLIサブコマンド（コンパイラバックエンド）

## URL/ルーティング

```
nim c [options] <projectfile.nim>
nim compile [options] <projectfile.nim>
nim cc [options] <projectfile.nim>
```

オプション例：
- `nim c hello.nim` - デフォルト設定でコンパイル
- `nim c -d:release hello.nim` - リリースビルド
- `nim c --opt:speed hello.nim` - 速度最適化
- `nim c -r hello.nim` - コンパイル後に実行
- `nim c --cc:clang hello.nim` - Clangコンパイラ使用
- `nim c -o:myapp hello.nim` - 出力ファイル名指定

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| projectfile | string | 入力 | はい | コンパイル対象のNimソースファイル |
| -d:NAME | string | 入力 | いいえ | 条件コンパイルシンボル定義 |
| --opt:LEVEL | enum | 入力 | いいえ | 最適化レベル（none/speed/size） |
| --cc:COMPILER | enum | 入力 | いいえ | 使用するCコンパイラ |
| -o:FILE | string | 入力 | いいえ | 出力ファイルパス |
| --nimcache:DIR | string | 入力 | いいえ | 中間ファイル出力ディレクトリ |
| --mm:MODE | enum | 入力 | いいえ | メモリ管理方式（arc/orc/refc等） |
| *.c | file | 出力 | - | 生成されたCソースファイル |
| executable | file | 出力 | - | 最終実行ファイル |
| *.json | file | 出力 | - | ビルド指示ファイル |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| CC: filename | コンパイル中のCファイル | --listCmd有効時 |
| Hint: [Link] | リンク処理開始 | デフォルト |
| Hint: [Success] | コンパイル成功と出力パス | デフォルト |
| コンパイラ出力 | Cコンパイラの警告・エラー | Cコンパイラ実行時 |
| 進捗表示 | 処理中のモジュール名 | --verbosity:1以上 |

## イベント仕様

### 1-コンパイル開始

`main.nim`の`commandCompileToC`関数が呼び出されます：

1. `extccomp.initVars(conf)` - 外部コンパイラ変数初期化
2. 増分ビルド判定（`changeDetectedViaJsonBuildInstructions`）
3. `setPipeLinePass(graph, CgenPass)` - コード生成パス設定
4. `compilePipelineProject(graph)` - プロジェクト全体のコンパイル

### 2-Cコード生成

`cgen.nim`モジュールでCコード生成が行われます：

1. `genProc` - プロシージャのC関数への変換
2. `genStmt` - 文のCステートメントへの変換
3. `genExpr` - 式のC式への変換
4. 型情報の生成（`ccgtypes.nim`）
5. リテラル処理（`ccgliterals.nim`）

### 3-外部コンパイラ呼び出し

`extccomp.nim`の`callCCompiler`関数で：

1. Cコンパイラコマンドライン構築
2. 並列コンパイル実行（複数.cファイル）
3. リンカ呼び出し
4. 最終バイナリ生成

### 4-ビルド指示出力

`extccomp.nim`の`writeJsonBuildInstructions`で：

1. コンパイル対象ファイルリスト
2. コンパイラオプション
3. リンカオプション
をJSONファイルに出力

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

本CLIツールはデータベースを使用しません。ファイルシステム操作のみ行います。

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

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| コンパイル | *.nim | READ | Nimソースファイル読み込み |
| コンパイル | nimcache/*.c | WRITE | 生成Cソースファイル出力 |
| コンパイル | nimcache/*.h | WRITE | 生成ヘッダファイル出力 |
| コンパイル | nimcache/*.o | WRITE | オブジェクトファイル生成 |
| リンク | 実行ファイル | WRITE | 最終バイナリ出力 |
| ビルド情報 | *.json | WRITE | ビルド指示ファイル出力 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| ヒント | "Hint: [Link]" | リンク処理開始時 |
| ヒント | "Hint: [Success] ..." | コンパイル成功時 |
| エラー | "Error: cannot open file: $1" | ソースファイル不在時 |
| エラー | "Error: undeclared identifier: '$1'" | 未定義シンボル参照時 |
| エラー | "Error: type mismatch: ..." | 型エラー時 |
| 警告 | Cコンパイラからの警告 | Cコンパイル時 |
| エラー | "execution of external compiler failed" | Cコンパイラ失敗時 |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| ソースファイル不在 | "cannot open file: $1" | エラー終了 |
| 構文エラー | 行番号・列番号付きエラー | エラー終了 |
| 型エラー | 詳細な型ミスマッチ情報 | エラー終了 |
| Cコンパイラ不在 | "execution of external program failed" | エラー終了 |
| リンクエラー | リンカからのエラーメッセージ | エラー終了 |
| ディスク容量不足 | OSからのエラー | エラー終了 |

## 備考

- デフォルトのメモリ管理方式はORC（サイクル検出付き自動参照カウント）
- `--mm:arc`でシンプルなARC、`--mm:refc`で従来の参照カウントGC
- `-d:release`で最適化有効、デバッグ情報削除
- `-d:danger`でさらに境界チェック等も削除（最高速）
- `--passC:`でCコンパイラに追加オプション渡し可能
- `--passL:`でリンカに追加オプション渡し可能

---

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

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

### 推奨読解順序

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

Cコード生成で使用される主要なデータ構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cgendata.nim | `compiler/cgendata.nim` | BModule、BProc、TLoc型の定義 |
| 1-2 | ropes.nim | `compiler/ropes.nim` | Rope型（効率的な文字列連結） |
| 1-3 | ast.nim | `compiler/ast.nim` | PNode、PSym、PType型（AST表現） |

**読解のコツ**: BModuleは1つのNimモジュールに対応するCファイル生成情報、BProcは1つのプロシージャのC関数生成情報、TLocは変数・式の位置情報。

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

コンパイルパイプラインの開始点を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.nim | `compiler/main.nim` | commandCompileToC関数（行146〜176） |
| 2-2 | pipelines.nim | `compiler/pipelines.nim` | CgenPass、compilePipelineProject |

**主要処理フロー**:
1. **main.nim 行147-148**: `extccomp.initVars(conf)` 外部コンパイラ初期化
2. **main.nim 行149-154**: 増分ビルド判定
3. **main.nim 行156-158**: オーバーフローチェック設定
4. **main.nim 行160-162**: CgenPassまたはSemPass設定
5. **main.nim 行163**: `compilePipelineProject(graph)`
6. **main.nim 行166-175**: Cコンパイラ呼び出しとビルド情報出力

#### Step 3: Cコード生成を理解する

cgen.nimの構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cgen.nim | `compiler/cgen.nim` | メインのCコード生成ロジック |
| 3-2 | ccgtypes.nim | `compiler/ccgtypes.nim` | 型のC表現生成 |
| 3-3 | ccgliterals.nim | `compiler/ccgliterals.nim` | リテラルのC表現生成 |

**主要処理フロー**:
- **cgen.nim 行354**: `genProc` - プロシージャ生成
- **cgen.nim 行459-500**: `genObjectInit` - オブジェクト初期化
- ropecgマクロでC言語文字列を効率的に構築

#### Step 4: 外部コンパイラ連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | extccomp.nim | `compiler/extccomp.nim` | callCCompiler、コンパイラ設定 |
| 4-2 | platform.nim | `compiler/platform.nim` | プラットフォーム情報 |

**主要処理フロー**:
- `callCCompiler`: Cコンパイラの実行
- `writeJsonBuildInstructions`: ビルド情報JSON出力

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

```
main.nim::mainCommand()
    │
    └─ case cmdCompileToC
           │
           └─ compileToBackend()
                  │
                  └─ commandCompileToC()
                         │
                         ├─ extccomp.initVars()
                         │
                         ├─ setPipeLinePass(graph, CgenPass)
                         │
                         ├─ compilePipelineProject()
                         │      │
                         │      ├─ 各モジュールをコンパイル
                         │      │      └─ cgen.myProcess()
                         │      │             ├─ genProc()
                         │      │             ├─ genStmt()
                         │      │             └─ genExpr()
                         │      │
                         │      └─ cgenWriteModules()
                         │             └─ 各*.cファイル出力
                         │
                         ├─ callCCompiler()
                         │      ├─ 各*.cをコンパイル
                         │      └─ リンク実行
                         │
                         └─ writeJsonBuildInstructions()
```

### データフロー図

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

*.nim ───▶ レキサー/パーサー ───▶ AST (PNode)
                 │
                 ▼
AST ───▶ セマンティック解析 ───▶ 型付きAST + シンボルテーブル
                 │
                 ▼
型付きAST ───▶ cgen.nim ───▶ Rope (C言語文字列)
                 │
                 ▼
Rope ───▶ ファイル出力 ───▶ nimcache/*.c, *.h
                 │
                 ▼
*.c ───▶ extccomp (gcc/clang) ───▶ *.o
                 │
                 ▼
*.o ───▶ リンカ ───▶ 実行ファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cgen.nim | `compiler/cgen.nim` | ソース | メインCコード生成ロジック |
| cgendata.nim | `compiler/cgendata.nim` | ソース | Cコード生成用データ構造定義 |
| ccgtypes.nim | `compiler/ccgtypes.nim` | ソース | 型のC表現生成 |
| ccgliterals.nim | `compiler/ccgliterals.nim` | ソース | リテラル生成 |
| ccgexprs.nim | `compiler/ccgexprs.nim` | ソース | 式のC表現生成 |
| ccgstmts.nim | `compiler/ccgstmts.nim` | ソース | 文のC表現生成 |
| ccgcalls.nim | `compiler/ccgcalls.nim` | ソース | 関数呼び出し生成 |
| extccomp.nim | `compiler/extccomp.nim` | ソース | 外部Cコンパイラ連携 |
| main.nim | `compiler/main.nim` | ソース | commandCompileToC関数 |
| ropes.nim | `compiler/ropes.nim` | ソース | 効率的文字列連結 |
| platform.nim | `compiler/platform.nim` | ソース | プラットフォーム情報 |
| nimbase.h | `lib/nimbase.h` | ヘッダ | 生成Cコード用基本ヘッダ |
