ADR-008: Distribution — cargo-dist + Per-Distro Packagers¶

Status: Accepted
Date: 2026-05-18
Deciders: Mohsen Seyedkazemi Ardebili

Context¶

YazSes v0.4 ships via apt, snap, dmg, and an exe with bundled Python. The install experience has friction: PortAudio errors, Python-version conflicts, and 100–150 MB install artifacts from the bundled Python interpreter. The v1.0 target is a single static binary per platform with zero runtime dependencies, idle RSS below 80 MB, and install time under 60 seconds including the first model download. This bar aligns with the Rust-core decision in ADR-001; cargo-dist is the current best-of-breed toolchain for producing cross-platform release binaries from a Rust workspace.

Model weights are not embedded in the binary; yazses model pull fetches GGUF files from Hugging Face (or a configured mirror) and caches them at ~/.local/share/yazses/models/, keeping the binary itself below 100 MB.

Decision¶

cargo-dist is adopted for cross-platform release binary generation. It produces statically-linked binaries for Linux x86_64, Linux aarch64, macOS x86_64, macOS aarch64, and Windows x86_64, plus a generic installer script. GitHub Releases is the canonical distribution channel.

Per-platform packagers complement the binary: - cargo-deb — Debian/Ubuntu .deb packages, feeding the existing YazSes apt-repo. - cargo-rpm + Fedora COPR — RPM packages. - cargo-aur — Arch User Repository PKGBUILD. - Homebrew tap (yazses/tap/yazses) — preserves the existing macOS distribution path. - winget manifest + MSI (WixToolset fallback) — Windows package manager. - Snap — continued if the existing snap repo retains active users; deprecated otherwise. - AppImage — optional, nice-to-have for distro-agnostic Linux.

Consequences¶

Positive: - Idle RSS target of ≤ 80 MB is achievable in the Rust-core path. - Existing apt-repo, Homebrew tap, and snap infrastructure are reusable. - Reproducible builds via cargo with a pinned toolchain support the sovereignty commitment (see ADR-011). - Cross-architecture support extends naturally to Linux aarch64 (Raspberry Pi 5, ARM servers) and macOS aarch64.

Negative / trade-offs: - Approximately five per-platform package manifests must be maintained per release. Some are auto-generated by cargo tooling; winget requires manual submission. - Apple notarisation is a per-release manual ceremony; cargo-dist's macOS-signing support partially automates this. - Windows code-signing certificate carries an annual cost (~$300–500); the v0.4 setup carries forward.

Implementation¶

cargo-dist configuration is in Cargo.toml under [workspace.metadata.dist]. Per-distro package targets are in .github/workflows/release.yml. The yazses model pull command is implemented in yazses-core/src/model_manager.rs and exposed via the CLI entry point in yazses-cli/src/commands/model.rs.