Continuous integration
The GitLab CI pipeline is defined in .gitlab-ci.yml. This page describes what it does; the file itself is the reference for the details.
The project runs on GitLab.com’s Free tier, which allows 400 compute minutes a month on GitLab-hosted runners. That budget shapes the pipeline: everyday pushes only run the quick checks, and the three release builds run only when a version is actually released.
On every push
| Check | What it does |
|---|---|
| Format | cargo fmt --check |
| Lint | cargo clippy with -D warnings: any warning fails the pipeline |
| Tests | cargo test (headless: the tests that need a GPU or a local photo corpus are skipped) |
| Documentation | Builds this book with mdBook 0.5.4; a page listed in SUMMARY.md but missing fails the build |
| Third-party licenses | Generates the license list with cargo-about and fails if a dependency uses a license not accepted in about.toml |
Cargo commands run with --locked, so an out-of-date Cargo.lock fails the pipeline instead of being silently updated.
On a release
When a push to main brings a new version section in CHANGELOG.md, the pipeline also builds, publishes and tags the release. Whether a push is a release is only known once the release:detect job has read the changelog, so the builds live in a child pipeline (ci/release-pipeline.yml) that this job generates and that the release job starts once every check has passed: an ordinary push spends its minutes on the checks only. The trigger and the steps are described in Releasing.
On other branches and in merge requests, a manual builds job runs the same three builds without releasing anything, to try a change to the build before merging it.
The builds all run on Linux runners:
| Platform | How it is built |
|---|---|
| Linux x86-64 | Built with cargo-zigbuild against glibc 2.31, so the binary runs on distributions as old as Ubuntu 20.04 and Debian 11 rather than only on the runner’s own glibc. |
| Windows x86-64 | Cross-compiled with the mingw-w64 toolchain (x86_64-pc-windows-gnu target). |
| macOS universal2 | Cross-compiled for Apple Silicon and Intel in one binary with cargo-zigbuild, using the official cargo-zigbuild container image, which bundles the macOS 11.3 SDK. A GUI app links against Apple’s system frameworks (AppKit, Metal…), whose SDK stubs Zig alone does not provide. The binary is packaged as an ad-hoc signed .app bundle that runs on macOS 11 and later. |
The ad-hoc signature is what lets the app run on Apple Silicon at all, which refuses unsigned native code. It is not a Developer ID signature, hence the Gatekeeper warning described in Installation.
Documentation deployment
This book is deployed to GitLab Pages by the pipeline of a release tag, so the published documentation always matches the latest released version rather than unreleased work on main. A manual job on main pipelines can republish it in between, for example to fix a typo. See Releasing.