Skip to content

Building

Jump to bottom
Rodrigo Agurto edited this page May 30, 2026 · 1 revision

Building

Requirements

  • C++20 toolchain: clang 14+ or gcc 11+
  • Rust 1.85+ stable
  • git (for cloning the Verovio submodule)
  • POSIX userland (Linux or macOS — Windows is permanently out of scope)

Standard build

git clone --recurse-submodules https://github.com/ro-ag/verovio-rs
cd verovio-rs
cargo test

If you forgot --recurse-submodules:

git submodule update --init --recursive

First clean build takes ~6 minutes (295 C++ source files in -O0 + debug info). Subsequent incremental builds are seconds.

NixOS

The repo ships a shell.nix with the full toolchain plus sccache (compiler cache) and mold (fast linker):

nix-shell
cargo test

A clean rebuild after cargo clean, on a warm sccache, completes in under a minute.

Live audio on NixOS

The live-audio feature needs alsa-lib and pkg-config for cpal:

nix-shell -p alsa-lib pkg-config
cargo run --release --features live-audio \
    --example live_playback -- soundfont.sf2

Sanitizers

The sanitize (ASan + UBSan) and sanitize-thread (TSan) features instrument the C++ build:

RUSTFLAGS="-C linker=clang -C link-arg=-fuse-ld=lld" \
ASAN_OPTIONS="halt_on_error=1:abort_on_error=1:detect_leaks=0" \
    cargo test --features verovio/sanitize
RUSTFLAGS="-C linker=clang -C link-arg=-fuse-ld=lld" \
    cargo test --features verovio/sanitize-thread --test concurrency

See Concurrency for what TSan reports and why we leave those races unmitigated.

On stable Rust, rust-lld doesn't translate -fsanitize=… into the matching runtime link. The RUSTFLAGS above forces clang as the linker driver so the right libsanitizer runtime gets linked.

build.rs panics if both sanitize and sanitize-thread are enabled together (the runtimes can't coexist).

CI matrix

Matrix:

Job Platform What it runs
test (ubuntu-latest) ubuntu-latest default cargo test
test (macos-latest) macos-latest default cargo test
test (nix-shell) ubuntu-latest cargo test inside nix-shell
sanitize ubuntu-latest cargo test --features verovio/sanitize

CI uses sccache backed by the GitHub Actions cache for cross-job compile caching. If you see "cache storage failed to read" from sccache, that's a transient GH Actions cache outage — rerun the job.

Common build problems

pkg-config exited with status code 1: alsa

You enabled live-audio without alsa-lib available. On NixOS: nix-shell -p alsa-lib pkg-config. On Debian/Ubuntu: apt install libasound2-dev pkg-config.

libclang not found

Required by bindgen (used only as a fallback for cxx). On NixOS this isn't on a standard FHS path — shell.nix sets LIBCLANG_PATH for you. Outside the shell, install clang and ensure libclang.so is discoverable, or set LIBCLANG_PATH manually.

Submodule is empty after clone

You cloned without --recurse-submodules and didn't run git submodule update --init. The Verovio source tree at crates/verovio-sys/vendor/verovio/ will be empty and the build will fail to find headers.

Clone this wiki locally