Files
cardputerzero-sync/docs/building-and-installation.md

207 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Building & Installation Guide
This guide covers building the ARM64 Debian package for **CardputerZero**, installing the background receiver on **macOS**, running the desktop **SDL2 UI simulator**, and running all test suites.
---
## 1. Prerequisites
### macOS Host
- **Python:** `3.9+` (macOS system/Homebrew Python 3; both `mac-receiver` and `device-daemon` use the Python standard library with zero third-party `pip` dependencies).
- **Tailscale:** Signed into the same private tailnet as your CardputerZero.
- **Docker Desktop (for building the CardputerZero `.deb` on Mac):** Apple Silicon or `linux/arm64` binfmt/emulation support enabled.
- **Homebrew packages (only needed for building/running the macOS SDL2 desktop UI simulator & C++ tests):**
```bash
brew install cmake pkg-config sdl2 freetype sqlite3
```
### CardputerZero Device
- M5Stack CardputerZero running Raspberry Pi CM0 **ARM64 Debian Bookworm** (or compatible `arm64` Debian) with `systemd --user`, `APPLaunch`, and `tailscale` connected to your tailnet.
- Runtime packages declared by `packaging/debian/control`: `python3 (>= 3.9)`, `libsqlite3-0`, `libfreetype6`.
- Native build packages (only required if compiling `.deb` directly on the CardputerZero instead of via Docker):
```bash
sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config libsqlite3-dev libfreetype-dev dpkg-dev python3
```
---
## 2. Optional: Bundling TrueType Fonts (`Inter` + `JetBrains Mono`)
At runtime, `cp0-sync-ui` searches for Sans and Mono fonts in this order (`device-ui/src/app_ui.cpp`):
1. `CP0_FONT_SANS` / `CP0_FONT_MONO` environment variable overrides
2. `/usr/share/cp0-sync/fonts/` (`Inter-Regular.ttf` / `Inter.ttf` and `JetBrainsMono-Regular.ttf` / `JetBrainsMono.ttf`)
3. `assets/fonts/` relative to working directory
4. System Debian (`DejaVuSans.ttf`, `LiberationSans-Regular.ttf`, `/usr/share/fonts/truetype/inter/...`) or macOS (`/System/Library/Fonts/SFNS.ttf`, `Menlo.ttc`, etc.)
5. Built-in crisp 5×7 pixel bitmap font (`kFont5x7`) if no `.ttf` / `.ttc` font is found
If you want `Inter` and `JetBrains Mono` bundled inside the `.deb` at `/usr/share/cp0-sync/fonts/`, place `.ttf` or `.otf` font files in `packaging/fonts/` (or `device-ui/assets/fonts/`) **before** running `packaging/build-deb.sh`:
```text
packaging/fonts/
├── Inter-Regular.ttf
└── JetBrainsMono-Regular.ttf
```
> Note: When building the CardputerZero target inside a clean container or minimal Bookworm image without bundled fonts, installing `fonts-dejavu-core` on the device also activates FreeType anti-aliased rendering automatically without needing custom files in `packaging/fonts/`.
---
## 3. Building the CardputerZero ARM64 `.deb`
### Method A: Cross-Build on macOS via Docker (Recommended)
`packaging/build-deb.sh` uses [`packaging/Dockerfile.arm64`](../packaging/Dockerfile.arm64) (`--platform linux/arm64`, `debian:bookworm-slim`) to compile `device-ui` with `-DCP0_UI_TARGET_DEVICE=ON` (Linux `fbdev` + `evdev`), run C++ unit tests inside the container, and package `cp0-sync_1.0.0_m5stack1_arm64.deb`:
```bash
./packaging/build-deb.sh
```
Output artifact:
```text
packaging/dist/cp0-sync_1.0.0_m5stack1_arm64.deb
```
`(packaging/dist/ and device-ui/build-arm64/ are gitignored.)`
#### `build-deb.sh` Options
| Flag | Description |
|---|---|
| *(none)* | Build inside `--platform linux/arm64` Docker container and copy `.deb` to `packaging/dist/` |
| `--local` | Compile `device-ui` (`CP0_UI_TARGET_DEVICE=ON`) and build `.deb` directly on a Linux ARM64 host |
| `--stage-only <dir>` | Stage package file tree without calling `dpkg-deb` (requires existing binary or `--ui-bin`) |
| `--ui-bin <path>` | Use a prebuilt `cp0-sync-ui` binary instead of recompiling |
| `--out-dir <dir>` | Write `.deb` into a custom directory instead of `packaging/dist/` |
### Method B: Build Directly on CardputerZero (or ARM64 Linux Host)
```bash
git clone <your-repo-url> cardputerzero-sync
cd cardputerzero-sync
sudo apt-get update && sudo apt-get install -y build-essential cmake pkg-config libsqlite3-dev libfreetype-dev dpkg-dev python3
./packaging/build-deb.sh --local
```
### Package Contents (`cp0-sync_1.0.0_m5stack1_arm64.deb`)
- `/usr/bin/cp0-sync-ui` — 320×170 companion UI (`fbdev` + `evdev` binary)
- `/usr/bin/cp0-syncd` — Background Python sync daemon CLI entrypoint
- `/usr/lib/cp0-sync/cp0_syncd/*.py` — Sync daemon Python modules
- `/usr/lib/systemd/user/cp0-syncd.service` — `systemd --user` service unit
- `/usr/share/APPLaunch/applications/cp0-sync.desktop` — `Photo Sync` app launcher entry
- `/usr/share/APPLaunch/share/images/cp0-sync.png` — `80×80` app icon
- `/usr/share/cp0-sync/fonts/*` — Optional bundled fonts (if provided at build time)
---
## 4. Installing & Uninstalling on CardputerZero
Copy the `.deb` over Tailscale and install:
```bash
scp packaging/dist/cp0-sync_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-host>:/tmp/
ssh pi@<cardputerzero-host> "sudo dpkg -i /tmp/cp0-sync_1.0.0_m5stack1_arm64.deb"
```
If `dpkg` reports missing shared runtime dependencies (`libfreetype6` or `libsqlite3-0`), resolve them with:
```bash
sudo apt-get install -f -y
```
### What `postinst` / `prerm` Do
- **`postinst` (`configure`):** Runs `systemctl --global enable cp0-syncd.service || true` and best-effort restarts `cp0-syncd.service` for active logged-in user sessions via `loginctl`.
- **`prerm` (`remove` / `deconfigure`):** Stops active user instances, runs `systemctl --global disable cp0-syncd.service || true`, and cleans Python `__pycache__` files under `/usr/lib/cp0-sync` without deleting your `~/.config/cp0-sync/` or `~/.local/share/cp0-sync/` data.
Verify the background service is active under your user session:
```bash
systemctl --user status cp0-syncd.service
```
To uninstall later:
```bash
sudo dpkg -r cp0-sync
```
---
## 5. Installing the Mac Receiver
On your Mac, run the `LaunchAgent` installer from the repository:
```bash
./mac-receiver/bin/cp0-mac-sync install-service
./mac-receiver/bin/cp0-mac-sync status
```
This creates and loads `~/Library/LaunchAgents/com.cardputerzero.photosync.plist` (`RunAtLoad=true`, `KeepAlive=true`), starting `mac-receiver/bin/cp0-mac-receiver` automatically at login.
*(Optional)* Symlink the CLI scripts into your `PATH` (both entrypoints resolve the `mac-receiver/` package cleanly through symlinks):
```bash
mkdir -p ~/.local/bin
ln -sf "$(pwd)/mac-receiver/bin/cp0-mac-sync" ~/.local/bin/cp0-mac-sync
ln -sf "$(pwd)/mac-receiver/bin/cp0-mac-receiver" ~/.local/bin/cp0-mac-receiver
```
To stop and remove the `LaunchAgent`:
```bash
./mac-receiver/bin/cp0-mac-sync uninstall-service
```
---
## 6. Building & Running the Desktop Simulator (`device-ui`)
You can run and visually inspect the 320×170 UI natively on macOS using SDL2 without CardputerZero hardware:
```bash
cmake -S device-ui -B device-ui/build -DCP0_UI_BUILD_TESTS=ON -DCP0_UI_BUILD_APP=ON
cmake --build device-ui/build
```
Run a scaled `3×` simulator window (connected to `~/.config/cp0-sync/` or offline fallback):
```bash
./device-ui/build/cp0-sync-ui --sim --scale 3
```
Render a headless `320×170` PPM snapshot without opening a window:
```bash
./device-ui/build/cp0-sync-ui --render-test /tmp/status_dark.ppm --theme dark --tab status
./device-ui/build/cp0-sync-ui --render-test /tmp/folders_light.ppm --theme light --tab folders
```
### CMake Options Reference (`device-ui/CMakeLists.txt`)
| Option | Default | Notes |
|---|---|---|
| `CP0_UI_BUILD_TESTS` | `ON` | Builds `test_ipc_and_theme` and `test_ui_navigation` |
| `CP0_UI_BUILD_APP` | `ON` | Builds the `cp0-sync-ui` executable (set `OFF` to build only `cp0_ui_core` + tests) |
| `CP0_UI_TARGET_DEVICE` | `OFF` | Linux only: targets `/dev/fb0` + `/dev/input/event*` instead of SDL2 (errors cleanly on non-Linux hosts) |
| *(Optional LVGL)* | auto-detected | If system `lvgl` (`find_package(lvgl)` / `pkg-config lvgl`) is present, enables `CP0_HAS_LVGL=1` style hooks alongside the built-in `320×170` renderer; never downloads over network via `FetchContent` |
---
## 7. Running All Test Suites
All test suites use zero third-party Python dependencies (`unittest` stdlib) and CTest:
```bash
# 1. Mac Receiver unit & HTTP server tests (24 tests)
PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v
# 2. Device Daemon config, SQLite store, watcher, uploader & IPC tests (25 tests)
PYTHONPATH=device-daemon:mac-receiver python3 -W error -m unittest discover -s device-daemon/tests -v
# 3. Companion UI C++ tests (2 CTest targets: test_ipc_and_theme, test_ui_navigation)
cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure -V
# 4. Packaging validation tests (7 tests)
python3 -m unittest discover -s packaging/tests -v
```
*(Note on macOS sandboxing: `test_server.py`, `test_daemon_integration.py`, and `test_ipc_and_theme` open local TCP loopback or `AF_UNIX` sockets; if running inside a restricted sandbox that blocks sockets with `Operation not permitted` / `EPERM`, run them outside the sandbox.)*