plotter/docs/building-and-testing.md

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

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 377 cases in the linux-debug preset; its harness prints one line per case and a final 377 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=<substring> 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 377 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/<adapter>/, their targets in the same package).

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).

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

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, 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 360 of the 377 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).