Building from source

Everything goes through Nix, so a checkout needs nothing else installed.

git clone https://github.com/jmoo/drawbar && cd drawbar
nix run .#drawbar                 # the desktop app
nix run .#drawbar-web             # the browser build, served with this guide beside it
nix run .#nord-cli -- --help      # the nord command
nix build .#site                  # drawbar.app's layout, from this checkout
nix build .#docs                  # this guide

nix run .#drawbar-web serves on http://127.0.0.1:8080/. Set DRAWBAR_PORT for another port. scripts/site.bash assembles the tree drawbar.app deploys: the layout of nix build .#site, with the app taken from the latest drawbar-v* tag.

Checks

nix flake check runs the formatting check, Clippy and rustdoc with warnings denied, and the tests of scripts/bump.bash. nix build .#nord.all builds every crate with its tests, the cross targets, the browser build and this guide. CI runs both. nix build .#<crate> builds and tests one crate. nix fmt formats everything. Testing describes the suites, and Contributing the house rules.

Generated files

Two files are generated by scripts, which run in the nix develop shell. The drawbar suite fails until the matching script is re-run.

scripts/licenses.bash regenerates the license notices drawbar shows for its Rust crates. Re-run it when the registry packages drawbar reaches in Cargo.lock change.
scripts/glyphs.py regenerates drawbar-glyphs.ttf, which draws the characters drawbar’s text uses that no other bundled font has. Change a glyph in the script’s table and re-run it, or add one when the text uses a character no face draws.

Build by hand

Cargo needs stable Rust, and on Linux the ALSA headers and pkg-config. nix develop opens a shell with all of it. Run Cargo from crates/, because crates/.cargo/config.toml carries a flag the wasm build needs, and Cargo finds it by walking up from the working directory.

cd crates
cargo run -p drawbar
cargo run -p nord-cli -- --help
cargo test --workspace

The browser build

The browser build also needs the wasm32-unknown-unknown target and wasm-bindgen-cli at the wasm-bindgen version in Cargo.lock. nix build .#drawbar-web does all of this in one step. By hand, from crates/:

cargo build -p drawbar --lib --target wasm32-unknown-unknown --release
wasm-bindgen --target web --out-dir drawbar/pkg \
  target/wasm32-unknown-unknown/release/drawbar.wasm
cd drawbar && python3 -m http.server 8000

--lib is required. The crate also has a binary target of the same name, and if that one wins, the wasm module exports nothing. nix run --inputs-from .. nixpkgs#wasm-bindgen-cli -- in place of wasm-bindgen takes the matching version from the flake’s pinned nixpkgs.

Serve over http://localhost, which counts as a secure context. WebUSB, the module import and the library’s storage all fail from file://. The page loads library-writer.js, the worker that writes the library, from beside itself; serving crates/drawbar serves it too. This plain server has no guide beside the app, so Help ▸ User guide finds nothing there. nix run .#drawbar-web serves both.

nix build .#drawbar-web also writes the version and the module’s byte count into the page. Built by hand it has neither, so the loading screen shows no version and measures the download against the server’s Content-Length, or not at all when the server compresses it.

Checks by hand

The checks need taplo, shfmt, shellcheck and nixfmt beside the Rust toolchain, with rustfmt and Clippy. CI uses the versions Nix pins, so a different version can still disagree. A pull request labeled autofix gets CI’s formatting committed to it.

Format from the repository root. The file lists come from Git, so git add new files first.

cargo fmt --manifest-path crates/Cargo.toml --all
git ls-files -z '*.toml' | xargs -0 taplo format --option array_auto_collapse=false
git ls-files -z '*.sh' '*.bash' | xargs -0 shfmt -w -i 2 -s
git ls-files -z '*.sh' '*.bash' | xargs -0 shellcheck --external-sources
git ls-files -z '*.nix' | xargs -0 nixfmt

Lint and test from crates/. The features are each crate’s testFeatures, and Clippy adds corpus so the corpus suites compile.

cargo clippy --locked --workspace --all-targets --features nord-format/bundle,nord-format/corpus,nord-usb/blocking,nord-usb/replay,nord-usb/corpus -- --deny warnings
RUSTDOCFLAGS="--deny warnings" cargo doc --locked --workspace --no-deps
cargo test --locked --workspace --features nord-format/bundle,nord-usb/blocking,nord-usb/replay