Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Packaging and releases

This page describes how release artifacts are built: the RPM and tarball, the Windows installer, the third-party license page, and the GitHub release that the in-app updater reads.

Version

The version is the single version line under [workspace.package] in the root Cargo.toml. All crates inherit it. The packaging scripts read it from there, listen --version prints it, and the updater compares it with the newest release tag. To release, raise the number, build, and tag the commit vX.Y.Z. A tag containing a hyphen, such as v0.35.0-beta.1, is a pre-release.

RPM and tarball

Build the release binary first, then run the script from anywhere inside the repository:

cargo build --release -p listen
cargo install cargo-about --locked    # once
packaging/build-rpm.sh

packaging/build-rpm.sh produces two files in dist/:

  • listen-<version>-x86_64.tar.gz, a portable tarball with the binary, the desktop file, the icon, LICENSE, NOTICE.md, README.md and THIRD_PARTY_LICENSES.html.
  • listen-<version>-1.<dist>.x86_64.rpm, built by rpmbuild from packaging/listen.spec, which installs the binary, the desktop entry (io.github.leks2205.Listen.desktop) and the icon, and declares the run-time dependencies (mpv, PipeWire tools, the display libraries, whipper, flac and cdrdao; yt-dlp and Node.js as recommended packages). On a machine that is not Fedora the script defines a dist tag so rpmbuild still works.

The RPM is a binary package of the prebuilt executable; it does not compile anything.

Windows installer

packaging/windows/build-installer.sh [--no-build] [--out DIR] builds dist/Listen-Setup-<version>.exe on Linux:

  1. Cross-builds listen.exe for x86_64-pc-windows-gnu (skipped with --no-build). See Building from source.
  2. Assembles a folder with listen.exe, LICENSE, NOTICE.md and a fresh THIRD_PARTY_LICENSES.html. mpv, yt-dlp and Deno are not bundled; the installed app obtains them with winget on first start.
  3. Downloads Inno Setup into a cache ($LISTEN_WIN_CACHE, default ~/.cache/listen-windows), checking a pinned SHA-256 before using it, installs it into a Wine prefix ($LISTEN_WINE_PREFIX) and compiles packaging/windows/listen.iss with it.

Needs wine, curl, sha256sum, cargo-about and the MinGW toolchain. The installer is per-user: it installs to %LOCALAPPDATA%\Programs\Listen and does not ask for administrator rights. The script prints the installer’s SHA-256 at the end. packaging/windows/test-installer-wine.sh is a helper for trying the installer under Wine.

Note: A fresh Wine prefix can hang on some Fedora releases. The script header explains the workaround it uses (it copies an existing ~/.wine prefix and fills in the 32-bit system files).

Third-party licenses

THIRD_PARTY_LICENSES.html lists the license of every Rust crate in the build. It is generated by cargo about generate packaging/about.hbs, using the rules in about.toml:

  • accepted lists the allowed SPDX licenses (MIT, Apache-2.0, BSD, ISC, Zlib, MPL-2.0, Unicode, GPL-3.0 for the GPL parts and so on). A dependency under any other license makes the generation fail, which is the point: review it before shipping.
  • targets covers both x86_64-unknown-linux-gnu and x86_64-pc-windows-gnu, so one file serves both platforms.
  • Build and dev dependencies are ignored, and a workaround is set for the ring crate.

packaging/about.hbs is the page template. Fonts, icons and the parts derived from Feishin are listed in NOTICE.md, which ships next to the page.

GitHub releases and the updater

A release on GitHub carries the RPM, the tarball, the Windows installer and a text file named SHA256SUMS. Create the checksums from inside dist/:

cd dist
sha256sum listen-*.rpm listen-*.tar.gz Listen-Setup-*.exe > SHA256SUMS

The in-app updater (app/src/app/updater.rs) reads the repository’s releases through the GitHub API, picks the asset that fits how Listen was installed (the RPM on Fedora, the installer on Windows, or the tarball, whose binary replaces the one in ~/.local/bin), downloads it and refuses to install it unless its SHA-256 matches the line in SHA256SUMS. A release without SHA256SUMS cannot be installed by the updater. Pre-releases are only offered to users who chose the beta update channel. See Updates for the user side.