Building from a clean clone
A fresh clone of this repository will not run until you build it. The static pages are committed, but the WebAssembly module is not, because the build tool generates a gitignore that excludes its own output. Opening the page before building gives you a calculator whose buttons do nothing, because the module the page imports is missing. Two commands fix that. This page lists what you need installed, the build itself, and how to serve the result.
What you need installed
- Rust, with cargo. The crate declares the 2021 edition.
- wasm-pack, which drives the WebAssembly build. The build script installs it with cargo if it is not already on the path.
- Go, only if you intend to regenerate the static pages or run the content guards. The committed HTML means the site publishes without it.
Nothing else. There is no package manager step on the JavaScript side, no node_modules directory and no bundler, because the build emits a plain ES module that the page imports directly.
The build
The one command that matters is the WebAssembly build. It compiles the crate for the wasm32 target and writes the module and its JavaScript loader into a directory the page imports from.
cargo test— run the engine's unit tests first, so a broken build fails before it is packaged.wasm-pack build --target web— produce the module and loader. This is the step without which nothing works../build.sh— does both of the above, then regenerates the static pages and runs the content guards if Go is available, and finally produces a coverage report if the coverage tool is installed.
The build script is safe to run without Go or the coverage tool; it reports what it skipped rather than failing. The build output page describes the seven files the WebAssembly step produces.
Serving it
The page loads its module with an ES module import, and browsers refuse module imports over the file protocol, so opening the HTML directly from disk will not work. It has to come from an HTTP server. The repository includes a small static server for this, written in Go, which serves the repository root, redirects a directory path without a trailing slash, sends the correct content type for WebAssembly, and marks every response uncacheable so an edit is never hidden by a stale copy.
Any static server will do instead, with one requirement: it must send the WebAssembly binary as application/wasm. A server that does not will still work, because the generated loader falls back to a slower path, but it will warn in the browser console every time.
Checking your work
The repository has one gate that runs everything, offline, with no network access at all. It runs the engine's unit tests, the Go test suites for the page generator and the content guard, a check that the committed HTML still matches what the generator produces, and the guard itself. Details of what each suite covers are on the testing page.
Questions and answers
Why do the calculator buttons do nothing after I clone the repository?
Because the WebAssembly module is not committed. The build tool generates a gitignore excluding its own output, so you have to run wasm-pack build --target web before the page has anything to import.
Can I open the HTML file directly from disk?
No. The page loads its module with an ES module import, which browsers refuse over the file protocol. Serve it over HTTP instead; the repository includes a small Go static server for this.
Do I need Node or npm to build this?
No. There is no JavaScript build step, no bundler and no node_modules directory. You need Rust and wasm-pack, plus Go only if you want to regenerate the static pages or run the content guards.
What is the minimum command to get a working calculator?
wasm-pack build --target web, then serve the repository root over HTTP. Everything else in the build script is tests, page generation and coverage.