# アーキテクチャ設計書

## 概要

本ドキュメントは、Nimプログラミング言語のコンパイラおよび標準ライブラリのアーキテクチャ設計を記載する。Nimコンパイラは自身がNim言語で記述されたセルフホスティングコンパイラであり、複数のバックエンド（C、C++、Objective-C、JavaScript）へのコード生成をサポートするマルチパイプラインアーキテクチャを採用している。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| Cコンパイラ（GCC, Clang, MSVC等） | プロセス起動 | 生成されたCコードのコンパイル・リンク |
| Node.js | プロセス起動 | JavaScriptバックエンド実行時のランタイム |
| Nimble（パッケージマネージャー） | CLI連携 | パッケージ管理、依存関係解決 |
| csources_v3 | ブートストラップ | コンパイラのブートストラップビルド |
| FFIライブラリ | 動的リンク | 外部Cライブラリとの連携 |

## レイヤー構成

### アーキテクチャスタイル

パイプライン/パス型アーキテクチャ（Multi-Pass Compiler Architecture）

Nimコンパイラは従来的なコンパイラ設計に基づき、複数のフェーズ（パス）を経てソースコードを処理する。各パスは独立したモジュールとして実装され、パイプラインを通じて連携する。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| フロントエンド | ソースコードの字句解析・構文解析・意味解析 | `lexer.nim`, `parser.nim`, `sem*.nim` |
| 中間表現 | 抽象構文木（AST）の管理と変換 | `ast.nim`, `astdef.nim`, `transf.nim` |
| バックエンド | ターゲットコードの生成 | `cgen.nim`, `jsgen.nim`, `nifgen.nim` |
| ランタイムライブラリ | 実行時サポート機能 | `lib/system.nim`, `lib/pure/*`, `lib/std/*` |
| ツール層 | 開発支援ツール | `nimsuggest/`, `nimpretty/`, `testament/` |

### レイヤー間の依存関係ルール

- **依存の方向性**: フロントエンド -> 中間表現 -> バックエンドの一方向依存
- **許可される参照**: 上位レイヤーから下位レイヤーへの参照、共通モジュール（`options.nim`, `msgs.nim`等）への参照
- **禁止される参照**: バックエンドからフロントエンドへの直接参照、ランタイムライブラリからコンパイラへの参照

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| 字句解析 | トークン化、識別子管理 | `lexer.nim`, `idents.nim`, `nimlexbase.nim` |
| 構文解析 | AST構築、構文検証 | `parser.nim`, `syntaxes.nim` |
| 意味解析 | 型検査、シンボル解決、マクロ展開 | `sem.nim`, `semexprs.nim`, `semstmts.nim`, `semtypes.nim`, `sigmatch.nim` |
| 変換 | AST変換、最適化 | `transf.nim`, `injectdestructors.nim`, `lambdalifting.nim` |
| Cコード生成 | C/C++/Objective-Cコード生成 | `cgen.nim`, `ccgexprs.nim`, `ccgstmts.nim`, `ccgtypes.nim` |
| JavaScriptコード生成 | JavaScriptコード生成 | `jsgen.nim`, `jstypes.nim` |
| 仮想マシン | コンパイル時評価、NimScript実行 | `vm.nim`, `vmdef.nim`, `vmgen.nim` |
| ドキュメント生成 | APIドキュメント生成 | `docgen.nim`, `docgen2.nim` |

### パッケージ構造

