# 機能設計書 118-tinyc

## 概要

本ドキュメントは、Nim標準ライブラリの`tinyc`ラッパーモジュールの機能設計について記載する。このモジュールはTinyCC（TCC）コンパイラライブラリへのNimバインディングを提供する。

### 本機能の処理概要

tinycモジュールは、TinyCC（TCC）コンパイラをライブラリとして利用するためのラッパーを提供する。実行時にCコードをコンパイルし、メモリ上で直接実行したり、オブジェクトファイルを生成したりできる。

**業務上の目的・背景**：動的なコード生成やJIT（Just-In-Time）コンパイルのニーズに対応するため、軽量で高速なCコンパイラをプログラム内に組み込む機能が必要となる場合がある。TCCは非常に小さなフットプリントで高速なコンパイルを提供する。

**機能の利用シーン**：
- 実行時のCコード生成と実行
- プラグインシステムの実装
- スクリプティングエンジン
- 動的なコード評価
- テストや検証のための一時的なコード実行

**主要な処理内容**：
1. `openCCState` - コンパイルコンテキストの作成
2. `compileString` - 文字列からのコンパイル
3. `addFile` - ファイルの追加
4. `run` - コンパイル済みコードの実行
5. `getSymbol` - シンボルアドレスの取得
6. `setOutputType` - 出力タイプの設定（メモリ/EXE/DLL/OBJ）

**関連システム・外部連携**：
- TinyCC（libtcc）ライブラリ
- システムCライブラリ

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プログラム内部で使用するライブラリ機能 |

## 機能種別

コンパイル / 動的コード生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| s | PccState | Yes | コンパイル状態 | nil不可 |
| buf | cstring | Yes | コンパイルするCコード | 有効なC構文 |
| filename | cstring | No | ファイルパス | - |
| pathname | cstring | No | インクルードパス | - |
| sym | cstring | No | シンボル名 | - |
| value | cstring | No | プリプロセッサ定義値 | - |

### 入力データソース

Cソースコード文字列またはファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PccState | ptr CcState | コンパイル状態ポインタ |
| cint | cint | 操作結果（0=成功、-1=失敗） |
| pointer | pointer | シンボルアドレス |

### 出力先

メモリ上の実行可能コード、またはファイル

## 処理フロー

### 処理シーケンス

```
1. openCCState()でコンパイル状態を作成
   └─ TCC: tcc_new

2. setOutputType()で出力タイプを設定
   └─ OutputMemory / OutputExe / OutputDll / OutputObj

3. オプション設定
   └─ addIncludePath() - インクルードパス追加
   └─ defineSymbol() - プリプロセッサ定義
   └─ addLibraryPath() / addLibrary() - ライブラリ設定

4. コンパイル
   └─ compileString() - 文字列からコンパイル
   └─ addFile() - ファイルを追加

5. リンクと実行
   └─ run() - メモリ上で実行
   または
   └─ outputFile() - ファイルに出力

6. シンボル操作
   └─ relocate() - メモリ再配置
   └─ getSymbol() - シンボルアドレス取得
   └─ addSymbol() - シンボル追加

7. closeCCState()でリソース解放
   └─ TCC: tcc_delete
```

### フローチャート

