diff --git a/CLAUDE.md b/CLAUDE.md index 89af9e5..2655910 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -275,11 +275,18 @@ hides world surfaces itself. Keep the teardown rule: overlays, then SteamVR, the targets, and with a `/usr` Qt it would bundle glibc. - **`VRDASH_BUNDLE_EXCLUDE` must keep excluding the GPU/display stack** (libGL/EGL/GLX, libdrm/gbm, Vulkan, Wayland, X11/xcb, libffi, glibc, libstdc++). These must come from SteamOS, - or GPU access breaks. + or GPU access breaks. With libmosquitto shipped, `cmake/Mosquitto.cmake` also excludes + `libssl`/`libcrypto`: the bundler resolves dependencies recursively (also through excluded + libraries) and otherwise ships Debian's OpenSSL 3.5; SteamOS has OpenSSL 3. - **Release packages** (`scripts/package-release.sh [--bundle-qt]`) contain only the app, `install.sh` (install/update: stops a running instance, registers, - launches), `uninstall.sh` and `README.txt`. `deploy-to-frame.sh` rsyncs the newest one to - the Frame and runs its `install.sh`. + launches), `uninstall.sh` (stops the app, `--ha-remove`, unregisters) and `README.txt`. + `deploy-to-frame.sh` rsyncs the newest one to the Frame and runs its `install.sh`. + - `package-release.sh` refuses a package whose ELF files *need* (version needs section, not + a library's own definitions) newer `GLIBC_*`/`OPENSSL_*` versions than the Frame has + (glibc 2.39, OpenSSL 3.2.1; D35). Raise the limits in the script only after checking the + Frame. + - About 11 of the binary's 12 MB are debug info (`RelWithDebInfo`). - **Licenses:** MIT (`LICENSE`); `THIRD_PARTY_NOTICES.md` and OpenVR's license are installed to `share/doc/frameassistant/`. Bundled builds also get the Debian copyright files of every bundled library plus the referenced common license texts (collected via `dpkg -S` in @@ -355,3 +362,6 @@ Check these when testing on the device, and update this list: - Several dashboard tabs from one process (works in `tst_surfaces`, not tried in SteamVR). - Settings errors when started by SteamVR: the app exits and the log names the error (e.g. missing `device.name`); covered by `tst_config` off the device (iteration 1 checks 3, 4). +- Iteration 2: the package with libmosquitto (system Qt and bundled) connects to the broker; + "Quit app" publishes `offline` (graceful exit); `uninstall.sh` removes the device from HA; + which CA store OpenSSL uses with `mqtt.tls.ca_file` empty. diff --git a/cmake/Mosquitto.cmake b/cmake/Mosquitto.cmake index 4dc26fb..eac30a9 100644 --- a/cmake/Mosquitto.cmake +++ b/cmake/Mosquitto.cmake @@ -34,6 +34,8 @@ if(FRAMEASSISTANT_SHIP_MOSQUITTO) message(WARNING "${_mosquitto_copyright} not found: package lacks libmosquitto's license") endif() - # Shipped by the rule above: the Qt bundler must not copy it a second time. - list(APPEND VRDASH_BUNDLE_EXCLUDE "^libmosquitto") + # Shipped by the rule above: the Qt bundler must not copy it a second time. Its + # OpenSSL comes from the system (SteamOS has OpenSSL 3; libmosquitto needs OPENSSL_3.0.0): + # the bundler resolves dependencies recursively and would bundle Debian's. + list(APPEND VRDASH_BUNDLE_EXCLUDE "^libmosquitto" "^libssl\\.so" "^libcrypto\\.so") endif() diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 504f9be..ca881e4 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -514,6 +514,12 @@ excluded from the Qt bundler, licence in `share/doc/frameassistant/`). of MQTT (D17). 6. Guard: `package-release.sh` checks with `readelf -V` that shipped libraries need no newer symbol versions than the Frame has (today at most `OPENSSL_3.2`, `GLIBC_2.39`). + Implemented for every ELF file in the package, reading only the version *needs* section + (a library's own definitions, e.g. libssl's `OPENSSL_3.5.0`, gave false positives). +7. Found when building the bundled package: the bundler resolves dependencies recursively, + also through excluded libraries, and shipped Debian's `libssl`/`libcrypto` (OpenSSL 3.5) + for libmosquitto. `cmake/Mosquitto.cmake` now excludes them too: OpenSSL comes from + SteamOS (3.2.1; libmosquitto needs `OPENSSL_3.0.0`). ## Test strategy diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index 8237a36..56ce6b7 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -22,11 +22,26 @@ CLAUDE.md ("Working rules"). The error itself is covered off the device by `tst_config`. Checks 3 and 4 run in the next session on the Frame (iteration 2 testing needs it too). -- **Implementation** follows the order in DESIGN.md (steps 1–7). Steps 1 (libmosquitto in - CMake and the containers), 2 (`MqttClient`, `MosquittoClient`, `tst_mqtt`) 3 - (`HaEntity`, `HaSensor`, `HaDevice`, unit tests) and 4 (app wiring, `--desktop-novr`, - UI-1) 5 (TLS) and 6 (app commands, `--ha-remove`, `uninstall.sh`) done; next: step 7 - (packaging check, docs). +- **Implementation (phase 3) done:** steps 1–7 of DESIGN.md. **Next: phase 4 (testing)** + with the manual checklist below, from the PC against the user's HA and broker; then on the + Frame. +- **Manual checklist for iteration 2 (phase 4):** + + | # | Check | Where | Result | + |---|---|---|---| + | 1 | Settings file for the PC (own device name, the user's broker), `--desktop-novr --config …`: tab shows "Connected" | PC | open | + | 2 | HA: device appears with the "Uptime" sensor (diagnostic), value rises every 10 s; HA log has no MQTT discovery warnings (NFR-7); `~` base topic accepted | PC + HA | open | + | 3 | Close the window → HA shows the entities unavailable at once (graceful exit) | PC + HA | open | + | 4 | `kill -9` → unavailable (last will) | PC + HA | open | + | 5 | Broker restart → tab "Not connected" + error, then "Connected"; HA values current again | PC + HA | open | + | 6 | HA restart → device republished after the birth message | PC + HA | open | + | 7 | Two settings files with different device names → two HA devices | PC + HA | open | + | 8 | Login and, if the broker offers it, TLS against the user's broker | PC + HA | open | + | 9 | `--ha-remove --config …` → device gone from HA | PC + HA | open | + | 10 | Package on the Frame: starts with SteamVR, connects, tab shows the status; "Quit app" → unavailable | Frame | open | + | 11 | `uninstall.sh` on the Frame removes the device from HA; `install.sh` brings it back | Frame | open | + | 12 | Iteration 1 checks 3 and 4 (settings errors when started by SteamVR) | Frame | open | + ## Next steps @@ -185,6 +200,18 @@ Known limitation: the bundled-Qt package does not support WebEngine in this iter unregisters. Checked end to end against a local mosquitto, without a display: retained discovery, availability, state and entity availability before, none after (exit 0); broker down → exit 1 after 10 s; missing settings → exit 1. +- Step 7: `package-release.sh` checks the symbol versions of every shipped ELF file against + the Frame (glibc 2.39, OpenSSL 3.2.1; D35); a test with a too low limit names the files + and refuses the package. Building the bundled package showed two problems, both fixed: + the check read version *definitions* too (false positives from libssl), and the bundler + shipped Debian's OpenSSL 3.5 for libmosquitto (now excluded; SteamOS provides OpenSSL). + Checked: + - system-Qt package 5.0 MB (`lib/libmosquitto.so.1`, its copyright file; the binary is + 12 MB, 11 MB of it debug info); bundled package 45 MB, no OpenSSL, libmosquitto once; + both need at most `GLIBC_2.38`, `OPENSSL_3.0.0`. + - generated `uninstall.sh` with a stub binary and a stub `pkill`: stop, `--ha-remove`, + unregister; a failing `--ha-remove` prints the warning and still unregisters. + - `container-test.sh` 13/13, no Vulkan validation messages. ### 2026-10-05: requirements approved diff --git a/scripts/package-release.sh b/scripts/package-release.sh index e00e40a..691d86c 100755 --- a/scripts/package-release.sh +++ b/scripts/package-release.sh @@ -50,6 +50,29 @@ cp -a "$stage/." "$out/" find "$out/bin" -maxdepth 1 -type f -perm -u+x ! -name "$exe" -delete cp "$root/LICENSE" "$out/" +# Nothing shipped may need newer glibc or OpenSSL symbol versions than the Frame has +# (docs/DESIGN.md, D35; checked on the Frame 2026-10-05: glibc 2.39, OpenSSL 3.2.1). Catches a +# Debian update of a shipped library (libmosquitto, bundled Qt) that SteamOS can't run. +frame_max=(GLIBC_2.39 OPENSSL_3.2.0) +too_new=0 +while IFS= read -r -d '' file; do + [[ "$(file -b "$file")" == ELF* ]] || continue + # Only the "needs" section: a library's own version definitions (e.g. libssl defining + # OPENSSL_3.5.0) are not needed from the system. + for needed in $(readelf -V --wide "$file" | + awk '/^Version needs section/ {n = 1; next} /^Version/ {n = 0} n' | + grep -oE "Name: (GLIBC|OPENSSL)_[0-9.]+" | cut -d' ' -f2 | sort -u); do + for max in "${frame_max[@]}"; do + [[ "${max%%_*}" == "${needed%%_*}" ]] || continue + if [[ "$(printf '%s\n%s\n' "$needed" "$max" | sort -V | tail -1)" != "$max" ]]; then + echo "${file#"$out"/} needs $needed; the Frame has at most $max" >&2 + too_new=1 + fi + done + done +done < <(find "$out" -type f -print0) +(( too_new )) && { echo "Package not usable on the Frame" >&2; exit 1; } + cat > "$out/install.sh" <