Building and contributing¶
stone is a Rust workspace (edition 2024). The stone crate itself depends only on clap,
unless built with the opt-in self-update feature (for stone update) or fetch feature (for
downloading packages). The workspace also holds lsp/ (the stone-lsp language server), and
separate fuzz/ and bench/ crates.
Setup¶
git clone https://github.com/tarolling/stone
cd stone
cargo build
stone build assembles and links programs itself, so it needs no other tools, but the test
suite runs what it builds, so it needs x86-64 or arm64 Linux, arm64 macOS, or x86-64 Windows.
On Linux, to also run the other processor’s programs, and to compare the built-in assembler with
GNU’s, install qemu-user and the GNU binutils for both processors, which on an x86-64 Debian or Ubuntu machine is
sudo apt-get install qemu-user binutils-aarch64-linux-gnu (see testing).
Everyday commands¶
task |
command |
|---|---|
interpret a file |
|
compile a file |
|
check a file |
|
run every test |
|
run one test |
|
format |
|
lint |
|
build the docs |
see below |
Every build/ directory is gitignored scratch output, whether at the root or next to a program
stone build compiled. In a debug build, setting STONE_DEBUG=1 prints token
dumps, parser traces, and each function’s IR and register assignment to stderr:
STONE_DEBUG=1 cargo run -- build examples/basics.stn
What CI runs¶
Every push and pull request runs, and must pass, on x86-64 Linux:
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --features self-update,fetch -- -D warnings
cargo test
cargo test --features self-update --bin stone
cargo test --features fetch --lib --test cli
shellcheck install.sh scripts/*.sh
sh scripts/test-install.sh
sh scripts/test-bump-version.sh
sh scripts/test-changelog.sh
(cd editors/vscode && npm test)
with qemu-user, binutils-aarch64-linux-gnu, xvfb, and weston installed, so every golden
program is also cross-built for arm64 and run under qemu, the built-in assembler is compared with
GNU as for both processors, and gui windows open on Xvfb and a headless Weston. Other jobs run:
cargo testnatively on arm64 Linux (ubuntu-24.04-arm), withqemu-user,binutils-x86-64-linux-gnu,xvfb, andwestonfor the x86-64 cross pass and the windows.On x86-64 Windows (
windows-latest), both clippy runs,cargo test(so every golden program runs as a PE executable), theself-updateandfetchtests,scripts/test-install.ps1under both PowerShell 7 and Windows PowerShell, and the VS Code extension’snpm test.cargo testandcargo test --manifest-path fuzz/Cargo.tomlnatively on arm64 macOS (macos-15), so every golden program runs as a signed Mach-O.The fuzz program generator’s tests, then each crash target fuzzed for a minute on nightly.
Workflow¶
Practice test-driven development: write the test first, watch it fail for the expected reason, then make it pass. See Testing.
After every change, run
cargo fmtandcargo clippy, and fix what clippy reports.Follow the Style guide.
Building the docs¶
This site is built with Sphinx and the Furo theme from docs/:
python3 -m venv .venv
.venv/bin/pip install -r docs/requirements.txt
.venv/bin/sphinx-build -W -b html docs docs/_build/html
Then open docs/_build/html/index.html. -W turns warnings, such as a broken link or a missing
include, into errors, as the docs workflow does. Every push to main that touches the docs
publishes the site to GitHub Pages.
Tutorial programs live in docs/examples/ with their .out files and are pulled into pages with
literalinclude, so the golden tests run them under both backends. tests/docs.rs checks that
reference/builtins.md documents every builtin and reference/syntax.md lists every keyword.