Simple Language

Simple is a self-hosted language and toolchain that combines a readable Python-like surface with compiler-integrated testing, documentation, architecture rules, and baremetal-oriented execution paths.

The repo is unusually broad: language, compiler, interpreter, loader, test runner, doc generation, traceability tooling, SDN-backed project databases, editor tooling, and hardware-oriented test flows all live together.

Quick Navigation: Distinctive Features | Feature Status | Quick Start | Language Basics | Examples | Editor Plugins | Documentation

Distinctive Features

• Self-hosted staged toolchain: real source layers for frontend, type analysis, borrow checking, backend, driver, interpreter, and loader live in-tree.
• Verification-native workflow: SSpec tests, the SPipe runner/docgen process, SDoctest executable docs, coverage, traceability checks, and generated spec docs are part of the toolchain rather than bolted on.
• MDSOC architecture support: virtual capsules, manifests, and architecture-aware repository structure are first-class concepts.
• Parser-friendly macro system: macro definitions, expansion, validation, and hygiene are compiler features rather than editor-hostile text substitution.
• Math-oriented syntax blocks: m{}, loss{}, and nograd{} are implemented syntax with parsing, evaluation, five rendering backends (text, debug, Unicode, LaTeX, Markdown), and editor integration (query/LSP hover, VSCode highlighting/preview, Neovim inline Unicode preview with conceal). The autograd path is complete for the promoted torch-backed C/LLVM scope.
• SDN-backed textual databases: tests, todos, dashboards, and other project metadata are stored through repo-native SDN data flows.
• Multiple execution paths: interpreter, loader, SMF/module loading, and native/LLVM-oriented compilation paths coexist in one system.
• Baremetal-oriented build and test plumbing: QEMU, semihosting, MMIO mailbox, remote baremetal flows, and adapter-backed hardware lanes (8 authoritative) are built into the repo story.
• Tooling-aware language rules: Tree-sitter integration, primitive-public-API linting, traceability tooling, and language statistics are part of the platform.
• Shared UI contract across supported surfaces: one HTTP-based test protocol (Protocol V1) with UITestClient drives both the web backend and the TUI-web proxy through a shared handle_test_request handler, verified by a cross-surface contract suite. Contract: doc/04_architecture/shared_ui_contract.md

Feature Status Highlights

Implemented and safe to advertise:

• SSpec tests, SPipe runner/docgen, SDoctest, coverage, traceability checks, and generated spec docs
• SPipe mock policy: system-test mock ban, HAL-only and custom pattern modes
• Self-hosted staged compiler, interpreter, and loader architecture
• MDSOC manifests and architecture-focused project structure
• Parser-friendly macros with validation and hygiene
• Tree-sitter outline/query tooling
• SDN-backed project, test, and todo databases
• Primitive-public-API linting and semantic wrapper/unit-type patterns
• Borrow-checking infrastructure
• Watch mode and auto-build support
• mmap-backed loader support and executable-memory plumbing
• Baremetal build/test plumbing and host-aware remote baremetal flows
• C/C++ bidirectional SFFI for the supported ABI subset: exports, imports, callback trampolines, layout verification, and round-trip proof tests

Implemented, but best described with qualifiers:

• LLVM full-family closure is complete for the declared public matrix: every llvm-lib and llvm backend row is now explicitly stable or unsupported, with no ambiguous middle states. rust-llvm remains a bootstrap-only seed path outside the public family claim
• Lean verification workflow is complete for the supported verification subset: deterministic Lean generation, proof artifact inventory, Lean/Lake checking, cache invalidation, and verification-state reporting. Contract: doc/04_architecture/lean_verification_contract.md. Report: doc/09_report/lean_verification_complete_2026-04-04.md
• GC and no-GC runtime families: 5 public families (common, nogc_sync_mut, nogc_async_mut, gc_async_mut, nogc_async_mut_noalloc) with compiler boundary enforcement, interpreter warnings, and target preset mapping. Support matrix: doc/04_architecture/runtime_family_support_matrix.md
• Shared UI contract across web backend and TUI-web proxy (Protocol V1): shared handler, structured error model, stable element IDs, cross-surface contract suite — but this is a shared test protocol, not a full unified UI rendering layer
• Remote baremetal execution has 8 authoritative lanes (3 stable + 5 host-aware including both GHDL semihost and mailbox simulation), but hardware-dependent lanes remain host- and board-aware rather than universally complete. Lane matrix: doc/08_tracking/lane_matrix.md

Implemented with bounded scope:

• m{} / loss{} / nograd{} are complete for the promoted torch-backed C/LLVM scope, including backward, detached-input failure, and nograd{} restore semantics. Other backends remain deferred
• AOP provides predicate-based pointcuts (execution, within, attr), deterministic before/after/around advice, compile-time weaving as the default backend, and scoped runtime interception. Support matrix: doc/05_design/aop_support_matrix.md
• VHDL backend compiles a documented hardware-oriented Simple subset to synthesizable VHDL-2008, validated through GHDL analysis/elaboration. Strict fail-fast on unsupported constructs. Two GHDL RV32 simulation lanes are operational: semihost (GDB-backed, ARM semihosting traps) and mailbox (debugger-independent, MMIO at 0x80FF0000 with ram_sentinel result collection). Support matrix: doc/04_architecture/vhdl_support_matrix.md. Mailbox protocol: doc/04_architecture/ghdl_rv32_mailbox_protocol.md

Implemented:

• Anti-dummy / anti-stub enforcement is active on the primary source and compiled CLI surfaces (simple lint, simple verify quality). All public-facing proof suites (SFFI, T32 hardware, compiler/runtime/system) now pass the gate. Remaining debt is only in deferred OS/GPU/experimental areas — all active surfaces are clean.

See doc/report/unique_features.md for the evidence-backed audit.

Runtime Families

Simple organizes its standard library into runtime families based on allocation, mutation, and concurrency requirements:

The compiler enforces family boundaries: importing a GC module from a no-GC context produces a diagnostic warning. Target presets (Baremetal, Hosted, EmbeddedWithHeap) automatically restrict module resolution to compatible families.

For advanced use: nogc_async_immut provides persistent data structures with lock-free concurrency.

See Runtime Family Support Matrix for full contracts, and Known Limitations for current caveats.

Quick Start

Installation

What you get:

• Complete Simple compiler and toolchain source
• Standard library and generated spec manuals
• Development tools, including MCP server, LSP, and debugger surfaces

Use a source checkout for the current beta. It also initializes the example and tooling submodules used by the docs and tests:

git clone --recurse-submodules https://github.com/ormastes/simple.git
cd simple
export PATH="$PWD/bin:$PATH"
simple --version

For an existing checkout:

git submodule sync --recursive
git submodule update --init --recursive

Note: Rust remains present as the bootstrap seed and host substrate. Product compiler, library, and tool work should stay in Simple source wherever the repo can express it; do not read "pure Simple" as "there is no Rust source in this checkout" today.

Source Footprint

Snapshot generated 2026-04-23 from existing tracked .spl, .rs, .c, .h, .s, .S, and .asm files. Blank lines and comment-only lines are excluded; examples/ code is included; vendored and third-party source is excluded.