Skip to content

compiler-backend-roadmap.md

Latest commit

 

History

History
120 lines (93 loc) · 5.03 KB

compiler-backend-roadmap.md

File metadata and controls

120 lines (93 loc) · 5.03 KB
Raw

Compiler Backend Roadmap

This document describes how the Spanda compiler evolves from the current tree-walking interpreter toward native binaries via LLVM.

Current pipeline (implemented)

Spanda source (.sd)
  → lexer
  → parser
  → AST
  → semantic / type checker
  → interpreter / simulator / hardware verifier

The authoritative implementation lives in Rust (crates/spanda-core). A TypeScript mirror (src/) supports tests, the web playground, and CLI delegation when the native binary is built.

Supporting outputs today:

Output Command Status
Diagnostics spanda check Implemented
Compatibility report spanda verify Implemented
Interpreted run spanda run / spanda sim Implemented (native-primary with interpreter LTS fallback)
Formatted source spanda fmt Implemented
Markdown docs spanda doc Implemented
Skeleton codegen spanda codegen --target native|wasm|esp32 Stubbed (SIR-aware template C/WASM/ESP32, not a real compiler)
WASM manifest spanda deploy --target wasm Partially implemented

Future pipeline (planned)

Spanda source (.sd)
  → Spanda IR (SIR)
  → LLVM IR
  → native binary / WASM module

Milestone 1 — Spanda IR (SIR) ✓ (extended)

  • Lower typed AST to SIR preserving module functions, extern bridge kinds, imports, behavior metadata (requires/ensures/invariant flags, task names), and robot names.
  • spanda ir [--json] file.sd emits SIR for codegen planning and CI inspection.
  • SIR is the contract between frontend and backends; the interpreter still executes AST directly.

Milestone 2 — LLVM backend ✓ (extended)

  • spanda llvm-ir [--target-triple <triple>] file.sd emits LLVM IR from SIR with libspanda_rt declarations and calls for supported statements (actuator drive/stop, publish/subscribe with string payloads, constant if, loop every, emergency stop, integer returns).
  • spanda compile-native [--out <binary>] [--target-triple <triple>] file.sd links LLVM IR with libspanda_rt via clang when available.
  • crates/spanda-rt exposes the C ABI (spanda_rt_drive, spanda_rt_stop, spanda_rt_publish, spanda_rt_subscribe, spanda_rt_loop_delay_ms, …).
  • crates/spanda-llvm lowers bool variable if (alloca/br) and unit-enum match (switch); payload variants remain planned.
  • Robot scheduler, safety monitor, and comm routing remain in libspanda_rt (interpreter-backed for now).
  • -O2 builds for deployment; -O0 + debug info for DAP debugging.

Milestone 3 — Cross-compilation (partial)

  • --target-triple on llvm-ir and compile-native selects the LLVM/clang target (e.g. aarch64-unknown-linux-gnu).
  • HAL profiles and conditional compilation for Jetson vs ESP32 remain planned.
  • scripts/llvm_golden_path.sh exercises hello_world.sd and examples/showcase/autonomous_rover/rover.sd when clang is available (CI Nightly signal).
  • spanda run / spanda sim use native-primary dispatch (ExecutionRuntime::Auto); interpreter LTS when SIR is ineligible or clang is missing (--runtime, SPANDA_RUNTIME).

Target platforms

Platform Architecture Priority Notes
Linux x86_64 amd64 P1 Dev machines, CI, cloud agents
macOS aarch64 / x86_64 P1 Developer workstations
Windows x86_64 P2 Simulation and tooling
Linux ARM64 aarch64 P1 Raspberry Pi 5, custom SBCs
NVIDIA Jetson aarch64 + CUDA P1 Vision / AI edge workloads
Raspberry Pi aarch64 P2 Low-cost robotics
ESP32 xtensa / riscv P3 Microcontroller targets via existing codegen stub
RISC-V rv64gc P3 Open hardware platforms
WASM wasm32 P2 Browser playground, serverless agents

What stays interpreted (for now)

These subsystems depend on dynamic robot graphs and are expensive to compile prematurely:

  • Full hardware compatibility matrix (spanda verify --all-targets)
  • Digital twin replay buffers
  • Mock AI providers and agent planning loops
  • Transport adapter discovery (ROS2/MQTT/DDS stubs)

They will remain in libspanda_rt even after LLVM codegen ships.

Self-hosting path

See roadmap.md. Bootstrap order:

  1. Rust implements full language (current)
  2. Spec stabilization — grammar + api-contract.json
  3. Spanda subset rewritten in Spanda (lexer/parser for minimal .sd)
  4. Incremental migration — type checker, then SIR, then LLVM
  5. Rust optional for embedded/WASM targets

Debugging

Stage Tool Status
Interpreter breakpoints spanda debug --break N Partially implemented
DAP server crates/spanda-dap Partially implemented
LLVM debug symbols — Planned

Related documents