tomoaki/hakorune

Fork 0

Files

nyash-codex 8fd3a2b509 docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

2025-10-31 18:00:10 +09:00

9.8 KiB

Raw Blame History

Phase 20.5 — Index

Escape from Rust: Bootstrap Compiler Implementation

Status: Planning (Gate plan active) Duration: 10 weeks (2025-12-21 - 2026-02-28)

📚 Documentation Structure

Core Documents

README.md ⭐ START HERE
- Phase overview and goals
- Weekly breakdown (Week 1-10)
- Implementation strategy decision (Option B)
- Success criteria and DoD
MILESTONE.md
- Objectives and deliverables
- Weekly milestones
- Success criteria
- Risk analysis
BOOTSTRAP_CHAIN_ANALYSIS.md
- 3-stage bootstrap chain detailed design
- Stage 1 (Rust) → Stage 2 (Hako v1) → Stage 3 (Hako v2)
- Data flow analysis
- Verification strategy
C_CODE_GENERATOR_DESIGN.md
- MIR → C conversion design
- 16-instruction mapping table
- PHI resolution strategy
- Test strategy (43 test cases)
PLAN.md ✅ Gate-based execution plan（短縮版）
- 5行サマリ / 最小命令セット / DoD
- Gate A〜E（Parser→MIR→VM PoC→op_eq→統合）
- テスト/CI/リスク/次ステップ

🎯 Quick Reference

What is Phase 20.5? (5-line summary)

Goal: 脱Rust。凍結EXEを土台に自己ホストへ前進。
Strategy: Gate方式（Parser→MIR→VM PoC→op_eq→統合）。
Boundary: C‑ABI/HostBridgeのみ外部境界。中はEverything is Box。
Proof: 決定性（JSON正規化）、Golden＆固定点で検証。
Policy: 小さく、順序よく、SKIPはWARN、回帰のみFAIL。

Key Deliverables

Bootstrap Compiler (apps/bootstrap-compiler/)
- Written in Hakorune
- Runs on frozen EXE
- Outputs C code
C Code Generator
- MIR JSON → C source
- 16 instructions fully supported
- NyRT function calls
Verification
- v1 == v2 (compiler parity)
- v2 == v3 (fixed point)
- 10 test programs PASS

📊 Timeline at a Glance

Weeks	Focus	Deliverable
1-2	Design & Analysis	Design docs complete
3-4	Parser Adaptation	Parser works on frozen EXE
5-6	MIR Builder Migration	MIR JSON generation works
7-8	C Code Generator	C code emission works
9	Bootstrap Integration	v1 == v2 verified
10	Documentation & Review	Phase complete

🔄 Bootstrap Chain Overview

      ┌─────────────────┐
      │ hako-frozen-v1  │
      │   (Rust, 724KB) │
      └────────┬────────┘
               │
               │ compiles
               v
      ┌─────────────────┐
      │ bootstrap_v1    │
      │ (Hakorune code) │
      │ runs on frozen  │
      └────────┬────────┘
               │
               │ compiles itself
               v
      ┌─────────────────┐
      │ bootstrap_v2.c  │
      │ (C source)      │
      └────────┬────────┘
               │
               │ clang + NyRT
               v
      ┌─────────────────┐
      │ bootstrap_v2    │
      │ (native binary) │
      └─────────────────┘

      Verify: v1 output == v2 output ✅

💡 Implementation Strategy

Decision: Option B (Reuse apps/selfhost-compiler/)

Rationale:

2500 lines of existing, tested code
170 smoke tests already PASS
90%+ reusability
Proven architecture

Code Reuse Breakdown:

✅ 90% Reusable: Parser, Emitter, MIR Builder (2250 lines)
⚠️ 10% Adaptation: using paths, Box constraints (250 lines)
❌ New Code: C Code Generator (500 lines)

Total Effort: ~750 lines (vs 2500+ for Option A)

🧪 Test Strategy

Test Pyramid

         /\
        /  \    Level 3: Self-Compilation (1 test, slow)
       /____\   - v1 compiles itself → v2
      /      \  - v2 compiles itself → v3
     /        \ - Verify: v2 == v3
    /__________\
   /            \ Level 2: Comprehensive (10 tests, medium)
  /              \ - If/else, loops, functions, boxes, arrays
 /________________\
/                  \ Level 1: Smoke Tests (43 tests, fast)
                     - Each MIR instruction
                     - Basic parsing
                     - C generation

📦 Directory Structure

