# 機能設計書 25-Cソースダンパ

## 概要

本ドキュメントは、mrubyにおけるCソースダンパ機能の設計を記述する。irepをCソースコード形式のC構造体にダンプして出力する。組み込み用途で使用される。

### 本機能の処理概要

CソースダンパはコンパイルされたirepをC言語の構造体初期化子として出力する機能である。バイナリ形式（cfunc形式）と異なり、irep構造体を直接C言語のstatic const構造体として出力するため、リンク時に直接参照でき、ロード処理が不要になる。

**業務上の目的・背景**：組み込みシステムにおいて、mrubyスクリプトをROMに直接配置し、バイナリローダによるデシリアライズを省略して高速な起動を実現する。プリシンボル（MRB_SYM）を活用し、シンボル解決も静的に行う。

**機能の利用シーン**：mrbcコマンドの`--remove-lv`オプション等と組み合わせた組み込みバイナリ生成、ビルドシステムでの自動コード生成。

**主要な処理内容**：
1. irep構造体のC言語表現の生成
2. プール（リテラル）のC構造体表現
3. シンボルのMRB_SYM/MRB_OPSYM等マクロ表現
4. 命令列（iseq）のバイト配列表現
5. デバッグ情報のC構造体表現
6. 初期化関数（init_syms）の生成

**関連システム・外部連携**：コンパイラから生成されたirepを入力として受け取る。生成されたCソースはmrubyヘッダファイルに依存する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はC APIおよびCLIツール経由で使用される |

## 機能種別

データ連携（irepのCソースコードへのシリアライズ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mrb | mrb_state* | Yes | mrubyインタプリタ状態 | - |
| irep | const mrb_irep* | Yes | ダンプ対象のirep | - |
| flags | uint8_t | Yes | ダンプフラグ | MRB_DUMP_DEBUG_INFO, MRB_DUMP_STATIC |
| fp | FILE* | Yes | 出力先ファイル | NULLでないこと |
| initname | const char* | Yes | 生成する変数名のベース | 空文字列でないこと |

### 入力データソース

- コンパイラから生成されたmrb_irep構造体

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Cソースコード | テキスト | irep構造体のC言語表現 |
| result | int | 処理結果コード |

### 出力先

FILE*経由でファイルに出力

## 処理フロー

### 処理シーケンス

```
1. ヘッダ出力
   └─ #include文（mruby.h, irep.h, debug.h, proc.h, presym.h）
   └─ マクロ定義（mrb_BRACED, mrb_DEFINE_SYMS_VAR）
2. irep構造体再帰出力（cdump_irep_struct）
   ├─ 子irep再帰出力
   ├─ reps配列出力
   ├─ pool配列出力（cdump_pool）
   ├─ syms配列出力（cdump_syms）
   ├─ iseqバイト配列出力
   ├─ lv配列出力
   ├─ debug情報出力（cdump_debug）
   └─ irep構造体本体出力
3. RProc構造体出力
4. init_syms関数出力
```

### フローチャート

```mermaid
flowchart TD
    A[mrb_dump_irep_cstruct] --> B[ヘッダ・マクロ出力]
    B --> C[cdump_irep_struct 再帰]
    C --> D[子irep処理]
    D --> E[pool配列出力]
    E --> F[syms配列出力]
    F --> G[iseq配列出力]
    G --> H[lv配列出力]
    H --> I{DEBUG_INFO?}
    I -->|Yes| J[debug情報出力]
    I -->|No| K[irep構造体出力]
    J --> K
    K --> L[RProc構造体出力]
    L --> M[init_syms関数出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | シンボルマクロ変換 | 通常のシンボルはMRB_SYM、演算子はMRB_OPSYM等に変換 | cdump_sym |
| BR-02 | 非標準シンボル | プリシンボルに変換できないシンボルはinit_syms関数で動的にインターン | cdump_sym |
| BR-03 | デバッグ情報制限 | 1ファイル1irepのシンプルなケースのみサポート | simple_debug_info |

### 計算ロジック

- 演算子シンボルの名前変換はoperator_table（二分探索）で行う

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| MRB_DUMP_INVALID_ARGUMENT | 引数不正 | fp/initnameがNULL/空 | 有効な引数を指定 |
| MRB_DUMP_WRITE_FAULT | 書き込み失敗 | fprintf失敗 | ディスク空き容量確認 |
| MRB_DUMP_INVALID_IREP | irep不正 | 複雑なデバッグ情報 | デバッグ情報フラグを外す |

### リトライ仕様

リトライは不要。

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

特になし。

## パフォーマンス要件

特になし（ビルド時に使用する機能）。

## セキュリティ考慮事項

- 生成されたCソースにはバイトコードが含まれるため、ソースコード管理に注意

## 備考

- MRB_NO_STDIO定義時は本機能全体が無効化される
- cdump_debugはsimple_debug_info（1ファイル1irep）のみサポート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cdump.c | `src/cdump.c` | operator_table（122-153行目）: 演算子シンボルの名前マッピングテーブル |

**読解のコツ**: operator_tableはシンボル名の長さでソートされており、二分探索で高速にルックアップできる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cdump.c | `src/cdump.c` | mrb_dump_irep_cstruct（449-497行目）: メインのエントリーポイント |

**主要処理フロー**:
1. **455-462行目**: ヘッダ出力（#include文）
2. **467-476行目**: マクロ定義出力
3. **480行目**: cdump_irep_struct呼び出し
4. **482-497行目**: RProc構造体とinit_syms関数出力

#### Step 3: シンボル変換ロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cdump.c | `src/cdump.c` | cdump_sym（190-237行目）: シンボルのMRB_SYMマクロ変換 |
| 3-2 | cdump.c | `src/cdump.c` | sym_operator_name（155-175行目）: 演算子シンボル名解決 |

#### Step 4: プール・命令列出力

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cdump.c | `src/cdump.c` | cdump_pool（28-73行目）: リテラルプールのC表現出力 |
| 4-2 | cdump.c | `src/cdump.c` | cdump_irep_struct（336-427行目）: irep構造体全体の出力 |

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

```
mrb_dump_irep_cstruct (公開API)
    │
    └─ cdump_irep_struct (再帰)
           ├─ cdump_pool (プール出力)
           ├─ cdump_syms (シンボル出力)
           │     └─ cdump_sym
           │           ├─ sym_name_word_p (通常シンボル判定)
           │           ├─ sym_name_with_equal_p
           │           ├─ sym_name_with_question_mark_p
           │           ├─ sym_name_with_bang_p
           │           ├─ sym_name_ivar_p
           │           ├─ sym_name_cvar_p
           │           └─ sym_operator_name (演算子判定)
           ├─ cdump_debug (デバッグ情報出力)
           │     └─ simple_debug_info (対応可否判定)
           └─ iseq/lv直接出力
```

### データフロー図

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

mrb_irep*           ───▶ cdump_irep_struct     ───▶ Cソースコード（FILE*）
                           │
mrb_sym[]           ───▶ cdump_sym             ───▶ MRB_SYM(...)テキスト
                           │
mrb_irep_pool[]     ───▶ cdump_pool            ───▶ {IREP_TT_..., ...}テキスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cdump.c | `src/cdump.c` | ソース | Cソースダンパの実装本体 |
| dump.h | `include/mruby/dump.h` | ヘッダ | ダンプフラグ定義 |
| irep.h | `include/mruby/irep.h` | ヘッダ | irep構造体定義 |
| presym.h | `include/mruby/presym.h` | ヘッダ | プリシンボルマクロ定義 |
| dump.c | `src/dump.c` | ソース | バイナリダンパ（cfunc形式との比較用） |
