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

cargo run -- run examples/basics.stn

compile a file

cargo run -- build examples/basics.stn (writes examples/build/basics)

check a file

cargo run -- check examples/basics.stn

run every test

cargo test

run one test

cargo test simple_functions

format

cargo fmt

lint

cargo clippy --all-targets

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 test natively on arm64 Linux (ubuntu-24.04-arm), with qemu-user, binutils-x86-64-linux-gnu, xvfb, and weston for 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), the self-update and fetch tests, scripts/test-install.ps1 under both PowerShell 7 and Windows PowerShell, and the VS Code extension’s npm test.

  • cargo test and cargo test --manifest-path fuzz/Cargo.toml natively 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 fmt and cargo 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.