> This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
This guide covers building the CardputerZero ARM64 `.deb` package, installing on device with `APPLaunch` integration, building the macOS/Linux SDL2 desktop simulator, and running all verification suites.
---
## 1. Prerequisites
### CardputerZero Device (Runtime)
- Raspberry Pi CM0 (ARM64 Debian Bookworm, `dtoverlay=imx219` enabled in `/boot/firmware/config.txt`)
- Sony IMX219 camera module verified with `rpicam-hello --list-cameras`
-`APPLaunch` application launcher and `/dev/fb0` + `cp0-keys``evdev` input device
- Runtime `.deb` dependencies (declared in [`packaging/debian/control`](../packaging/debian/control)):
-`python3 (>= 3.9)`
-`python3-picamera2`
-`ffmpeg`
-`alsa-utils` (`aplay`)
-`libjpeg62-turbo | libjpeg8`
-`libfreetype6`
-`libc6`, `libstdc++6`
> Note: `czcamera` intentionally has **no** dependency on `cp0-sync` and **no** direct C++ linkage to `libcamera0*` or `libcamera.so`.
- CMake `>= 3.16` and a C++17 compiler (`clang++` or `g++`)
-`pkg-config`
-`libjpeg` (`libjpeg-turbo` via Homebrew `jpeg-turbo`/`libjpeg` or Debian `libjpeg62-turbo-dev`)
-`SDL2` (`sdl2` via Homebrew or `libsdl2-dev`)
- **Optional:** `FreeType2` (`freetype` / `libfreetype-dev`) for crisp antialiased UI fonts (falls back automatically to the built-in `5×7` bitmap renderer if absent)
- **Optional:** `ffmpeg` & `ffprobe` on `PATH` for desktop Timelapse MP4 compilation and Gallery `.mp4` playback tests
- Python `>= 3.9` for running helper/packaging test suites
---
## 2. Building the ARM64 Debian Package (`.deb`)
Use [`packaging/build-deb.sh`](../packaging/build-deb.sh) in one of four supported modes:
Builds a clean `debian:bookworm-slim` (`linux/arm64`) container via [`packaging/Dockerfile.arm64`](../packaging/Dockerfile.arm64), compiles `czcamera` with `-DCZ_BUILD_APP=ON -DCZ_TARGET_DEVICE=ON -DCZ_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS_RELEASE="-O2"`, executes ARM64 `ctest` and `cam-helper/tests`, and outputs `packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb`:
```bash
./packaging/build-deb.sh
```
> Why `-O2` without global `-DNDEBUG`: the ARM64 verification step runs the C++ `ctest` binaries (`app/tests/*.cpp`) built in the same tree, and those tests use `<cassert>` `assert()`.
### Option B: Native Build on CardputerZero / ARM64 Linux
On an ARM64 Debian host with build dependencies installed (`build-essential cmake pkg-config libjpeg62-turbo-dev libfreetype-dev dpkg-dev`):
```bash
./packaging/build-deb.sh --local
```
### Option C: Stage Directory or Supply Prebuilt Binary
Stage the package tree without running `dpkg-deb` or Docker (useful for inspection or custom packaging):
If TTF/OTF font files exist under `app/assets/fonts/` or `packaging/fonts/` before running `build-deb.sh`, they are staged into `/usr/share/czcamera/fonts/` (`0644`). At runtime, `cz::AppView` checks `/usr/share/czcamera/fonts/` first, then common system font directories, and falls back to the built-in `5×7` bitmap font cleanly if none are installed.
---
## 3. Installing & Uninstalling on CardputerZero
Copy the generated package to the device and install via `dpkg` + `apt-get`:
Verify shared libraries (`libjpeg.so.62` / `libfreetype.so.6` present, zero `libcamera.so` linkage) and camera visibility:
```bash
ldd /usr/bin/czcamera
rpicam-hello --list-cameras
```
Launch **czcamera** from the `APPLaunch` grid, or test from TTY/SSH:
```bash
/usr/bin/czcamera
```
### Uninstalling
```bash
sudo apt-get remove czcamera
```
[`packaging/debian/prerm`](../packaging/debian/prerm) automatically cleans Python `__pycache__` bytecode under `/usr/lib/czcamera` on package removal or deconfiguration.
---
## 4. Building & Running the Desktop SDL2 Simulator
*(Note: `test_backend_protocol` also spawns `cam-helper/bin/czcamera-cam --mock-driver` end-to-end across pipes to validate C++ ↔ Python JSON v1 + `CZFR` binary framing.)*