366 lines
9.8 KiB
Markdown
366 lines
9.8 KiB
Markdown
# 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
|
||
|
||
1. **[README.md](README.md)** ⭐ START HERE
|
||
- Phase overview and goals
|
||
- Weekly breakdown (Week 1-10)
|
||
- Implementation strategy decision (Option B)
|
||
- Success criteria and DoD
|
||
|
||
2. **[MILESTONE.md](MILESTONE.md)**
|
||
- Objectives and deliverables
|
||
- Weekly milestones
|
||
- Success criteria
|
||
- Risk analysis
|
||
|
||
3. **[BOOTSTRAP_CHAIN_ANALYSIS.md](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
|
||
|
||
4. **[C_CODE_GENERATOR_DESIGN.md](C_CODE_GENERATOR_DESIGN.md)**
|
||
- MIR → C conversion design
|
||
- 16-instruction mapping table
|
||
- PHI resolution strategy
|
||
- Test strategy (43 test cases)
|
||
|
||
5. **[PLAN.md](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)
|
||
|
||
1) Goal: 脱Rust。凍結EXEを土台に自己ホストへ前進。
|
||
2) Strategy: Gate方式（Parser→MIR→VM PoC→op_eq→統合）。
|
||
3) Boundary: C‑ABI/HostBridgeのみ外部境界。中はEverything is Box。
|
||
4) Proof: 決定性（JSON正規化）、Golden＆固定点で検証。
|
||
5) Policy: 小さく、順序よく、SKIPはWARN、回帰のみFAIL。
|
||
|
||
### Key Deliverables
|
||
|
||
1. **Bootstrap Compiler** (`apps/bootstrap-compiler/`)
|
||
- Written in Hakorune
|
||
- Runs on frozen EXE
|
||
- Outputs C code
|
||
|
||
2. **C Code Generator**
|
||
- MIR JSON → C source
|
||
- 16 instructions fully supported
|
||
- NyRT function calls
|
||
|
||
3. **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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
- [x] Frozen EXE built and tested (`hako-frozen-v1.exe`)
|
||
- [x] NyRT function calls working (Result: 6 test PASS)
|
||
- [x] MIR JSON → .o → EXE pipeline verified
|
||
- [x] 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)
|
||
|
||
---
|
||
|
||
## 📚 Related Phases
|
||
|
||
### Previous
|
||
|
||
- [Phase 15.77 - Frozen EXE Finalization](../phase-15.77/)
|
||
- [Phase 15.76 - extern_c & Frozen Toolchain](../phase-15.76/)
|
||
- [Phase 15.75 - Escape from Rust Planning](../phase-15.75/)
|
||
|
||
### Next
|
||
|
||
- **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](../phase-15.78/)
|
||
- 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](https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html)
|
||
- **Go Bootstrap**: [Go 1.5 Bootstrap Process](https://go.dev/doc/go1.5#bootstrap)
|
||
- **OCaml Bootstrap**: [OCaml self-hosting](https://ocaml.org/docs/compiling-ocaml-projects)
|
||
|
||
### Papers
|
||
|
||
- [Rapid Self-Hosting Paper](../../../../private/papers-active/rapid-selfhost-ai-collaboration/)
|
||
- [Reflections on Trusting Trust](https://www.cs.cmu.edu/~rdriley/487/papers/Thompson_1984_ReflectionsonTrustingTrust.pdf) (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)
|