docs: a user guide covering getting started, architecture, embedding, data, interaction, styling and testing
This commit is contained in:
Martino Ferrari committed
1 parent
d03f9ce51a
commit
b7d0f901cc
7 files changed
+1082
No files matched your search
@@ -0,0 +1,109 @@
|
||||
# Building and testing
|
||||
|
||||
## Presets and options
|
||||
|
||||
Four configure/build presets live in `CMakePresets.json`:
|
||||
|
||||
| preset | binaryDir | what it builds |
|
||||
|---|---|---|
|
||||
| `linux-debug` | `build/debug` | Debug; tests, examples and all four adapters |
|
||||
| `linux-release` | `build/release` | Release; `PLOT_BUILD_TESTS=OFF` (so the installed `libplot_core.a` carries none of the test-only counter instrumentation); examples and all four adapters |
|
||||
| `linux-asan` | `build/asan` | Debug with `PLOT_SANITIZE=address`; tests and all four adapters |
|
||||
| `linux-coverage` | `build/cov` | the instrumented tree behind `tools/coverage.sh`: `--coverage -O0 -g`, `PLOT_COVERAGE=ON`, tests on, adapters and examples off |
|
||||
|
||||
The options (`cmake/plot_options.cmake`) and their defaults:
|
||||
|
||||
| option | default | meaning |
|
||||
|---|---|---|
|
||||
| `PLOT_BUILD_TESTS` | `ON` | build the test suite (needs EGL) |
|
||||
| `PLOT_BUILD_EXAMPLES` | `OFF` | build the demos |
|
||||
| `PLOT_BUILD_GLFW` | `OFF` | build the GLFW adapter and its demo |
|
||||
| `PLOT_BUILD_IMGUI` | `OFF` | build the Dear ImGui adapter and its demo (ImGui is fetched at configure time) |
|
||||
| `PLOT_BUILD_QT6` | `OFF` | build the Qt6 adapter and its demo |
|
||||
| `PLOT_BUILD_GTK4` | `OFF` | build the GTK4 adapter and its demo |
|
||||
| `PLOT_BUILD_TTF_FONT` | on iff `third_party/stb_truetype.h` exists | build the optional `plot::text::TrueTypeFont` backend |
|
||||
| `PLOT_INSTALL` | `ON` | generate install/export rules for `find_package(plot)` |
|
||||
| `PLOT_SANITIZE` | `""` | sanitizer list for `-fsanitize=` (e.g. `address`) |
|
||||
| `PLOT_COVERAGE` | `OFF` | add the `coverage` target (requires an instrumented tree) |
|
||||
|
||||
Adapters and examples are off by default, so the core library and its tests build on a bare
|
||||
toolchain. Each example is guarded by the adapter target it needs, so
|
||||
`-DPLOT_BUILD_EXAMPLES=ON` without the matching adapter is a no-op rather than a configure
|
||||
error.
|
||||
|
||||
## Running the suite
|
||||
|
||||
```sh
|
||||
cmake --preset linux-debug
|
||||
cmake --build build/debug
|
||||
ctest --test-dir build/debug --output-on-failure
|
||||
```
|
||||
|
||||
ctest registers four tests: `plot_tests` (the test binary), the two header/umbrella build
|
||||
checks (`plot_headers_self_contained`, `plot_umbrella_covers_public_headers`) and
|
||||
`plot_umbrella_check`. The `plot_tests` binary itself runs **283 cases** in the `linux-debug`
|
||||
preset; its harness prints one line per case and a final `283 cases, 0 failed` summary line.
|
||||
The case counts per file are the `PLOT_TEST(...)` declarations under `tests/`.
|
||||
|
||||
## Headless demo modes
|
||||
|
||||
Each demo supports two environment variables, implemented once and reused:
|
||||
|
||||
- `PLOT_DEMO_EXIT_AFTER_MS=<n>` — stop the loop after `n` milliseconds and return. Unset,
|
||||
unparsable or not positive means "run until the window is closed". A run with a deadline
|
||||
creates its window hidden, so an automated run never flashes a window on a real display,
|
||||
and its frame times are not throttled by a vblank.
|
||||
- `PLOT_DEMO_SCREENSHOT=<path>` — on that final frame, write it as a binary PPM before the
|
||||
swap. The GLFW host writes the framebuffer with `Renderer::dump_frame_ppm()`; the ImGui
|
||||
demo writes the whole framebuffer, while Qt and GTK write their widget's/area's own
|
||||
framebuffer (their toolkits' chrome lives outside it).
|
||||
|
||||
That pair is what lets CI run the GUI demos under `xvfb-run` with no display access and no
|
||||
screen capture (the invocations are in [embedding.md](embedding.md)).
|
||||
|
||||
Three demos add env-gated **self-checking** modes. These are verification affordances for
|
||||
the project's own testing, driven through the real host and its own controllers — they are
|
||||
not a second implementation of anything, and they exit non-zero if a measured property fails:
|
||||
|
||||
| variable | demo | what it drives |
|
||||
|---|---|---|
|
||||
| `PLOT_DEMO_FOLLOW=1` | `plot_glfw_demo` | the live-follow sequence: three wheel notches and a pan on a `XFollow::Live` axis, printing the range width, the distance behind the newest sample and the follow state at each step |
|
||||
| `PLOT_DEMO_REGIONS` (`=hot` to hover a bound) | `plot_glfw_demo` | the direct-manipulation sequence: freeze the view, place a region, pan 100 px with the press outside it, and check the region came along with its width untouched |
|
||||
| `PLOT_DEMO_SYNC=1` | `plot_multiplot_demo` | the synced-follow check: the three rows hold one range and its right edge keeps tracking the newest sample through a zoom and a pan on different rows |
|
||||
| `PLOT_DEMO_CROSSHAIR=<row>` | `plot_multiplot_demo` | parks the pointer in a row each frame so a headless screenshot shows the one horizontal line the hovered row draws |
|
||||
|
||||
(`plot_glfw_demo` also accepts `PLOT_DEMO_CROSSHAIR=1`, which parks the pointer at the centre
|
||||
of the data area so the two-line crosshair has ink to measure.)
|
||||
|
||||
## Coverage
|
||||
|
||||
```sh
|
||||
tools/coverage.sh # from the repository root
|
||||
cmake --build build/cov --target coverage # the same thing, through CMake
|
||||
```
|
||||
|
||||
The script configures `build/cov` from the `linux-coverage` preset, builds it, clears the
|
||||
`.gcda` counters, runs the whole suite, captures `src/**` with `lcov`, renders an HTML report
|
||||
to `build/cov/html/index.html`, prints the per-file table, and **exits non-zero when a floor
|
||||
is violated**. It needs `cmake`, `ninja`, `ctest`, `lcov`, `genhtml` and `python3`, and exits
|
||||
`2` with a message when one is missing.
|
||||
|
||||
The floors are enforced by `tools/coverage_floor.py`:
|
||||
|
||||
| scope | floor |
|
||||
|---|---|
|
||||
| every file under `src/` | **80%** of its instrumented lines |
|
||||
| `src/` as a whole | **90%** of instrumented lines |
|
||||
|
||||
Branch coverage is deliberately off. The current measurement (from `build/cov/coverage.info`,
|
||||
re-read with `python3 tools/coverage_floor.py build/cov/coverage.info`) is an **aggregate
|
||||
95.3% (3284/3447 lines)** over 23 files, every file at or above 80% — the floor is satisfied.
|
||||
The method, the full per-file table and the reproducibility notes are in
|
||||
[docs/coverage.md](coverage.md); re-run the command for the live numbers.
|
||||
|
||||
**One thing to know about the coverage preset:** it builds **272 of the 283 cases**. The 11
|
||||
that are missing are the adapter cases that need an adapter target to exist — 8 in
|
||||
`test_imgui_widget.cpp` and 3 in `test_glfw_host.cpp` — and the coverage preset turns the
|
||||
adapters off. The toolkit-free adapter seams still run there: `test_qt_pointer.cpp` (2 cases)
|
||||
and `test_gtk_input.cpp` (8 cases) compile without Qt or GTK. So the coverage number measures
|
||||
the library plus its unit suite, not the adapter bodies (which the headless demo runs cover).
|
||||
Reference in new issue
Block a user