7.7 KiB
Important
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.
Building & Installation Guide
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=imx219enabled in/boot/firmware/config.txt) - Sony IMX219 camera module verified with
rpicam-hello --list-cameras APPLaunchapplication launcher and/dev/fb0+cp0-keysevdevinput device- Runtime
.debdependencies (declared inpackaging/debian/control):python3 (>= 3.9)python3-picamera2ffmpegalsa-utils(aplay)libjpeg62-turbo | libjpeg8libfreetype6libc6,libstdc++6
Note:
czcameraintentionally has no dependency oncp0-syncand no direct C++ linkage tolibcamera0*orlibcamera.so.
Docker Cross-Build Host (macOS / Linux)
- Docker Desktop (or Docker Engine with
linux/arm64emulation /buildx)
Desktop Simulator Build (macOS / Linux)
- CMake
>= 3.16and a C++17 compiler (clang++org++) pkg-configlibjpeg(libjpeg-turbovia Homebrewjpeg-turbo/libjpegor Debianlibjpeg62-turbo-dev)SDL2(sdl2via Homebrew orlibsdl2-dev)- Optional:
FreeType2(freetype/libfreetype-dev) for crisp antialiased UI fonts (falls back automatically to the built-in5×7bitmap renderer if absent) - Optional:
ffmpeg&ffprobeonPATHfor desktop Timelapse MP4 compilation and Gallery.mp4playback tests - Python
>= 3.9for running helper/packaging test suites
2. Building the ARM64 Debian Package (.deb)
Use packaging/build-deb.sh in one of four supported modes:
./packaging/build-deb.sh --help
Option A: Docker linux/arm64 Build (Recommended on macOS / x86_64)
Builds a clean debian:bookworm-slim (linux/arm64) container via 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:
./packaging/build-deb.sh
Why
-O2without global-DNDEBUG: the ARM64 verification step runs the C++ctestbinaries (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):
./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):
./packaging/build-deb.sh --stage-only /tmp/czcamera-stage --bin /path/to/czcamera
Flags supported by build-deb.sh:
| Flag | Description |
|---|---|
--local |
Build app/build-arm64 natively on Linux ARM64 and package .deb |
--stage-only <dir> |
Stage package files into <dir> with target permissions and exit |
--bin <path> / --ui-bin <path> |
Supply a prebuilt czcamera binary (--ui-bin is an alias for --bin) |
--out-dir <dir> |
Output directory for .deb (default: packaging/dist/) |
-h, --help |
Show usage help |
Optional TrueType Font Bundling
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:
scp packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-host>:/tmp/
ssh pi@<cardputerzero-host> 'sudo dpkg -i /tmp/czcamera_1.0.0_m5stack1_arm64.deb && sudo apt-get install -f'
Installed Layout
| Destination Path | Mode | Role |
|---|---|---|
/usr/bin/czcamera |
0755 |
C++17 320×170 fbdev + evdev camera application binary |
/usr/bin/czcamera-cam |
0755 |
Python 3 camera worker launcher (python3-picamera2) |
/usr/lib/czcamera/czcamera_cam/*.py |
0644 |
Protocol, FramePipeWriter, Picam2Worker, and mock driver modules |
/usr/share/APPLaunch/applications/czcamera.desktop |
0644 |
APPLaunch launcher entry (Name=czcamera, Exec=/usr/bin/czcamera) |
/usr/share/APPLaunch/share/images/czcamera.png |
0644 |
80×80 Zinc dark camera launcher icon |
/usr/share/czcamera/fonts/*.ttf (optional) |
0644 |
Optional bundled UI fonts |
Sanity Checks on Device
Verify shared libraries (libjpeg.so.62 / libfreetype.so.6 present, zero libcamera.so linkage) and camera visibility:
ldd /usr/bin/czcamera
rpicam-hello --list-cameras
Launch czcamera from the APPLaunch grid, or test from TTY/SSH:
/usr/bin/czcamera
Uninstalling
sudo apt-get remove czcamera
packaging/debian/prerm automatically cleans Python __pycache__ bytecode under /usr/lib/czcamera on package removal or deconfiguration.
4. Building & Running the Desktop SDL2 Simulator
Configure and build on macOS or Linux desktop:
cmake -S app -B app/build -DCZ_BUILD_APP=ON -DCZ_BUILD_TESTS=ON
cmake --build app/build
Run the interactive 320×170 SDL2 simulator (defaults to SimCameraBackend when --sim or --mock-cam is given):
./app/build/czcamera --sim --scale 3
Render headless P6 320×170 PPM snapshots (163215 bytes each) for CI or visual inspection:
./app/build/czcamera --render-test /tmp/cz_photo.ppm --theme dark --mode photo --rail right
./app/build/czcamera --render-test /tmp/cz_light_left.ppm --theme light --mode photo --rail left
./app/build/czcamera --render-test /tmp/cz_video.ppm --theme dark --mode video
./app/build/czcamera --render-test /tmp/cz_timelapse.ppm --theme dark --mode timelapse
./app/build/czcamera --render-test /tmp/cz_gallery.ppm --theme dark --mode gallery
./app/build/czcamera --render-test /tmp/cz_settings.ppm --theme dark --mode settings
CMake Build Options
| Option | Default | Effect |
|---|---|---|
CZ_BUILD_APP |
OFF |
Build the czcamera executable in addition to czcamera_core |
CZ_TARGET_DEVICE |
OFF |
Build Linux /dev/fb0 + cp0-keys evdev backend instead of SDL2 (Linux only) |
CZ_BUILD_TESTS |
ON |
Build the 5 ctest suites |
CZ_ENABLE_LVGL |
OFF |
Link optional lvgl::lvgl (CP0_HAS_LVGL=1) if available |
5. Running Test Suites
Run all three suites cleanly from the repository root:
# C++ unit & integration tests (5 suites)
ctest --test-dir app/build --output-on-failure -V
# Python camera helper & mock-driver IPC tests (18 tests, warnings-as-errors)
PYTHONPATH=cam-helper python3 -W error -m unittest discover -s cam-helper/tests -v
# Packaging metadata, icon, maintainer script & staging tests (4 tests)
python3 -m unittest discover -s packaging/tests -v
(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.)