twislaandClaude Sonnet 5.5
3b4100dc6a
/dev/ has Debug Builds and the Debug Console (builds and the token, the console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, the command reference), Build, test and release (including how an update works), the architecture decisions and the milestone plans. Generated from the repository by site/tools/gen_dev_docs.py: the ADRs, the milestones, the README's sections, and the command reference, read from the firmware's own `help` text. The pages are committed (Zola cannot read outside its folder); the Site workflow checks they are current, and now also runs when src/main.cpp changes. M0, M1 and CONTEXT.md are not published. README: the gnss commands that the table lacked. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2.2 KiB
+++ title = "Build, test and release" description = "Docker is the only tool you need. How the firmware is built, how the host tests run, and what CI does on a pull request and on a tag." weight = 1
[extra] docs = true source = "README.md" tag = "Build" +++
Requirements
Only Docker is needed. PlatformIO and the ESP32 toolchain run inside a container, and are cached in the roro9stack-pio Docker volume. The first build downloads about 1 GB and takes a few minutes.
Build and test (local CI)
scripts/ci.sh
This runs the host-side unit tests (test/, native environment), then builds the firmware. The output is .pio/build/cardputer-adv/firmware.factory.bin.
scripts/coverage.sh runs the same tests with coverage counters and writes a line-by-line report to .pio/coverage/index.html. The badge above is its figure for main: the share of the lines of lib/ that the host tests run. lib/ is the logic that compiles on a PC; lib/SD (the card's driver) and src/ (the Apps, the Services, everything that needs the device) have no host tests and aren't in that figure.
The framework is rebuilt with the TLS settings in platformio.ini (custom_sdkconfig, ADR 0006), so the first build after a fresh checkout takes about 4 minutes; later builds take under a minute.
CI and releases
Gitea Actions (.gitea/workflows/ci.yml, docs/milestones/R1.md) runs the host tests on every push to main, and on a pull request also builds the release firmware and the Debug Build: changes reach main through pull requests. Pushing a tag v* runs all of it and publishes a release on Gitea with:
roro9stack-<version>.ota, the signed Update File;roro9stack-<version>-factory.bin, the whole flash image for a first install over USB;roro9stack-<version>.elf.gz, to decode crash reports from that build;SHA256SUMS.
CI signs with the project's key, held as a repository secret (ADR 0008). Debug Builds are built but never published: each carries its builder's Debug Console token.
scripts/ota_verify.py <file.ota> checks an Update File on a PC the way a device does. scripts/release_build.sh and scripts/release_publish.py are what the workflow runs; they work the same by hand.