pkg: build a local .deb; de-duplicate onto DAEMON's systemd/nativehost/man page

DAEMON landed packaging/nativehost/, packaging/systemd/{velox.service,velox.socket} (real sd_listen_fds() socket activation) and cli/man/velox.1 on main while this was in flight, duplicating paths this branch had drafted independently. Per CLAUDE.md (packaging/nativehost/ is DAEMON's; the rest of packaging/ is PKG/QA's), DAEMON's copies are kept as the single source and this branch's packaging/native-messaging/, packaging/man/velox.1 and stale packaging/systemd/velox.service are dropped rather than maintained twice. The root CMakeLists.txt's install() rules now point at DAEMON's paths directly, install both systemd units (not just velox.service), and docs/07-packaging.md / packaging/README.md no longer claim there's no socket activation — there is, and this package now ships it. Adds the local-test-only .deb itself: debian/{control,rules,postinst,postrm, changelog,copyright}, a placeholder icon set, the desktop entry and PKG/QA's own man pages (veloxd.8, velox-gui.1 — velox.1 stays DAEMON's). libveloxcore stays static (no consumer needs a .so yet); pairing has no real approval UI in this build (D1 unbuilt), so postinst and packaging/README.md both say VELOX_PAIR_AUTO=1 is required and print it prominently. No PPA, no GPG — local dpkg -i only. Verified live: dpkg-buildpackage -us -uc -b, dpkg -i, socket activation (systemctl --user enable --now velox.socket), `velox ls` against the running daemon, lintian clean, dpkg -r removes the manifest/units and leaves $XDG_DATA_HOME/velox alone. .gitignore now excludes dpkg-buildpackage's debhelper build tree and obj-*/ (the debuild output dir) — debian/control et al. stay tracked, everything debhelper regenerates does not. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_0176u3fTrxegrGNm2yC7r69W
2026-09-15 18:02:11 +04:00
parent 9624e685af
commit 31eadffce5
24 changed files with 492 additions and 2 deletions
@@ -1 +1,101 @@
 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.
+
+```sh
+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:
+  ```sh
+  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.
@@ -0,0 +1,12 @@
+[Desktop Entry]
+Type=Application
+Version=1.0
+Name=Velox
+GenericName=Download Manager
+Comment=IDM-class download manager
+Exec=velox-gui
+Icon=velox
+Terminal=false
+Categories=Network;FileTransfer;
+Keywords=download;downloader;idm;resume;segmented;
+StartupNotify=true
@@ -0,0 +1,20 @@
+.TH VELOX\-GUI 1 "2026-09-12" "velox 0.1.0" "Velox Download Manager"
+.SH NAME
+velox-gui \- Velox download manager, graphical client
+.SH SYNOPSIS
+.B velox-gui
+.SH DESCRIPTION
+.B velox-gui
+is the Qt graphical client for
+.BR veloxd (8),
+the Velox download manager daemon. It takes no command-line arguments and connects
+to the daemon over its local Unix socket.
+.B veloxd
+must already be running \(em see
+.BR veloxd (8)
+for starting it as a
+.B systemd --user
+service.
+.SH SEE ALSO
+.BR velox (1),
+.BR veloxd (8)
@@ -0,0 +1,35 @@
+.TH VELOXD 8 "2026-09-12" "velox 0.1.0" "Velox Download Manager"
+.SH NAME
+veloxd \- Velox download manager daemon
+.SH SYNOPSIS
+.B veloxd
+.SH DESCRIPTION
+.B veloxd
+is the background daemon behind the Velox download manager. It manages downloads,
+segmented transfers and resume state in a local SQLite database, and exposes a
+JSON-RPC API over a local Unix socket (for
+.BR velox (1)
+and
+.BR velox-gui (1))
+and a loopback WebSocket (for the Firefox extension).
+.PP
+It takes no command-line arguments. It is normally started as a
+.B systemd --user
+service:
+.RS
+.nf
+systemctl --user enable --now velox.service
+.fi
+.RE
+.SH FILES
+.TP
+.I $XDG_RUNTIME_DIR/velox/velox.sock
+The Unix socket clients connect to.
+.TP
+.I $XDG_DATA_HOME/velox/velox.db
+The task and settings database (default
+.IR ~/.local/share/velox/velox.db ).
+.SH SEE ALSO
+.BR velox (1),
+.BR velox-gui (1),
+.BR systemctl (1)