SouveraineOS/docs/substrate/tasks/feature-gate-voice-deps.md

scope	status	created
build	proposed	2026-05-18

Feature-gate voice/audio dependencies

Problem

cargo build fails on a fresh Linux install because cpal pulls in alsa-sys, which requires alsa-lib-devel (or equivalent) to be installed. First-time users hit a cryptic pkg-config error about missing ALSA.

Solution

1. Feature-gate cpal and rodio behind an optional voice feature in Cargo.toml. Default: off.
2. #[cfg(feature = "voice")] the src/core/voice/ module so the module and its imports don't compile when the feature is off.
3. Graceful fallback — if the user runs souveraine tui without voice, the setup wizard or TUI should show "Voice disabled (compile with --features voice)" instead of crashing.
4. Build-time hint — if cpal fails to build (pkg-config error), the error should suggest dnf install alsa-lib-devel (Fedora) or apt install libasound2-dev (Debian) rather than panicking with the raw pkg-config output. This might need a build.rs or a note in a README instead, since build-script panics come from upstream crates.

Files to touch

• Cargo.toml — make cpal, rodio optional; add voice feature
• src/core/voice/mod.rs — #[cfg(feature = "voice")]
• src/core/mod.rs — gate the pub mod voice declaration
• src/core/config.rs — VoiceConfig behind feature gate or default stub
• src/ui/ — any voice UI that imports voice types

Non-goals

• Don't remove or rework the voice subsystem. Just make it opt-in at build time.
• Don't split ALSA detection into a build.rs for upstream crates. That's cpal/alsa-sys's job.