```
Nim-devel/
├── compiler/                 # コンパイラ本体
│   ├── nim.nim              # コンパイラエントリポイント
│   ├── main.nim             # コマンドディスパッチャー
│   ├── pipelines.nim        # パイプライン処理
│   ├── passes.nim           # パス管理
│   ├── lexer.nim            # 字句解析器
│   ├── parser.nim           # 構文解析器
│   ├── sem*.nim             # 意味解析モジュール群
│   ├── cgen*.nim            # Cコード生成モジュール群
│   ├── jsgen.nim            # JavaScriptコード生成
│   ├── vm*.nim              # 仮想マシンモジュール群
│   ├── ast*.nim             # AST関連モジュール群
│   ├── ic/                  # インクリメンタルコンパイル
│   └── plugins/             # コンパイラプラグイン
├── lib/                     # 標準ライブラリ
│   ├── system.nim           # システムモジュール（暗黙的にインポート）
│   ├── core/                # コアモジュール
│   ├── pure/                # 純粋Nimモジュール
│   ├── std/                 # 標準モジュール
│   ├── impure/              # 外部依存モジュール
│   ├── wrappers/            # Cラッパーモジュール
│   ├── posix/               # POSIX API
│   ├── windows/             # Windows API
│   └── js/                  # JavaScript固有モジュール
├── nimsuggest/              # IDE統合ツール
├── nimpretty/               # コードフォーマッター
├── testament/               # テストフレームワーク
├── tools/                   # 開発ツール群
├── doc/                     # ドキュメント
├── tests/                   # テストスイート
├── config/                  # 設定ファイル
└── koch.nim                 # ビルドツール
```

### コンポーネント依存関係

```
nim.nim (エントリポイント)
    └── main.nim (コマンドディスパッチャー)
        ├── pipelines.nim (パイプライン制御)
        │   ├── parser.nim (構文解析)
        │   │   └── lexer.nim (字句解析)
        │   ├── sem.nim (意味解析)
        │   │   ├── semexprs.nim (式の意味解析)
        │   │   ├── semstmts.nim (文の意味解析)
        │   │   ├── semtypes.nim (型の意味解析)
        │   │   └── sigmatch.nim (オーバーロード解決)
        │   ├── cgen.nim (Cコード生成)
        │   ├── jsgen.nim (JSコード生成)
        │   └── vm.nim (仮想マシン)
        ├── modulegraphs.nim (モジュールグラフ)
        └── options.nim (コンパイラオプション)
```

## ミドルウェア構成

### データベース

本プロジェクトはコンパイラであり、外部データベースは使用しない。

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| 内部ストレージ | RODファイル | N/A | インクリメンタルコンパイルキャッシュ |
| 内部ストレージ | NIFファイル | N/A | 新インクリメンタルコンパイル形式 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| インメモリキャッシュ | N/A | 型インスタンス化キャッシュ | コンパイル中のみ |
| インメモリキャッシュ | N/A | シンボルキャッシュ | コンパイル中のみ |
| ファイルキャッシュ（nimcache） | N/A | 生成Cファイル、オブジェクトファイル | 明示的削除まで |

### メッセージキュー

該当なし（コンパイラのため非同期メッセージングは使用しない）

### 検索エンジン

該当なし

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| 外部Cコンパイラ | 各種 | 生成されたCコードのコンパイル |

## データフロー

### リクエスト処理の流れ

コンパイルコマンド実行時の処理フロー:

1. **コマンドライン解析** (`nim.nim`): コマンドライン引数を解析し、設定オブジェクトを構築
2. **設定ロード** (`nimconf.nim`): 設定ファイル（nim.cfg等）を読み込み
3. **モジュールグラフ初期化** (`modulegraphs.nim`): コンパイル対象のモジュールグラフを初期化
4. **パイプライン実行** (`pipelines.nim`): 選択されたパイプラインパスを実行
   - 4.1 **字句解析** (`lexer.nim`): ソースコードをトークン列に変換
   - 4.2 **構文解析** (`parser.nim`): トークン列からASTを構築
   - 4.3 **意味解析** (`sem.nim`): 型検査、シンボル解決、マクロ展開
   - 4.4 **変換** (`transf.nim`): AST変換、デストラクタ注入
   - 4.5 **コード生成** (`cgen.nim`/`jsgen.nim`): ターゲットコード生成
5. **外部コンパイラ呼び出し** (`extccomp.nim`): 生成されたCコードをコンパイル
6. **リンク** (`extccomp.nim`): オブジェクトファイルをリンクして実行ファイル生成

### 非同期処理の流れ

コンパイラ自体は同期処理で動作する。ただし、マクロ・テンプレート展開時のコンパイル時評価は仮想マシン（VM）で実行される。

