hakorune/docs/private/roadmap/phases/phase-20.20

Phase 20.20 — C ABI Export via LLVM（設計・計画）

目的

• Hakorune スクリプトから LLVM（llvmlite）を用いて C ABI 互換の関数をエクスポートできる最小ラインを構築する。
• Rust 層の一部（AOT/エクスポート境界）を置き換え可能な薄い導線を用意し、段階的に Rust 依存を薄くする。

スコープ（段階導入）

• 短期（Phase 20.20）: プリミティブ型（i64/i32）限定の純関数エクスポート。
  • @extern_c("c_symbol") 注釈を MIR JSON へ反映。
  • llvmlite で C calling convention（ccc）・unmangled symbol・visibility を設定したラッパー関数を生成。
  • C ヘッダー自動生成（extern "C"、stdint.h 依存、最小プロトタイプ）。
• 中期（次フェーズ）: String（const char* readonly）、Array（ptr+len 構造体）の読み出しサポート。
• 長期: Box ABI（Arc/RefCell 相当）と GC 連携（高リスク。段階的に）

進捗（2025‑10‑30, M2 到達）

• Python/llvmlite ビルダーに C‑ABI ラッパ生成を実装（flags.extern_c / metadata.extern_c）
  • MIR(JSON) 例（v1）:

    {
      "schema_version": "1.0",
      "functions": [
        { "name": "add/2",
          "params": [{"name":"a","type":"i64"},{"name":"b","type":"i64"}],
          "blocks": [],
          "flags": { "extern_c": "hako_add" }
        }
      ]
    }
    

  • 生成IR: define i64 @hako_add(i64,i64) が挿入され、内部 @"add/2" を呼び出す
  • 使い方: python3 tools/llvmlite_harness.py --in mir.json --emit-ll out.ll（または --out out.o）

非対象（このフェーズ）

• メモリ管理（自動管理）
• 参照循環/所有権を跨いだ複雑な Box ABI
• 既存 CLI/VM ラインの既定挙動変更（すべて既定 OFF の新フラグでガード）

設計原則

• Box‑First（境界を箱化）: C ABI 層は src/llvm_py/abi/（純粋ツール）に隔離。VM/Runner へ依存しない。
• Fail‑Fast: 型不一致や未対応は IR 生成前にエラーメッセージで停止。
• ENV 最小: 既定は CLI フラグ優先。ENV は開発支援の短命 TTL のみ。

受け入れ基準（MVP）

• @extern_c("hako_add") を付与した i64 加算関数が .o と .h に出力され、C からリンクして実行可能。
• Linux/Mac/Win いずれか 1 プラットフォームで visibility/dllexport 設定に問題がない（警告なし）。
• MIR 注釈 → IR ラッパ生成 → ヘッダー生成の一貫性（SSOT）を満たす。

---

関連ドキュメント（起票予定）

• docs/development/abi/README.md — C ABI 全体設計・制約
• docs/development/abi/types.md — MIR 型→C 型マッピング（SSOT）