```mermaid
flowchart TD
    A[openCCState] --> B[setOutputType]
    B --> C[インクルード・ライブラリ設定]
    C --> D{コンパイル方法}
    D -->|文字列| E[compileString]
    D -->|ファイル| F[addFile]
    E --> G{出力タイプ}
    F --> G
    G -->|Memory| H[relocate]
    G -->|File| I[outputFile]
    H --> J[run / getSymbol]
    I --> K[終了]
    J --> L[closeCCState]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-118-01 | OutputMemory | デフォルト出力タイプ、メモリ上実行 | run()使用時 |
| BR-118-02 | OutputExe | 実行可能ファイル出力 | スタンドアロン実行時 |
| BR-118-03 | OutputDll | 動的ライブラリ出力 | プラグイン作成時 |
| BR-118-04 | OutputObj | オブジェクトファイル出力 | リンク時 |
| BR-118-05 | setOutputType先行 | コンパイル前にsetOutputType必須 | 常時 |
| BR-118-06 | relocate先行 | getSymbol前にrelocate必須 | シンボル取得時 |

### 計算ロジック

特になし

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

### 操作別データベース影響一覧

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| -1 | コンパイルエラー | 構文エラー等 | setErrorFuncでエラー情報取得 |
| -1 | リンクエラー | シンボル未定義等 | ライブラリ・シンボルを確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- TCCは非常に高速なコンパイラ
- メモリ上実行ではディスクI/Oなし
- 最適化レベルはGCC等より低い

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

- 任意コード実行のリスク
- 信頼できないコードのコンパイルは危険
- サンドボックス環境での使用を検討

## 備考

- TCCのライブラリリンクが必要
- Nimのアトミック操作にTCCサポートあり（sysatomics.nim参照）

---

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

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

### 推奨読解順序

#### Step 1: 型定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | tinyc.nim | `lib/wrappers/tinyc.nim` | CcState/PccState型（10-12行目） |
| 1-2 | tinyc.nim | `lib/wrappers/tinyc.nim` | ErrorFunc型（14行目） |

**読解のコツ**: CcStateは不透明型（pure, final）。PccStateはそのポインタ型。

#### Step 2: コンテキスト管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tinyc.nim | `lib/wrappers/tinyc.nim` | openCCState（16-17行目） |
| 2-2 | tinyc.nim | `lib/wrappers/tinyc.nim` | closeCCState（19-20行目） |
| 2-3 | tinyc.nim | `lib/wrappers/tinyc.nim` | setErrorFunc（22-24行目） |
| 2-4 | tinyc.nim | `lib/wrappers/tinyc.nim` | setOptions（26-27行目） |

#### Step 3: プリプロセッサ設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tinyc.nim | `lib/wrappers/tinyc.nim` | addIncludePath（31-33行目） |
| 3-2 | tinyc.nim | `lib/wrappers/tinyc.nim` | addSysincludePath（35-37行目） |
| 3-3 | tinyc.nim | `lib/wrappers/tinyc.nim` | defineSymbol（39-41行目） |
| 3-4 | tinyc.nim | `lib/wrappers/tinyc.nim` | undefineSymbol（43-45行目） |

#### Step 4: コンパイル関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | tinyc.nim | `lib/wrappers/tinyc.nim` | addFile（49-52行目） |
| 4-2 | tinyc.nim | `lib/wrappers/tinyc.nim` | compileString（54-56行目） |

#### Step 5: リンク・実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | tinyc.nim | `lib/wrappers/tinyc.nim` | 出力タイプ定数（61-67行目） |
| 5-2 | tinyc.nim | `lib/wrappers/tinyc.nim` | setOutputType（69-71行目） |
| 5-3 | tinyc.nim | `lib/wrappers/tinyc.nim` | addLibraryPath/addLibrary（73-79行目） |
| 5-4 | tinyc.nim | `lib/wrappers/tinyc.nim` | addSymbol（81-83行目） |
| 5-5 | tinyc.nim | `lib/wrappers/tinyc.nim` | outputFile（85-88行目） |
| 5-6 | tinyc.nim | `lib/wrappers/tinyc.nim` | run（90-93行目） |
| 5-7 | tinyc.nim | `lib/wrappers/tinyc.nim` | relocate（95-99行目） |
| 5-8 | tinyc.nim | `lib/wrappers/tinyc.nim` | getSymbol（101-103行目） |
| 5-9 | tinyc.nim | `lib/wrappers/tinyc.nim` | setLibPath（105-107行目） |

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

```
アプリケーション
    │
    ├─ openCCState()
    │      └─ TCC: tcc_new
    │
    ├─ setOutputType(OutputMemory)
    │      └─ TCC: tcc_set_output_type
    │
    ├─ コンパイル設定
    │      ├─ addIncludePath()
    │      ├─ defineSymbol()
    │      └─ addLibrary()
    │
    ├─ compileString(cCode)
    │      └─ TCC: tcc_compile_string
    │
    ├─ relocate(nil)
    │      └─ TCC: tcc_relocate
    │
    ├─ getSymbol("main")
    │      └─ TCC: tcc_get_symbol
    │             └─ 関数ポインタを取得
    │
    └─ closeCCState()
           └─ TCC: tcc_delete
```

### データフロー図

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

Cソースコード ───▶ compileString ───▶ 内部表現
    │
    ├─ ヘッダファイル ──▶ addIncludePath
    ├─ ライブラリ ─────▶ addLibrary
    └─ 定義 ───────────▶ defineSymbol
                            │
                            ▼
                        relocate
                            │
                            ▼
                    ┌───────┴───────┐
                    │               │
                    ▼               ▼
               run(main)      getSymbol()
                    │               │
                    ▼               ▼
               実行結果        関数ポインタ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tinyc.nim | `lib/wrappers/tinyc.nim` | ソース | TCCラッパー |
| sysatomics.nim | `lib/std/sysatomics.nim` | ソース | TCC用CAS実装含む |
