Complete documentation for the ReScript → IC10 assembly compiler

• 🚀 Getting Started
• 📚 User Guides
• 🏗️ Architecture
• 💻 Implementation Details
• 🧪 Testing
• 📦 Archive

New to the compiler? Start here:

1. Compiler Overview - Project structure, architecture, and development workflow
2. Language Reference - Complete ReScript subset language guide
3. IC10 Support - IC10 assembly features and device operations

• ✅ Variables and arithmetic operations
• ✅ Control flow (if/else, while loops)
• ✅ Mutable references
• ✅ Variant types with pattern matching
• ✅ Device I/O operations
• ✅ Raw assembly instructions

ReScript Source
      ↓
   Lexer.res         → Tokenization
      ↓
   Parser.res        → AST Generation
      ↓
  Optimizer.res      → AST-level optimizations
      ↓
   ┌────────────────┐
   │ IR Pipeline    │
   ├────────────────┤
   │ IRGen.res      │ → IR generation
   │ IROptimizer    │ → IR optimizations
   └────────────────┘
      ↓
   ┌────────────────┐
   │   Backends     │
   ├────────────────┤
   │ IRToIC10.res   │ → IC10 assembly (default)
   │ IRToWASM.res   │ → WebAssembly text format
   └────────────────┘
      ↓
  Target Output (IC10 or WASM)

• Hybrid ReScript/TypeScript: Core compiler in ReScript, VSCode extension in TypeScript
• 16 Registers: r0-r15 with split allocation (variables vs temps)
• Fixed Stack Layout: Variant types use pre-allocated stack regions
• IR Layer: Optional intermediate representation with 7 optimization passes (17% code reduction)

// Variable registers: r0-r13 (low to high)
let x = 5         // → r0
let y = 10        // → r1

// Temp registers: r15-r14 (high to low)
switch state {
| Active(n) => n  // n → r15 (freed after case)
}

type state = Idle | Active(int)

stack[0] = tag (0=Idle, 1=Active)
stack[1] = Active arg0

if x < y { ... }
→ blt r0 r1 then_label  // Direct branch (optimized)

• Basic: Variables, arithmetic, constant folding
• Comparisons: All comparison operators with if/else
• Complex Expressions: Operator precedence, mixed operations
• Scoping: Variable shadowing, nested blocks
• Control Flow: If/else, while loops, infinite loops
• Variants: Type declarations, pattern matching, switches
• Error Handling: Syntax errors, register exhaustion

npm test                    # Run all tests
npm test loops              # Run specific test suite
npm run res:build          # Rebuild ReScript compiler

Historical documents and implementation records:

rescript-ic10-compiler/
├── src/
│   ├── compiler/           # ReScript compiler core
│   │   ├── Lexer.res      # Tokenization
│   │   ├── Parser.res     # AST generation
│   │   ├── AST.res        # AST definitions
│   │   ├── StmtGen.res    # Statement code generation
│   │   ├── ExprGen.res    # Expression code generation
│   │   ├── BranchGen.res  # Control flow generation
│   │   ├── RegisterAlloc.res # Register management
│   │   ├── Codegen.res    # Main codegen orchestrator
│   │   └── IR/            # Intermediate representation
│   │       ├── IR.res     # IR definitions
│   │       ├── IRGen.res  # AST → IR conversion
│   │       ├── IROptimizer.res # IR-level optimizations
│   │       ├── IRPrint.res # IR pretty printer
│   │       └── IRToIC10.res # IR → IC10 lowering
│   └── extension.ts       # VSCode extension (TypeScript)
├── tests/                 # Jest test suites
├── docs/                  # Documentation (you are here!)
│   ├── user-guide/       # Language and usage guides
│   ├── architecture/     # Design documents
│   ├── implementation/   # Implementation details
│   ├── testing/          # Test documentation
│   └── archive/          # Historical documents
└── testing/              # Test files
    └── test.res         # Sample ReScript code

• User guides: lowercase-with-dashes.md
• Architecture: descriptive-name.md
• Implementation: feature-name.md
• Archive: original-purpose.md

• ✅ Use relative links for cross-referencing
• ✅ Include code examples with expected output
• ✅ Explain both "what" and "why"
• ✅ Keep examples simple and focused
• ✅ Update docs when features change

When adding new features or fixing bugs:

1. Update relevant documentation
2. Add test cases
3. Update CLAUDE.md if architecture changes
4. Consider adding examples to user guides

• Stationeers IC10 Wiki: Official IC10 Documentation
• ReScript Documentation: rescript-lang.org
• VSCode Extension API: code.visualstudio.com/api

User Guides

• Language Reference
• IC10 Support
• IC10 Bindings
• IC10 Usage Guide

Architecture

• Compiler Overview
• Stack Layout
• IR Design
• Device I/O Operations

Implementation

• Loops
• Switch Statements
• Variants
• Implementation Notes

Testing

• IC10 Tests

Archive

• Implementation Plan
• Implementation Complete
• Switch Bug Investigation
• Fix Tests

Last Updated: 2025-11-13 Documentation Version: 2.0 Compiler Version: See package.json