# 07 — Packaging & install layout

Owner: lane **PKG/QA**. Target: Ubuntu 26.04 LTS.

## Install layout (.deb)

```
/usr/bin/veloxd
/usr/bin/velox-gui
/usr/bin/velox                       # CLI
/usr/libexec/velox/velox-nmhost      # native messaging host
/usr/share/applications/velox.desktop
/usr/share/icons/hicolor/*/apps/velox.png
/usr/share/man/man1/velox.1.gz
/usr/lib/systemd/user/velox.service
/usr/lib/systemd/user/velox.socket   # real socket activation, see below
/usr/lib/mozilla/native-messaging-hosts/com.velox.host.json
/etc/xdg/autostart/velox-gui.desktop # optional, off by default
```

`libveloxcore` is **static**, linked into `veloxd`, `velox` and `velox-gui` directly —
there is no `libveloxcore.so.*` to install. A shared, versioned `libveloxcore.so.1` was
the original plan here; the user decided against building one for now (no consumer needs
it as a shared object yet, and it would need CORE's `core/CMakeLists.txt` to grow a
`SOVERSION`). Revisit as a CORE-lane request if that changes — this doc was corrected in
the same commit as the decision rather than left describing something unshipped.

`velox.service` and `velox.socket` are both DAEMON's (`packaging/systemd/README.md`,
`daemon/src/rpc/systemd_activation.cpp`) — real `sd_listen_fds()` socket activation, not a
plain `exec`. This package installs both units verbatim and lets `dh_installsystemduser`
(compat 13) pick them up from the install tree; see `packaging/README.md` for what that
does and does not do at install time for an already-running session.

`postinst` additionally drops per-user native-messaging manifests for the packaging formats
that need them, and **detects whether Firefox is a snap** — if so it prints (and the GUI's
first-run wizard shows) a one-line note that the extension will pair over loopback.

## Package matrix

| Format | Priority | Notes |
|---|---|---|
| `.deb` via PPA | **Primary** | The only format where native messaging, systemd user units and Secret Service all behave predictably |
| Flatpak | Secondary | The sandbox changes native messaging *again*; test explicitly, don't assume. Needs `--filesystem=xdg-download` and a portal-based folder picker |
| AppImage | Optional | Convenient for testing; if it bundles Qt, honour LGPLv3 relink terms (`docs/06` R5) |
| Snap | **Not planned** | Confinement fights both native messaging and arbitrary download destinations. Revisit only if there's demand |

## Firefox extension distribution

Signed XPI on **addons.mozilla.org**. Ship the source with a reproducible build script
(AMO requires it for minified/bundled submissions). The `.deb` does *not* bundle the XPI —
it links to AMO from the first-run wizard, so extension updates flow through Firefox's own
update channel rather than through apt.

## Release checklist

- [ ] `lintian` clean
- [ ] Fresh 26.04 VM: install → install extension → M2 vertical slice passes with snap Firefox
- [ ] Upgrade from N-1: DB migrates, in-flight `.veloxpart` files still resume
- [ ] Uninstall: manifests, units and sockets removed; user data untouched unless purged
- [ ] `systemctl --user` units enabled and socket-activation verified from cold boot
- [ ] Protocol `VERSION` matches between the shipped daemon and the shipped extension, and
      a deliberate mismatch produces the "Velox needs updating" message rather than a hang
- [ ] Licence audit: Qt (LGPLv3, dynamic), libcurl, SQLite, ffmpeg, icon set