fader_master/docs/build.md

4.4 KiB

Build prerequisites

fader_master targets Linux and uses Rust 2024. Rust 1.88.0 is the selected minimum supported Rust version (MSRV) and the repository-pinned development toolchain. rustup reads rust-toolchain.toml and installs the required rustfmt, Clippy, and LLVM tools components.

The default build includes the PulseAudio protocol adapter and links to libpulse. MPRIS is enabled by default and also links to libdbus-1. On a Debian-family Linux system, install:

sudo apt-get install build-essential pkg-config libasound2-dev libpulse-dev libudev-dev libdbus-1-dev dbus
rustup toolchain install 1.88.0 \
    --profile minimal \
    --component rustfmt \
    --component clippy \
    --component llvm-tools-preview

On Arch Linux with PipeWire, install the client library, build tools, and the PulseAudio-compatible PipeWire service:

sudo pacman -S --needed base-devel pkgconf alsa-lib libpulse systemd-libs dbus pipewire-audio pipewire-pulse wireplumber
pactl info

The executable's mpris feature can be omitted with cargo build -p fader_master --no-default-features; this disables only MPRIS, not the existing audio/MIDI backends. MPRIS runtime requires access to the user's session bus, not playerctl. CI native runners need libdbus development files too. The hardware-free protocol fixture runs with:

dbus-run-session -- cargo test -p fader_master private_bus -- --ignored

The Server Name reported by pactl info should contain PulseAudio (on PipeWire ...). Arch packages the headers with libpulse, rather than in a separate development package. The application communicates with PipeWire through pipewire-pulse; it does not require the standalone PulseAudio server.

The Pulse adapter works with PulseAudio and PipeWire's pipewire-pulse compatibility service. MIDI input uses ALSA's sequencer API through midir, and Linux identity enrichment uses libudev. PipeWire does not replace the alsa-lib build dependency. To exclude native audio and MIDI dependencies, build the portable library/TUI subset used on FreeBSD and explicitly omit the Linux executable:

cargo build --locked --no-default-features \
  -p fader-core -p fader-config -p midi -p volume_lib -p tui

--workspace --no-default-features alone is not a native-free build: the executable's dependencies still enable the native MIDI and Pulse features.

The normal Linux release build produces all three entry points:

cargo build --locked --workspace --release --all-features
./target/release/fader_master
# Or run separately, in two terminals:
./target/release/fader_master_server
./target/release/fader_master_client

Restart both server and client when upgrading, including an external server that the all-in-one launcher might reuse. First-run configuration and MIDI setup are described in Advanced configuration.

Future native PipeWire and ALSA mixer adapters will add their own feature-gated development packages. The MIDI crate can also be checked without its native transport and identity discovery while retaining byte decoding and routing:

cargo check -p midi --no-default-features --locked

From a fresh checkout, use the tracked lockfile for reproducible resolution:

cargo build --workspace --locked
cargo test --workspace --all-targets --all-features --locked

Verify the MSRV explicitly without allowing rust-toolchain.toml to select a newer installed toolchain:

cargo +1.88.0 check --workspace --all-targets --all-features --locked
cargo +1.88.0 test --workspace --all-targets --all-features --locked

Jenkins backend modes

The current Jenkins worker is FreeBSD, so the job parameter ENABLE_NATIVE_BACKENDS defaults to false. In that mode CI checks, tests, documents, lints, and release-builds the portable fader-core, fader-config, midi, volume_lib, and tui packages with native features disabled. It does not build or test the Linux-only fader_master executable, MIDI transport, udev identity adapter, or Pulse adapter, and it publishes unavailable coverage rather than presenting partial coverage as the workspace measurement.

After Jenkins moves to a provisioned Linux worker, enable ENABLE_NATIVE_BACKENDS on the build (and change its default only after that build passes). This restores the complete default/no-default/all-feature workspace matrix, workspace coverage, doctests, strict documentation and Clippy, and the release executable assertion without changing the pipeline.