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/Applicationsto 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,.desktopfile, 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-inCI_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.pybuilds and assembles the bundles above.tools/brew_local.pycreates the local Homebrew cask and archive.tools/release_identity.pyandtools/stamp_release.pyassign CI package versions.tools/gitlab_release.pypublishes successful CI builds to the registry and Releases.tools/release_notes.pywrites the release notes from Conventional Commits.tools/generate_icons.pyregenerates committed icons with uv’s optionaliconsgroup (Pillow).tools/coverage.pyproduces the coverage reports.tools/supply_chain.pychecks licenses/RustSec and generates CycloneDX SBOMs.
None of them are part of the running app or read task data.