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 350 cases in the linux-debug preset; its harness prints one line per case and a final 350 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.

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 333 of the 350 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).