vdm/packaging/README.md

Owner: lane PKG/QA. See ../docs/07-packaging.md.

.deb — local test build only

There is no PPA, no GPG signing, no Launchpad wiring here. This produces a .deb you install with dpkg -i on the box you built it on (or an identical one), for testing — not something to hand to a user or publish anywhere. See docs/07-packaging.md's package matrix for the eventual PPA plan.

sudo ./tools/bootstrap.sh --packaging          # debhelper, dpkg-dev, lintian, devscripts, fakeroot
dpkg-buildpackage -us -uc -b                   # from the repo root; -b = binary only, no signing
sudo dpkg -i ../velox_0.1.0-1_amd64.deb
lintian ../velox_0.1.0-1_amd64.deb

Uninstall: sudo dpkg -r velox (or sudo dpkg -P velox to purge — see below for what purge does and does not do here).

Known limitations of this build — read before relying on any of these

• libveloxcore is static, not .so.1. The install layout in docs/07-packaging.md originally called for a shared, versioned libveloxcore.so.1; the user decided against building one for now (no consumer needs it as a shared object yet, and it would need a SOVERSION added to CORE's own core/CMakeLists.txt). The doc was corrected in the same commit as this packaging work — it no longer describes something unshipped.

• Placeholder app icon. gui/resources/icons/ (GUI's lane) is empty — no real icon art exists anywhere in the repo yet. packaging/icons/hicolor/*/apps/velox.png is a plain generated placeholder (flat color, a download-arrow glyph), good enough to install correctly and pass desktop-file-validate/lintian's icon checks, and nothing more. Replace it before any real release — and do the icon-set licence audit docs/07-packaging.md's release checklist asks for once real art exists (this placeholder was drawn from scratch for this package, so it has no licence question of its own, but it is not real Velox branding either).

• No license has been chosen for Velox's own source yet. There is no top-level LICENSE file in the repo. debian/copyright says so plainly (License: Unlicensed-TODO) rather than inventing one — that is a real project decision, above any one lane. Expect lintian to flag this package over it; that is lintian doing its job, not a bug in this packaging, and it stays a known exception to "lintian clean" until the project adopts a license. The release checklist's "Licence audit" item (Qt, libcurl, SQLite, ffmpeg, icon set) is separate and still open regardless.

• Pairing has no real approval UI in this build. libdbus-1-dev is not in this build's Build-Depends (D1's GUI-dialog/desktop-notification approver needs it and isn't wired up yet — daemon/src/main.cpp still uses EnvAutoApprover unconditionally). That approver auto-rejects every pairing request unless VELOX_PAIR_AUTO=1 is set in veloxd's environment — there is no prompt, no accept/decline, it is all-or-nothing. postinst prints this prominently after install; it is repeated here so it isn't missed by anyone reading only one of the two. Do not set VELOX_PAIR_AUTO=1 on a machine or account where auto-accepting every pairing request is unacceptable.

• Socket activation is real. velox.service and velox.socket both ship, verbatim from DAEMON's packaging/systemd/README.md — veloxd receives the pre-bound fd via sd_listen_fds() (daemon/src/rpc/systemd_activation.cpp) rather than binding its own socket. debian/rules does not disable dh_installsystemduser (only the system-level dh_installsystemd, since these are --user units); debhelper finds both units under lib/systemd/user/ in the install tree and enables the pair together (Also=velox.socket in velox.service's [Install]).

• The systemd --user service starts enabled for your next login, not this one. debhelper's dh_installsystemduser (verified in the built package's postinst) marks velox.service enabled automatically — that takes effect the next time each user's systemd --user instance starts. It cannot reach an already-running session from a root maintainer script, so for the session you're in right now, postinst prints:

  systemctl --user daemon-reload
  systemctl --user start velox.service
  

• dpkg -P velox (purge) does not delete user data. The uninstall test this package is built to pass is "manifests, units and sockets removed; user data untouched unless purged" — this build is deliberately conservative and leaves $XDG_DATA_HOME/velox (normally ~/.local/share/velox, the task database) alone on both remove and purge, for every account. A root maintainer script deleting per-user data across every account on the system is exactly the kind of destructive, hard-to-test operation that deserves its own design pass, not a first cut bolted on here. postrm only ever undoes what postinst did: the per-user native-messaging manifest it copied in.

The uninstall test, concretely

What docs/07-packaging.md's release checklist asks for, and what this build actually does:

Removed on dpkg -r/-P?
/usr/bin/{veloxd,velox,velox-gui}, /usr/libexec/velox/velox-nmhost	yes — dpkg itself, ordinary package files
/usr/lib/systemd/user/{velox.service,velox.socket}	yes — same
/usr/lib/mozilla/native-messaging-hosts/com.velox.host.json	yes — same
Per-user ~/.mozilla/native-messaging-hosts/com.velox.host.json	yes — postrm, both remove and purge
$XDG_DATA_HOME/velox (task DB, settings)	no, on either remove or purge — see above

Native messaging

velox-nmhost (DAEMON's nmhost/) and its manifest (DAEMON's packaging/nativehost/com.velox.host.json) now ship in this package — the top-level CMakeLists.txt's install rules are guarded on if(TARGET velox-nmhost), the same way its add_subdirectory() calls are, so this lit up automatically the day that lane merged, no packaging change needed on this end.