Burroughs user documentation¶

Work in progress

This page is a draft. It describes Burroughs as of its latest release and may change. Where it disagrees with the engine's own documentation or CHANGELOG, those win.

Written against v0.12.0 (tagged 2026-10-28). Every example program, expected output and CLI transcript on these pages is included from this site's examples/ directory, which the site's CI runs against the latest Burroughs release before anything publishes. A code block that is not run that way is labelled as a fragment.

Burroughs is a WebAssembly runtime written in pure Go: no cgo, and no dependency outside the Go standard library. Its module path is github.com/scttfrdmn/burroughs. It is language-directed: its host contract (threads, preemption, the memory model at host boundaries, stacks, the WASI 0.3 event loop) is designed around what the Go runtime needs from a host. Any guest that conforms to the spec should run correctly, and the upstream spec test suite is how that is checked. Where a design choice has to favour one kind of guest, it favours Go.

The pipeline is decoder, then internal form, then validator, then interpreter. There is no compiler, and none is on the published roadmap.

Status at v0.12.0, in one screen¶

Area	State
Core Wasm (MVP + Wasm 2.0 features)	Runs. The spec suite's core board has 0 failures (see Conformance).
SIMD, relaxed SIMD	On by default.
Extended constant expressions, tail calls, multi-memory, memory64	On by default since `v0.12.0`, each with an environment rollback (`BURROUGHS_<GATE>=0`; see Gates).
Threads (shared memory, atomics, wait/notify)	On by default, on every platform (the release claim covers linux and darwin; the default itself does not check the OS). A `wasip1` guest starts its own threads through the `"burroughs" "spawn"` import (#1122). Core `Instantiate` starts no second thread, and host-started threads are not built.
GC, exception handling	Gated off. The public API cannot turn them on.
WASI preview 1 (`wasip1` commands)	Public path: `WASIP1Config.Run` and `burroughs run`.
Component model, async ABI, component-model threads	On by default. Values that cross the boundary: `u32`, `string`, `list`, `record`.
WASI 0.2 host for components	Partial: `wasi:cli` and `wasi:io` streams, part of each. Filesystem, clocks, random, sockets and http are absent.
Platforms	64-bit Linux and macOS are built and tested. Windows runs the tests in CI as a measurement, not a gate, and is unsupported.
Stack switching (contract §7)	Not started.

Details and issue links are in Known limits and status.

The experimental apparatus¶

Burroughs' thesis is that a Wasm engine can be designed to the Go runtime's specification. Three things together test it:

Burroughs, the engine;
the Phase 4 Go fork, a modified Go toolchain whose wasip1 port starts real threads through Burroughs' spawn import. Stock Go's wasip1 port is single-threaded. The fork is not published;
the Go-runtime torture suite (#406): Go programs built with the fork, each of whose observable results must match the same program built with stock Go.

The v0.12.0 threads witness is one of the apparatus's readings, with what it does and does not show.

How these docs are organised¶

Getting started: install, build the CLI, and run your first module.
CLI reference: burroughs run, inspect and version, every flag, the value syntax, how a file is routed, and the exit codes.
Embedding guide: the Go API, type by type, with what each call does and returns.
Tutorials, each ending in a run:
Call an exported function from WAT
Run a Go program built for WASI preview 1
Load a component and call typed exports
Traps, refusals, gates and the environment switches
Concepts: the contract in plain terms, gates, conformance, and the trap / refused / declined / unsupported / gated vocabulary.
Known limits and status: what is and is not supported, with issue numbers.
Roadmap: what is decided, without dates. Subject to change.

The examples¶

Every example program lives in this site's repository under examples/. Each is its own Go module whose go.mod requires github.com/scttfrdmn/burroughs v0.12.0 from the Go module proxy, with no local replace. Before the site publishes, its CI (scripts/run-examples.sh) resolves the latest Burroughs release tag, points each example at it, runs it, and compares what it prints with the committed expected output; any difference fails the build. The component fixtures that tutorial 3 and the CLI transcripts use are fetched from the engine repository's internal/component/testdata/ at that tag, and the wasip1 Go guest is built with the stock toolchain (GOOS=wasip1 GOARCH=wasm).

Directory	What it shows
`examples/embed-core/`	`Instantiate`, `Call`, multiple results, argument checking, traps, `Global`, `ParseValue`
`examples/refusals/`	one module per error classification, and `BURROUGHS_THREADS=0`
`examples/wasip1/`	a Go `wasip1` guest (`guest/`) and a Go host that runs it (`host/`)
`examples/component/`	`LoadComponent`, record, string and list values, the trap lock, `Close`, `ComponentConfig.Run`
`examples/describe/`	tutorial 4's error-branching template, run over one error of each kind
`examples/cli/`	the `burroughs` CLI sessions whose transcripts these pages show, run with the CLI built at the tag

Where the authoritative text lives¶

These pages are a reader's guide. When they disagree with the source, the source wins:

the package documentation (go doc -all github.com/scttfrdmn/burroughs);
the repository's README.md and CHANGELOG.md (each release since v0.7.0 has a Known limits list);
docs/burroughs-contract-v0.1.md, the normative host contract;
docs/decisions/, the decision records (ADRs) cited throughout, each with a Status: line.

Project state (issues, milestones, the roadmap) is kept on GitHub at scttfrdmn/burroughs, not in files.