Regulus #

Regulus ("Reggie") is an experimental Gleam to WebAssembly compiler written in Rust.

The compiler uses tree-sitter to parse Gleam source, builds compiler-owned data structures, lowers a supported subset of Gleam to core IR, and emits .wasm with optional WAT output.

Gleam source
  -> tree-sitter syntax tree
  -> AST
  -> name resolution
  -> type checking
  -> core IR
  -> WebAssembly module
  -> .wasm / optional WAT

Status #

Regulus is not a full Gleam compiler yet. It can compile and run small programs using scalar values, managed values, pattern matching, closures, selected stdlib modules, and host imports. The compiler pipeline is intentionally visible so that each layer can be tested and explained.

At a glance #

Working today #

• Parse Gleam source with tree-sitter
• Build an AST with source spans
• Report diagnostics with source spans
• Resolve imports, modules, locals, types, constructors, and fields
• Type check scalar values, structured values, calls, branches, and patterns
• Infer generic functions, generic constructors, closures, and list types
• Lower the supported subset to core IR
• Emit deterministic .wasm
• Render optional WAT
• Run scalar and managed-value exports with Wasmtime
• Load gleam.toml and discover project modules
• Compile supported projects into linked Wasm output
• Load selected Hex and path dependency sources
• Lower supported externals to Wasm imports
• Validate target-aware host imports
• Emit deterministic browser, bundler, and Node.js .mjs adapters
• Emit optional AST, resolved, typed, IR, runtime, and ABI debug artifacts
• Render source diagnostics with snippets, labels, notes, and stable project ordering
• Keep normal CLI output concise, with --no-color and NO_COLOR support

Supported Gleam surface #

• Public and private functions
• Function annotations and inferred parameters
• Int, Float, Bool, String, and Nil
• Local bindings and structured patterns
• Direct, imported, and external calls
• case expressions, guards, and nested patterns
• Type aliases, custom types, opaque types, generics, and constructors
• Records, custom values, tuples, lists, and bit arrays
• Anonymous functions, captures, closures, pipelines, and use
• Selected stdlib modules and intrinsics

WebAssembly output #

• Function definitions, imports, and exports
• Scalar ABI values: i64, f64, and i32
• Managed values as guest-memory pointers
• Linear memory and static data segments
• Runtime objects for strings, records, lists, tuples, closures, and custom values
• Branches, comparisons, equality, pattern checks, and failure paths
• Selected runtime helpers and stdlib intrinsics
• Checked runtime helper fragments before final module output

Not yet implemented #

• Compile every valid Gleam project shape
• Compile broad dependency source modules without subset limits
• Compile the full published gleam_stdlib package without registry shims
• Provide complete browser, bundler, and Node.js host APIs beyond the current adapter subset
• Provide complete WASI adapters
• Add garbage collection or reference counting for long-lived managed values

For more detail, see the case-study book in docs/book and the user/development docs in docs/website.

Usage #

Build a Gleam project into one linked Wasm artifact:

cargo run -q -p compiler_cli -- build examples/scalar_project

Compile a single Gleam source file:

cargo run -q -p compiler_cli -- compile fixtures/e2e/public_id.gleam \
  -o .sandbox/public_id.wasm \
  --emit wasm,wat \
  --dump-dir .sandbox/dumps

--emit selects artifacts such as wasm, wat, ast, resolved, typed, and ir. The --dump-dir flag writes debug output for compiler stages. See CLI usage for project builds, targets, artifacts, and run.

Development #

Use the Rust workspace from the repository root:

cargo fmt
cargo test
cargo clippy --workspace --all-targets

To run examples & tests:

cargo test -p compiler_core
cargo test -p compiler_cli

cargo run -q -p compiler_cli -- compile fixtures/e2e/public_id.gleam \
  --out-dir .sandbox --emit wasm,wat
cargo run -q -p compiler_cli -- run fixtures/e2e/public_id.gleam
cargo run -q -p compiler_cli -- build examples/scalar_project \
  --target bundler --out-dir .sandbox

Documentation #

cd docs/website
pnpm install
pnpm docs:dev