regulus
Reggie, the experimental Gleam -> WASM compiler (mirror) reggie.desertthunder.dev
wasm compiler rust gleam
Star
Fork
Watch
regulus docs website reference supported-subset.md
7.3 kB · 262 lines
Markdown
at main

Supported subset #

Regulus currently compiles single-file Gleam programs and supported Gleam projects to WebAssembly through the full compiler pipeline:

Gleam source -> parse -> AST -> resolve -> type check -> IR -> Wasm

Summary #

Area Status
Single-file compilation Supported
Whole-project linked output Supported for project modules
Project discovery Partial
Type checking Broad subset
Managed runtime values Partial
Standard library Selected modules and intrinsics
JavaScript host ABI Browser, bundler, and Node.js
WASI ABI Incomplete
Memory management Bump allocation only

Supported today #

Inputs #

  • Compile one Gleam source file to .wasm.
  • Compile supported Gleam projects to one linked .wasm artifact.
  • Load gleam.toml and discover project modules.
  • Filter target-group declarations for Wasmtime, browser, bundler, Node.js, and WASI targets.
  • Emit optional debug dumps: AST, resolved AST, typed AST, IR, and WAT.
  • Emit generated .mjs JS host adapters for browser, bundler, and Node.js targets when Wasm output is requested.

Language surface #

Supported syntax includes:

  • modules, imports, constants, functions, and externals
  • type aliases, custom types, and opaque types
  • blocks, let, and let assert
  • literals, variables, calls, and captures
  • records, record updates, and field access
  • tuples and tuple access
  • lists
  • bit arrays
  • unary and binary operators
  • pipelines
  • use
  • anonymous functions
  • panic, todo, assert, and echo
  • case, guards, and nested patterns

Name resolution #

Supported:

  • local variables and shadowing
  • module references
  • qualified and unqualified imports
  • values, types, constructors, and fields
  • prelude type names
  • project-module visibility checks
  • private constructor checks
  • duplicate, unknown, and ambiguous name diagnostics

Type checking #

Supported:

  • scalar types
  • tuples, lists, records, and custom types
  • generic declarations and constructors
  • function types
  • typed parameters and return annotations
  • local bindings
  • direct, imported, and external calls
  • arity and argument checks
  • field and tuple access
  • record construction and updates
  • unary and binary operations
  • pipelines
  • anonymous functions
  • captures
  • use
  • case
  • guards and nested patterns
  • basic exhaustiveness checks
  • module interfaces
  • imported constructor patterns across project modules

Inference supports:

  • unannotated function parameters
  • eligible local values
  • anonymous-function parameters
  • generic functions
  • empty and generic lists
  • generic custom-type constructors
  • constructor patterns
  • polymorphic calls
  • imported generic functions

The checker reports ambiguous return types, recursive inferred types, and invalid generic arity.

WebAssembly output #

The backend emits deterministic Wasm and optional WAT for:

  • scalar values
  • managed heap values
  • locals
  • direct, external, and indirect calls
  • imports and exports
  • arithmetic and float operations
  • boolean operators
  • string concatenation
  • equality and comparisons
  • branches and guards
  • pattern tests and bindings
  • failure paths
  • memory operations
  • static data segments
  • selected runtime helpers
  • target-aware host imports
  • selected stdlib intrinsics
  • JS host ABI helpers for strings, structured readers, and opaque handles

ABI mapping:

Gleam type Wasm ABI
Int i64
Float f64
Bool i32
Nil no result
managed values i32 pointer

String exports with no parameters also receive:

  • <name>__data
  • <name>__len

JS host builds export stable runtime helpers for writing strings, reading strings and structured managed values, and wrapping opaque host handles.

Partially supported #

Project model #

Regulus can:

  • read gleam.toml
  • model package metadata
  • model dependency entries
  • discover modules under source roots
  • assign stable source file IDs
  • detect duplicate modules
  • report missing modules
  • load selected Hex and path dependency source modules
  • link supported dependency source modules into the final artifact
  • keep single-file loading available for tests and examples

Project builds compile discovered project modules into one linked Wasm output.

Standard library #

The stdlib registry models selected interfaces and lowering strategies for:

  • gleam/io
  • gleam/int
  • gleam/string
  • gleam/list
  • gleam/result
  • gleam/option
  • gleam/order
  • gleam/bool
  • gleam/dict
  • gleam/dynamic
  • gleam/dynamic/decode
  • gleam/float
  • gleam/function
  • gleam/bit_array

Some remaining modules are interface-only or unsupported beyond dependency metadata. This is not full stdlib source compilation.

Externals and targets #

General non-stdlib externals lower to Wasm imports when their ABI is supported. Bodyless @external declarations from project and dependency source lower through the selected target ABI when metadata is available.

The compiler:

  • preserves import module and function names
  • filters target-specific declarations
  • validates selected target modules
  • rejects unsupported ABI shapes before byte emission
  • emits generated JavaScript adapter glue for browser, bundler, and Node.js targets when Wasm output is requested
  • embeds import and export metadata for checked JS host calls
  • exposes standard browser and Node.js import helpers

The JavaScript adapter supports scalar and string imports, scalar and string export parameters, supported structured export returns, and opaque host-handle conversion. Structured JavaScript values passed into Gleam imports or exported function parameters are still deferred.

Not yet supported #

Projects and dependencies #

  • Compiling every valid Gleam project shape.
  • Broad dependency source compilation without subset limits.
  • Full stdlib source compilation.

Host interop #

  • Complete WASI adapters.
  • Writing arbitrary structured JavaScript values into Gleam.
  • Structured JS import parameters and returns.
  • Arbitrary managed-value wrappers for every import and export shape.

Runtime and memory management #

  • Freeing.
  • Garbage collection.
  • Reference counting.
  • Heap growth checks.

Known approximations #

Some implemented forms intentionally have smaller semantics than Gleam proper:

  • Residual raw Use IR is rejected before WAT assembly.
  • BitStringDeconstruct supports current segment matching, but not complete Gleam bit-string semantics.

Validation #

Tests cover:

  • parsing
  • AST construction
  • resolution
  • project loading
  • type checking
  • IR lowering
  • runtime layouts
  • WAT snapshots
  • Wasmtime execution
  • memory inspection
  • runtime helpers
  • host imports
  • export adapters
  • deterministic output
  • unsupported ABI diagnostics
  • unsupported target diagnostics