Project compilation and dependencies

Use reggie build for Gleam projects with a gleam.toml file. Project builds compile supported project modules and selected dependency source modules into one linked WebAssembly artifact.

reggie build
reggie build examples/scalar_project
reggie build examples/scalar_project/gleam.toml

With no project argument, Regulus builds the current directory. A directory argument builds that project root. A gleam.toml argument builds the project that owns that manifest.

What build does

Project builds compile every selected module in dependency order:

load project -> compile modules -> link modules -> emit Wasm

The final output is one linked Wasm module for the selected target. Per-module views are available as debug dumps. Same-project calls are linked inside the Wasm module rather than emitted as host imports.

Project inputs

Regulus reads project metadata from gleam.toml, including:

• package name and version
• source roots
• target selection
• dependency entries
• module names and source paths

The loader discovers modules under the configured source roots and reports project-shape diagnostics before later compiler phases run.

Project-shape diagnostics include:

• missing project files
• unreadable source files
• duplicate module names
• unknown imported modules
• unsupported project configuration

Dependencies

Regulus supports selected Hex and path dependency source loading. Dependency modules are compiled through the same compiler pipeline as project modules when they fit the supported compiler subset.

Hex package metadata and tarballs are fetched from the public Hex repository when needed. Downloaded tarballs are cached under the user Regulus store, and packages are extracted into the project-local build/packages/ directory.

Path dependencies are loaded from their declared paths without network access.

Project builds print stable dependency progress to stderr:

Resolving dependencies
Using cached gleam_stdlib 0.50.0
Extracting gleam_stdlib 0.50.0

Use --verbose to include local paths, cache paths, source paths, URLs, and checksums where available.

Targets

Project builds accept the same target names as single-file compilation:

reggie build --target wasmtime
reggie build --target browser
reggie build --target bundler
reggie build --target nodejs
reggie build --target wasi

When --target is omitted, project builds use the target from gleam.toml.

Target selection picks the declarations for the requested runtime before name resolution and checks that host imports are valid for that target.

Artifacts

By default, project builds write:

build/<package>.wasm

Use --output to choose the exact final Wasm path:

reggie build examples/scalar_project --output out/app.wasm

Use --out-dir to write compiler-named artifacts into a directory:

reggie build examples/scalar_project --out-dir build/examples

--emit selects artifact kinds:

reggie build examples/scalar_project --emit wasm,wat
reggie build examples/scalar_project --emit wat,ast,resolved,typed,ir
reggie build examples/scalar_project --emit runtime,abi

Supported project artifact kinds are:

Value	Output
wasm	Final WebAssembly binary.
wat	WebAssembly text for the linked module.
ast	Per-module AST debug dumps.
resolved	Per-module resolved AST debug dumps.
typed	Per-module typed-module debug dumps.
ir	Linked IR debug dump.
runtime	Runtime layout and object tag summary.
abi	Import/export ABI boundary summary.

Use --dump-dir to write debug dumps into a separate directory. If compilation fails, Regulus does not write the final Wasm artifact. Debug artifacts are only written when the requested compiler phase completes.

For the bundler target, Regulus writes a deterministic .mjs adapter next to the .wasm artifact when Wasm output is requested.

Inspect modules

Use list to inspect discovered modules without compiling artifacts:

reggie list examples/multi_module_project

Current limits

Project compilation is supported for the current compiler subset. These areas are still incomplete:

• compiling every valid Gleam project shape
• broad dependency source compilation without subset limits
• bodyless @external declarations from project and dependency source
• full standard-library source compilation
• complete browser, Node.js, and WASI host adapters
• automatic conversion for every managed host import and export shape