Phase 20.5 Planning:
docs/private/roadmap/phases/phase-20.5/
├── INDEX.md                          # ← You are here
├── README.md                         # Phase overview
├── MILESTONE.md                      # Milestones & DoD
├── BOOTSTRAP_CHAIN_ANALYSIS.md       # 3-stage bootstrap
├── C_CODE_GENERATOR_DESIGN.md        # C codegen design
├── REUSABILITY_ANALYSIS.md           # (Week 1-2 deliverable)
├── RISK_ASSESSMENT.md                # (Week 1-2 deliverable)
├── IMPLEMENTATION_GUIDE.md           # (Week 3+ deliverable)
└── COMPLETION_REPORT.md              # (Week 10 deliverable)

Implementation:
apps/bootstrap-compiler/
├── parser/                           # Week 3-4
│   ├── parser_box.hako
│   └── lexer_box.hako
├── mir_builder/                      # Week 5-6
│   └── builder_box.hako
├── codegen/                          # Week 7-8
│   ├── c_emitter_box.hako
│   └── c_runtime_box.hako
├── tests/                            # Week 3-9
│   ├── smoke/                        # 43 tests
│   ├── integration/                  # 10 tests
│   └── bootstrap/                    # 1 test (v1==v2==v3)
├── main.hako                         # Entry point
└── README.md                         # User guide

🚀 Quick Start (After Phase Complete)

Compile a Hakorune Program

# Stage 1: Use frozen EXE to run bootstrap compiler
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
  --input my_program.hako \
  --output my_program.c

# Stage 2: Compile C to native binary
clang my_program.c -o my_program \
  -L /path/to/hako_kernel \
  -lhako_kernel \
  -lpthread -ldl -lm

# Stage 3: Run
./my_program

Verify Bootstrap Chain

# Run verification script
bash tools/verify_bootstrap_chain.sh

# Expected output:
# ✅ Stage 1 → Stage 2: OK
# ✅ Stage 2 → Stage 3: OK
# ✅ v1 == v2: VERIFIED
# ✅ v2 == v3: VERIFIED (fixed point)
# ✅ Bootstrap chain complete!

⚠️ Prerequisites

From Phase 15.77

Frozen EXE built and tested (hako-frozen-v1.exe)
NyRT function calls working (Result: 6 test PASS)
MIR JSON → .o → EXE pipeline verified
Windows (MSVC/MinGW) + Linux support

For Phase 20.5

apps/selfhost-compiler/ analysis complete (Week 1-2)
Frozen EXE constraints documented (Week 1-2)
C Code Generator design approved (Week 1-2)
Test infrastructure ready (Week 3+)

🎯 Success Criteria Summary

Technical

Bootstrap chain works: Stage 1 → 2 → 3
C Code Generator: 16/16 instructions supported
Verification: v1 == v2 == v3 (identical output)
Tests: 43 smoke + 10 integration + 1 bootstrap PASS

Performance

Stage 2 compile time: < 30s for self-compilation
Stage 3 compile time: < 5s for self-compilation
Memory usage: < 100MB

Quality

Documentation complete (user guide + design docs)
Code is modular (Box-based)
Edge cases covered
Review approved (ChatGPT + Claude)

Phase 20.6 - Complete Rust Removal
- VM executor → Hakorune implementation
- Rust codebase → 0 lines
- Pure Hakorune self-hosting

Parallel

Phase 15.78 - Frozen UX Polish
- Distribution packaging
- Doctor improvements
- Windows polish

💬 Communication

Weekly Sync Points

Monday: Week start, goal setting
Wednesday: Mid-week progress check
Friday: Week review, next week planning

Issue Tracking

Use GitHub issues with label phase-20.5
Prefix: [20.5] in commit messages
Milestone: Phase 20.5 - Bootstrap Compiler

Review Process

Each week: Self-review + smoke tests
Week 5, 10: Full review with ChatGPT/Claude
Blocking issues: Immediate escalation

🔗 External Resources

Industry Examples

Rust Bootstrap: Rust stage0 documentation
Go Bootstrap: Go 1.5 Bootstrap Process
OCaml Bootstrap: OCaml self-hosting

Papers

Rapid Self-Hosting Paper
Reflections on Trusting Trust (Ken Thompson, 1984)

📝 Notes

Naming Conventions

Stage 1: Rust compiler, frozen EXE (hako-frozen-v1)
Stage 2: Hakorune compiler v1 (bootstrap_v1)
Stage 3: Hakorune compiler v2 (bootstrap_v2)
Fixed Point: v2 == v3 (self-consistency)

File Naming

Test outputs: test_v1.c, test_v2.c
Bootstrap outputs: bootstrap_v2.c, bootstrap_v3.c
Always include version suffix for clarity

Verification

Use diff for exact comparison
Use md5sum for quick hash checks
Use tools/verify_bootstrap_chain.sh for automation

Created: 2025-10-14 Last Updated: 2025-10-14 Status: Planning (Phase not yet started) Next Review: 2025-12-21 (Phase start)

9.8 KiB Raw Blame History Unescape Escape