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

Building and packaging

Build on the target OS and architecture; nothing here cross-compiles, installs, or launches the app automatically.

cargo build --release --locked          # target/release/productivity
uv run --locked python tools/package.py  # launcher-ready bundle in dist/

The release profile uses whole-program LTO, a single codegen unit, and stripped symbols to keep the executable small (about 40 MB on macOS instead of 63 MB). A clean release build therefore takes several minutes; use cargo run for day-to-day development.

  • macOS: dist/Productivity.app, with icon and bundle metadata, ad-hoc signed and verified after assembly. Copy it to /Applications to install. Ad-hoc signing uses no certificate; public distribution still needs Developer ID signing and notarization.

  • Linux: dist/productivity-linux/, a staged tree with the executable, .desktop file, and icons. Install it for your user with:

    data_dir="${XDG_DATA_HOME:-$HOME/.local/share}"
    install -Dm755 dist/productivity-linux/bin/productivity "$HOME/.local/bin/productivity"
    install -Dm644 dist/productivity-linux/share/applications/dev.productivity.desktop.desktop \
      "$data_dir/applications/dev.productivity.desktop.desktop"
    install -Dm644 assets/branding/app.svg \
      "$data_dir/icons/hicolor/scalable/apps/dev.productivity.desktop.svg"
    

Install uv before running the Python helpers; it manages their environment and interpreter. See Python tooling.

uv run --locked python tools/package.py --profile debug --no-build packages an existing debug build.

Distribution packages

These use pinned Cargo extensions.

# Ubuntu .deb (needs dpkg-dev and xz-utils)
cargo install cargo-deb --version 3.8.0 --locked
cargo build --locked --release --bin productivity
cargo deb --no-build --output target/debian/productivity-local.deb

# macOS .dmg
cargo install cargo-bundle --version 0.12.0 --locked
cargo build --locked --release --bin productivity
cargo bundle --release --format dmg --binary-path target/release/productivity

Generate a matching Cargo dependency SBOM locally:

uv run --locked python tools/supply_chain.py install
uv run --locked python tools/supply_chain.py
cargo build --locked --release --bin productivity --no-default-features --features desktop
uv run --locked python tools/supply_chain.py sbom --binary target/release/productivity

target/sbom/productivity-<target-triple>.cdx.json records the manifest version and executable hash. CI uploads this sidecar with each package; it is not embedded in the .deb/.dmg. Pages publishes the Ubuntu release SBOM alongside the book, coverage report, and APT repository; see SBOM and dependency policy. See Development for policy, target selection, maintenance warnings, and inventory limitations.

Use --format osx for just the .app. These are unsigned, native-architecture builds. The Debian maintainer contact still needs to be chosen before a public release.

GitLab Releases from CI

After all earlier stages (including signed APT/Pages publication) succeed, release-gitlab publishes the same Ubuntu 26.04 amd64 build to GitLab’s Deploy → Releases and Deploy → Package registry. These features are available on GitLab.com Free. The existing scheduled-pipeline restriction remains in effect; setting AUTO_PIPELINES=true also permits default-branch push releases.

The job uses release-identity.json’s rolling version to create v<version> at the exact packaged commit, without committing the CI-only Cargo version stamp. Its download links point to the versioned Generic Package Registry, not expiring job artifacts or the latest-only Pages download. Each release retains the .deb, CycloneDX SBOM, build identity, Grype/RustSec reports, archive public key, and a flat SHA256SUMS file for those downloads. Direct downloads remain unsigned; prefer the signed APT repository. macOS CI remains opt-in and is not attached: it currently produces development-version, unsigned/non-notarized packages.

Each release page ends with release notes generated by tools/release_notes.py from the Conventional Commits since the newest earlier release on the mainline (merge commits are left out; the first release covers the whole history). Commits are grouped by scope, the part in parentheses such as notes in feat(notes): …, sorted by name with unscoped commits last under General. Within a scope they are ordered from most to least significant: Breaking (a ! after the type or a BREAKING CHANGE: footer), Feature, Fix, then Performance, Refactor, Revert, Docs, Style, Tests, Build, CI, Chore, and Other for anything else. Subjects are escaped so they cannot add links, HTML, or @mentions. Preview the notes locally without publishing:

uv run --locked python tools/release_notes.py --commit "$(git rev-parse HEAD)" \
  --since "$(git rev-parse HEAD~10)"

Project setup:

  • Keep the default branch protected. Only push/scheduled pipelines on that branch can publish; the remote tip is checked again before creating a release.
  • Enable the project’s Package registry. For public, login-free downloads, make the project and its package registry publicly accessible.
  • The pipeline/schedule owner needs permission to publish packages and create releases/tags (at least Developer; protected v* tags may require Maintainer). The job authenticates with the built-in CI_JOB_TOKEN: no personal token, Git-push permission, or new signing secret is needed.
  • Exclude release packages from any registry cleanup policy if old downloads must remain available. Registry packages have no job-artifact expiration, but manual deletion/cleanup still removes them. Retained versions consume storage.

Publication shares the APT deployment’s resource lock and refuses stale builds, wrong identities, or a tag belonging to another commit. A repeated schedule for an already-published version leaves the release and its packages untouched, even if a rebuild’s bytes differ. After an interrupted upload, retry the same job to resume identical files; conflicting existing bytes fail rather than being replaced. Do not delete or move release tags/packages to work around a conflict without first investigating it. No release or upload occurs during local tests.

Tools

  • tools/package.py builds and assembles the bundles above.
  • tools/brew_local.py creates the local Homebrew cask and archive.
  • tools/release_identity.py and tools/stamp_release.py assign CI package versions.
  • tools/gitlab_release.py publishes successful CI builds to the registry and Releases.
  • tools/release_notes.py writes the release notes from Conventional Commits.
  • tools/generate_icons.py regenerates committed icons with uv’s optional icons group (Pillow).
  • tools/coverage.py produces the coverage reports.
  • tools/supply_chain.py checks licenses/RustSec and generates CycloneDX SBOMs.

None of them are part of the running app or read task data.