A facial recognition login service for Linux.
docs: Document v4l2 feature flag and hardware-test workflow
The v4l2 module is opt-in via the `v4l2` feature on pareidolia-core, and
its hardware-touching tests are `#[ignore]`d. Neither convention is
discoverable without docs, and 'just test-hardware' is the kind of recipe
contributors will forget exists if it isn't surfaced in CONTRIBUTING.
Also adds `test-v4l2` for running the v4l2 module's hardware-free tests
(FourCC mapping, enumerate-on-empty-host) with the feature enabled.
Isaac Corbrey
(May 27, 2026, 10:46 AM EDT)
b002f2d5
9106f35c
+54
+37
CONTRIBUTING.md
+37
CONTRIBUTING.md
···
115
115
If a test passes when its target code is replaced with `unimplemented!()`,
116
116
it isn't a test. Mutation testing exists to surface that case.
117
117
118
+
### Hardware-dependent tests
119
+
120
+
Tests that require real hardware (a V4L2 camera node, eventually a CUDA
121
+
device, etc.) are marked `#[ignore = "requires …"]` so the default test
122
+
runner skips them. CI never runs them — it has no hardware. Locally:
123
+
124
+
```sh
125
+
just test-v4l2 # runs v4l2 module's hardware-free tests
126
+
just test-hardware # runs only the ignored / hardware-gated tests
127
+
```
128
+
129
+
If you touch a hardware-facing module (`pareidolia_core::camera::v4l2`,
130
+
later the inference backends, etc.), run `just test-hardware` on your
131
+
machine before requesting review. The PR description should call out
132
+
which physical devices the tests were exercised against.
133
+
134
+
### Feature flags
135
+
136
+
`pareidolia-daemon` defaults to the `v4l2` feature so a normal
137
+
`cargo build` (or `nix build`) produces a working binary with camera
138
+
capture wired in. `cargo build --no-default-features` opts out — what CI
139
+
uses, since its Nixery image doesn't ship libv4l / libclang / kernel
140
+
headers. CI threads this through via the `CARGO_ARGS` env var that the
141
+
justfile recipes read.
142
+
143
+
`pareidolia-core` itself keeps `v4l2` opt-in (default features are empty)
144
+
so consumers that only need the pipeline (mocks, format conversions, IPC
145
+
types) don't pay the build cost.
146
+
147
+
Note that `[workspace.dependencies]` sets `default-features = false` on
148
+
every internal crate. This is load-bearing: `cargo --workspace` unifies
149
+
features across the dep graph, and without that setting the daemon's
150
+
default-on `v4l2` would transitively re-enable itself for every dependent
151
+
crate (integration tests, PAM module) and negate the CI opt-out. Crates
152
+
that genuinely need another internal crate's default features can flip
153
+
`default-features = true` back on in their own dep entry.
154
+
118
155
## Source control
119
156
120
157
The canonical workflow uses [Jujutsu](https://jj-vcs.github.io/jj/) (`jj`).
+17
justfile
+17
justfile
···
28
28
test-unit:
29
29
cargo nextest run --workspace --lib {{cargo_args}}
30
30
31
+
# Hardware-dependent tests (marked #[ignore]). Requires real devices on the
32
+
# host: a V4L2 camera at /dev/video*, eventually a NIC for IPC, etc. Enables
33
+
# every hardware-touching feature (currently just `v4l2`) so the gated
34
+
# modules actually compile.
35
+
#
36
+
# CI never runs this; it's the developer's responsibility to run locally
37
+
# before merging anything that touches a hardware-facing surface.
38
+
test-hardware:
39
+
cargo nextest run -p pareidolia-core --features v4l2 --run-ignored only
40
+
41
+
# Unit tests with the v4l2 feature enabled. Runs the FourCC mapping tests and
42
+
# the always-on portions of the V4L2 backend without touching real hardware.
43
+
# Locally only; CI doesn't have libv4l / libclang configured in its Nixery
44
+
# image.
45
+
test-v4l2:
46
+
cargo nextest run -p pareidolia-core --features v4l2 --lib
47
+
31
48
# Everything the per-push CI job runs.
32
49
ci-fast: fmt-check lint test-unit
33
50