From 6b50dafed23977155d4750e25e6e2ec87c810042 Mon Sep 17 00:00:00 2001 From: Owais Jamil Date: Thu, 11 Jun 2026 23:21:53 -0500 Subject: [PATCH] docs: update for CLI --- README.md | 27 +++++++---- docs/website/.vitepress/config.mts | 10 ++-- docs/website/guide/index.md | 3 +- docs/website/guide/{usage.md => usage/cli.md} | 48 ++++++++++++++----- docs/website/guide/usage/index.md | 28 +++++++++++ docs/website/index.md | 5 +- .../reference/cli-and-build-outputs.md | 8 ++-- docs/website/reference/supported-subset.md | 3 -- 8 files changed, 98 insertions(+), 34 deletions(-) rename docs/website/guide/{usage.md => usage/cli.md} (67%) create mode 100644 docs/website/guide/usage/index.md diff --git a/README.md b/README.md index 84484a1..3f78db6 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,8 @@ that each layer can be tested and explained. | Type checking | Broad subset | | Managed runtime values | Partial | | Standard library | Selected modules and intrinsics | -| Whole-project linked output | Not supported yet | -| Dependency source loading | Not supported yet | +| Whole-project linked output | Supported subset | +| Dependency source loading | Selected Hex and path packages | | Browser, Node.js, and WASI ABIs | Incomplete | ### Working today @@ -52,6 +52,8 @@ that each layer can be tested and explained. - [x] Render optional WAT - [x] Run scalar and managed-value exports in Wasmtime tests - [x] Load `gleam.toml` and discover project modules +- [x] Compile supported projects into linked Wasm output +- [x] Load selected Hex and path dependency sources - [x] Lower supported externals to Wasm imports - [x] Validate target-aware host imports @@ -81,8 +83,8 @@ that each layer can be tested and explained. ### Not yet implemented -- [ ] Compile full projects into linked Wasm output -- [ ] Fetch, load, and compile dependency source modules +- [ ] Compile every valid Gleam project shape +- [ ] Compile broad dependency source modules without subset limits - [ ] Compile the full Gleam standard library from source - [ ] Provide complete browser, bundler, and Node.js host ABIs - [ ] Provide complete WASI adapters @@ -94,18 +96,25 @@ For more detail, see the case-study book in ## Usage -Compile a Gleam source file to WebAssembly: +Build a Gleam project into one linked Wasm artifact: + +```sh +cargo run -q -p compiler_cli -- build examples/scalar_project +``` + +Compile a single Gleam source file: ```sh cargo run -q -p compiler_cli -- compile fixtures/e2e/public_id.gleam \ -o .sandbox/public_id.wasm \ - --wat \ + --emit wasm,wat \ --dump-dir .sandbox/dumps ``` -The `--wat` flag also writes WebAssembly text format. The `--dump-dir` flag -writes debug output for compiler stages such as AST, resolved names, typed -expressions, IR, and WAT. +`--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](./docs/website/guide/usage/cli.md) for project builds, targets, +artifacts, and `run`. ## Development diff --git a/docs/website/.vitepress/config.mts b/docs/website/.vitepress/config.mts index 7589f97..870c944 100644 --- a/docs/website/.vitepress/config.mts +++ b/docs/website/.vitepress/config.mts @@ -1,12 +1,16 @@ -import { defineConfig } from "vitepress"; +import { type DefaultTheme, defineConfig } from "vitepress"; -const sidebar = [ +const sidebar: DefaultTheme.Config["sidebar"] = [ { text: "Guide", items: [ { text: "Overview", link: "/guide/" }, { text: "Installation", link: "/guide/installation" }, - { text: "Usage", link: "/guide/usage" }, + { + text: "Usage", + link: "/guide/usage/", + items: [{ text: "CLI", link: "/guide/usage/cli" }], + }, { text: "Examples", link: "/guide/examples" }, ], }, diff --git a/docs/website/guide/index.md b/docs/website/guide/index.md index ac84ad3..c6ebc78 100644 --- a/docs/website/guide/index.md +++ b/docs/website/guide/index.md @@ -8,6 +8,7 @@ Regulus supports today. ## Common paths - Install or run the CLI locally: [Installation](./installation.md) -- Compile Gleam to Wasm: [Usage](./usage.md) +- Compile Gleam to Wasm: [Usage](./usage/) +- Review CLI commands and flags: [CLI](./usage/cli.md) - Try checked fixtures and examples: [Examples](./examples.md) - Check language support: [Supported subset](../reference/supported-subset.md) diff --git a/docs/website/guide/usage.md b/docs/website/guide/usage/cli.md similarity index 67% rename from docs/website/guide/usage.md rename to docs/website/guide/usage/cli.md index 9d3598f..d3d7513 100644 --- a/docs/website/guide/usage.md +++ b/docs/website/guide/usage/cli.md @@ -1,7 +1,17 @@ -# Usage +# CLI -Regulus provides two compiler entry points: project builds and single-file -compilation. +The CLI binary is named `gleam-wasm`. When running from a checkout, prefix +commands with Cargo: + +```sh +cargo run -q -p compiler_cli -- build +``` + +Installed binaries can be run directly: + +```sh +gleam-wasm build +``` ## Build a project @@ -95,25 +105,41 @@ gleam-wasm compile path/to/module.gleam --target wasmtime Supported target values are `wasmtime`, `browser`, and `wasi`. Project builds use the target from `gleam.toml` when `--target` is not provided. -## Artifacts and debug dumps +## Artifacts `--emit` selects emitted artifact kinds: ```sh gleam-wasm build examples/scalar_project --emit wasm,wat +gleam-wasm build examples/scalar_project --emit wat,ast,resolved,typed,ir ``` -`wasm` is the normal binary output. `wat` writes WebAssembly text next to the -Wasm output, or into `--out-dir` when that option is used. +Supported emit values 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. | -`--dump-dir` writes compiler debug dumps for contributor inspection: +`wasm` is the default. `wat` writes next to the Wasm output, or into +`--out-dir` when that option is used. Debug emit values write deterministic +files beside the selected output path unless `--dump-dir` is set. + +Use `--dump-dir` to write all compiler debug dumps into a separate directory: ```sh gleam-wasm build examples/multi_module_project --dump-dir build/dumps ``` Single-file dumps include AST, resolved AST, typed output, IR, and WAT. Project -build dumps currently include linked IR and WAT. +dumps include per-module AST, resolved AST, typed output, linked IR, and WAT. + +If compilation fails, Regulus does not write the final Wasm artifact. Debug +artifacts are only written when the requested compiler phase completes. ## List project modules @@ -125,6 +151,6 @@ gleam-wasm list examples/multi_module_project ## Current limitations -Project compilation is still growing. Full Hex resolution, broad dependency -language coverage, general external functions, and richer host ABI adapters are -tracked in `docs/internal`. +Project compilation is still growing. Broad Hex dependency language coverage, +general external functions, and richer host ABI adapters are tracked in +`docs/internal`. diff --git a/docs/website/guide/usage/index.md b/docs/website/guide/usage/index.md new file mode 100644 index 0000000..710351a --- /dev/null +++ b/docs/website/guide/usage/index.md @@ -0,0 +1,28 @@ +# Usage + +Regulus has two compiler paths: + +- `build` compiles a Gleam project from `gleam.toml` into one linked Wasm + artifact. +- `compile` compiles one `.gleam` file for tests, fixtures, and small examples. + +Most users should start with `build`. Use `compile` when you want the smallest +possible compiler input or when you are debugging one source file. + +## Common commands + +```sh +gleam-wasm build +gleam-wasm build path/to/project +gleam-wasm compile path/to/module.gleam +gleam-wasm run path/to/module.gleam +``` + +`run` is a single-file helper that compiles a module in memory and executes one +exported function with Wasmtime. + +## Learn more + +- [CLI commands and flags](./cli.md) +- [Examples](../examples.md) +- [Supported subset](../../reference/supported-subset.md) diff --git a/docs/website/index.md b/docs/website/index.md index 0c5f9ea..a149d48 100644 --- a/docs/website/index.md +++ b/docs/website/index.md @@ -14,9 +14,8 @@ hero: features: - title: Use the compiler - details: Build & compile your Gleam projects - compiler dumps. - link: /guide/usage + details: Build projects, compile files, run exports, and inspect dumps. + link: /guide/usage/ - title: Check support details: See the supported language subset, runtime shape, and current limitations. diff --git a/docs/website/reference/cli-and-build-outputs.md b/docs/website/reference/cli-and-build-outputs.md index 4b15bb4..0aa6339 100644 --- a/docs/website/reference/cli-and-build-outputs.md +++ b/docs/website/reference/cli-and-build-outputs.md @@ -12,8 +12,8 @@ that project root, and a `gleam.toml` argument builds the owning project. The command writes `build/.wasm` by default. `--output` writes the final Wasm artifact to an exact path. `--out-dir` writes compiler-named artifacts such as `.wasm` and `.wat` into the given -directory. `--emit` accepts comma-separated artifact kinds, including `wasm` -and `wat`. +directory. `--emit` accepts comma-separated artifact kinds: `wasm`, `wat`, +`ast`, `resolved`, `typed`, and `ir`. `gleam-wasm compile ` compiles one Gleam source file. It runs the same single-file pipeline used by tests: @@ -39,7 +39,7 @@ contract: - `examples/browser_scalar` builds a browser-target artifact with JS glue. - `examples/diagnostics/duplicate_modules` documents a failing project shape. -See `docs/website/guide/usage.md` for user-facing commands. +See `docs/website/guide/usage/cli.md` for user-facing commands. ## Targets @@ -54,7 +54,7 @@ and configures backend host import validation. `--dump-dir ` writes deterministic debug files. Single-file compilation writes AST, resolved AST, typed output, IR, and WAT dumps. Project builds write -linked IR and WAT dumps today. +per-module AST, resolved AST, typed output, linked IR, and WAT dumps. These dumps are for contributor inspection. Normal CLI output stays focused on the final artifact path, optional WAT path, and diagnostics. diff --git a/docs/website/reference/supported-subset.md b/docs/website/reference/supported-subset.md index 6c7d032..9545e00 100644 --- a/docs/website/reference/supported-subset.md +++ b/docs/website/reference/supported-subset.md @@ -7,9 +7,6 @@ full compiler pipeline: Gleam source -> parse -> AST -> resolve -> type check -> IR -> Wasm ``` -This document describes the supported source language, compiler behavior, and -known gaps. - ## Summary | Area | Status | -- 2.51.2