EffectCraft: An open-source motion graphics and compositing tool written by scratch in pure Rust
ci: name the missing ALSA package instead of dying at link time
Kaedo17ac0188f315b5
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex dfa28c9f0..16c969a72 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -7,6 +7,20 @@ work apply to everyone, people and AI agents alike, and they are not negotiable.You need [Rust](https://rustup.rs/) 1.95 or newer.+On Linux the desktop app plays preview sound through `cpal`, so the build also needs the ALSA+development headers. Without them `alsa-sys` fails at link time with an unrelated-looking error;+`cargo xtask ci` checks for them up front and names the package:++```sh+sudo dnf install alsa-lib-devel # Fedora+sudo apt install libasound2-dev # Debian / Ubuntu+sudo pacman -S alsa-lib # Arch+```++If you cannot install the package, point `PKG_CONFIG_PATH` at a directory holding an `alsa.pc`+whose `Libs` line names your system's `libasound` (usually `libasound.so.2`); every CI run needs+that variable set.+```shcargo run -p effectcraft -- --demo # the desktop app, with the demo projectcargo test --workspacediff --git a/xtask/src/main.rs b/xtask/src/main.rsindex da8026d78..e5c26cd2c 100644--- a/xtask/src/main.rs+++ b/xtask/src/main.rs@@ -407,6 +407,40 @@ fn serve_dir(dir: &std::path::Path, port: u16) -> Result<(), String> {Ok(())}+/// The guidance printed when the ALSA development package is missing. Split out so the test can+/// check the package names without needing a machine that is actually missing them.+fn audio_backend_hint(found: bool) -> Result<(), String> {+ if found {+ return Ok(());+ }+ Err("Linux audio needs the ALSA development package, and pkg-config cannot find it.\n\+ The desktop app plays preview sound through cpal, whose alsa-sys dependency asks\n\+ pkg-config for `alsa`; without the package the build dies minutes later with an\n\+ unrelated-looking linker error.\n\+ \n\+ Fedora: sudo dnf install alsa-lib-devel\n\+ Debian/Ubuntu: sudo apt install libasound2-dev\n\+ Arch: sudo pacman -S alsa-lib\n\+ \n\+ Install one of those and run `cargo xtask ci` again. If you cannot install it, point\n\+ PKG_CONFIG_PATH at a directory holding an `alsa.pc` whose Libs line names your system's\n\+ libasound (usually `libasound.so.2`); every CI run will need that variable set."+ .into())+}++/// `cargo xtask ci` builds the desktop app on the host, so on Linux it needs ALSA headers to be+/// present. Checking here turns a late, confusing link error into one line naming the package.+#[cfg(target_os = "linux")]+fn audio_backend() -> Result<(), String> {+ let found = Command::new("pkg-config").args(["--exists", "alsa"]).status().map(|s| s.success()).unwrap_or(false);+ audio_backend_hint(found)+}++#[cfg(not(target_os = "linux"))]+fn audio_backend() -> Result<(), String> {+ Ok(())+}+/// Lib, bin and integration tests (examples aren't linked; clippy checked them), then doctests,/// which nextest doesn't run.///@@ -438,7 +472,8 @@ type Stage = fn() -> Result<(), String>;/// Every stage runs even when an earlier one fails, so one run reports all the problems.fn ci() -> Result<(), String> {- let stages: [(&str, Stage); 7] = [+ let stages: [(&str, Stage); 8] = [+ ("audio backend", audio_backend),("fmt", || run(Command::new(env!("CARGO")).args(["fmt", "--check"]))),("clippy", || run(Command::new(env!("CARGO")).args(["clippy", "--workspace", "--all-targets", "--", "-D", "warnings"]))),("tests", tests),@@ -484,3 +519,21 @@ fn main() -> ExitCode {pub fn root() -> std::path::PathBuf {std::path::Path::new(env!("CARGO_MANIFEST_DIR")).parent().expect("xtask has a parent dir").to_path_buf()}++#[cfg(test)]+mod tests {+ use super::audio_backend_hint;++ #[test]+ fn alsa_present_is_not_an_error() {+ assert!(audio_backend_hint(true).is_ok());+ }++ #[test]+ fn alsa_missing_names_the_package_for_each_distro() {+ let e = audio_backend_hint(false).expect_err("missing ALSA must fail CI");+ for want in ["alsa-lib-devel", "libasound2-dev", "alsa-lib", "pkg-config", "PKG_CONFIG_PATH"] {+ assert!(e.contains(want), "hint lost `{want}`:\n{e}");+ }+ }+}