Building

Building

Prerequisites (Arch Linux host)

sudo pacman -S docker qemu-user-static binfmt-qemu-static
sudo systemctl enable --now docker
sudo systemctl restart systemd-binfmt

For other distros, install the equivalent packages for Docker, qemu-user-static, and binfmt support for aarch64.

Build the application binary

./scripts/build-app.sh

This runs an ARM64 Docker container (QEMU-emulated on x86_64), installs all dependencies, compiles the C++17 source, strips the binary, and extracts artifacts to deploy/install/.

Output binary: deploy/install/usr/local/bin/microscopi

Build the full OS image

./scripts/build-image.sh

Runs pi-gen inside Docker. Produces a compressed image in deploy/. Flash with:

./scripts/flash.sh /dev/sdX

Note: Flashing requires write access to a raw block device. Run the flash script yourself — do not give the application root access to do it.

Deploy a new binary to a running Pi

# Copy binary to Pi home dir
scp deploy/install/usr/local/bin/microscopi microscopi@<pi-ip>:~/microscopi

# On the Pi:
sudo mv ~/microscopi /usr/local/bin/microscopi
sudo systemctl restart microscopi

Deploy a new config

The application checks ~/.config/microscopi.conf before /etc/microscopi.conf:

scp deploy/install/usr/local/etc/microscopi.conf microscopi@<pi-ip>:~/.config/microscopi.conf

No restart needed if you only changed display/crop/key settings (they take effect on next launch). A camera or video backend change requires a restart.

Unit tests (host build)

cmake -S . -B build-tests -DBUILD_TESTS=ON
cmake --build build-tests
ctest --test-dir build-tests --output-on-failure

Tests cover: INI config parser, key binding parser, shutter/ISO ladder logic. CI runs these on every push via GitHub Actions.

clangd / LSP

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
ln -sf build/compile_commands.json compile_commands.json