# 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 **396 cases** in the `linux-debug` preset; its harness prints one line per case and a final `396 cases, 0 failed` summary line. The case counts per file are the `PLOT_TEST(...)` declarations under `tests/` — recount them (`grep -c '^PLOT_TEST(' tests/test_*.cpp`) after adding or removing cases. `PLOT_TEST_FILTER=` runs only the cases whose name contains that substring, and is for working *on* a case rather than for checking the library: most of the render cases create their own EGL context and read pixels back, so the whole binary is far slower than the one case being edited and its one line of measured output scrolls past 376 others. The summary line still counts the whole suite, so a filtered run says `396 cases, 0 failed` having run one — it is never evidence that the suite passes. Unset, every case runs. ## Install layout `cmake --install` follows `GNUInstallDirs`, so every path honours the standard cache variables (`CMAKE_INSTALL_LIBDIR`, `CMAKE_INSTALL_INCLUDEDIR`, …) and their distribution defaults — plain `lib`, `include` and `share` unless a packager overrides them: | prefix-relative path | what | |---|---| | `lib/` | the `plot_core` archive (and `libplot_core.so` with its version and SONAME symlinks when built with `BUILD_SHARED_LIBS=ON`) | | `include/plot/` | every public header, including the generated `plot/version.hpp` (`plot::version::major/minor/patch/string` and the `PLOT_VERSION_*` macros) | | `lib/cmake/plot/` | the CMake package: `plotConfig.cmake`, `plotConfigVersion.cmake` (Compatibility **SameMinorVersion**, so `find_package(plot 0.1 …)` accepts 0.1.x only), `plotTargets.cmake` | | `lib/pkgconfig/plot.pc` | pkg-config metadata for consumers whose build is not CMake | | `share/licenses/plot/` | `LICENSE` (MIT) and `licences/OFL-1.1.txt` (the embedded font) | Adapters that were built and exported install themselves alongside the core (their headers under `include//`, their targets in the same package). ## Headless demo modes Each demo supports two environment variables, implemented once and reused: - `PLOT_DEMO_EXIT_AFTER_MS=` — 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=` — 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=` | `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. This page carries no measured totals — a number written here would be stale the moment `src/` moved, and the report is reproducible: the method, the per-file table and the floor verdict live in [docs/coverage.md](coverage.md), which `tools/coverage.sh` rewrites from the very run that measured them. Re-run the command for the live numbers. **One thing to know about the coverage preset:** it builds **379 of the 396 cases**. The 17 that are missing are the adapter cases that need an adapter target to exist — 11 in `test_imgui_widget.cpp` and 6 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` (5 cases) and `test_gtk_input.cpp` (11 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).