1. **マクロ呼び出し検出** (`semexprs.nim`): 意味解析中にマクロ呼び出しを検出
2. **VMコード生成** (`vmgen.nim`): マクロ本体をVMバイトコードに変換
3. **VM実行** (`vm.nim`): バイトコードを実行し、AST変換結果を取得
4. **結果挿入**: 変換されたASTを元のAST位置に挿入

### データ永続化の流れ

1. **nimcacheへの保存**: 生成されたCファイル、オブジェクトファイルを`nimcache`ディレクトリに保存
2. **ROD/NIFファイル保存**: インクリメンタルコンパイル情報をファイルに永続化
3. **ビルド指示JSON**: コンパイル設定をJSONファイルとして保存（再コンパイル最適化用）

## 横断的関心事

### 認証・認可

該当なし（コンパイラであるため）

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| コンパイルログ | `msgs.nim` | 標準出力/標準エラー出力 |
| ヒント/警告/エラー | `msgs.nim` | 標準出力/標準エラー出力 |
| デバッグ情報 | `debugutils.nim` | 標準出力/標準エラー出力 |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 字句解析エラー | 即時報告 | エラーメッセージ出力、コンパイル中断 |
| 構文解析エラー | 即時報告 | エラーメッセージ出力、コンパイル中断 |
| 意味解析エラー | 蓄積・報告 | エラーメッセージ出力（複数エラー対応） |
| コード生成エラー | 即時報告 | 内部エラーとして報告 |
| 外部コンパイラエラー | 外部出力転送 | 外部コンパイラのエラーを表示 |

エラーハンドリングの方針:
- `errorhandling.nim`で定義されたエラー型を使用
- `msgs.nim`で集中的にメッセージを管理
- `--errorMax`オプションで最大エラー数を制御可能

### トランザクション管理

該当なし（コンパイラであるため）

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| パイプラインパターン | コンパイルフロー全体 | `pipelines.nim`でのパス管理 |
| ビジターパターン | AST走査 | `semexprs.nim`での式評価 |
| ファクトリパターン | AST生成 | `ast.nim`での`newNode`系関数 |
| シングルトンパターン | グローバル設定 | `ConfigRef`インスタンス |
| ストラテジーパターン | バックエンド選択 | `PipelinePass`列挙型による切り替え |

### コーディング規約

- **命名規則**: NEP-1（Nim Enhancement Proposal 1）に準拠
  - 型名: PascalCase（例: `TNodeKind`, `PNode`）
  - 関数名: camelCase（例: `parseExpr`, `semStmt`）
  - 定数: camelCaseまたはPascalCase
- **インデント**: 2スペース
- **行長**: 推奨80文字、最大120文字
- **コメント**: `##`によるドキュメントコメント
- **プレフィックス規則**:
  - `T`プレフィックス: 列挙型および古いスタイルの型
  - `P`プレフィックス: ポインタ/参照型（例: `PSym`, `PNode`）
- **モジュール構成**: 関連機能を同一ファイルに集約

## 備考

### セルフホスティング

Nimコンパイラは自身がNim言語で記述されている。初回ビルドには`csources_v3`リポジトリのCソースを使用してブートストラップする必要がある。

### マルチバックエンド対応

Nimは以下のバックエンドをサポート:
- **C**: デフォルトバックエンド、高い移植性
- **C++**: C++ライブラリとの連携用
- **Objective-C**: macOS/iOS開発用
- **JavaScript**: Webブラウザ/Node.js向け
- **NIF**: 新しいインクリメンタルコンパイル形式

### 仮想マシン（VM）

コンパイル時評価（static式、constセクション）およびNimScript実行にはレジスタベースの仮想マシンを使用。VMは`vm.nim`で実装され、バイトコードは`vmgen.nim`で生成される。

### インクリメンタルコンパイル

現在、2つのアプローチが存在:
- **RODファイル**: 従来のインクリメンタルコンパイル形式
- **NIFファイル**: 新しいインクリメンタルコンパイル形式（開発中）
