ConformalLabpp/doc/architecture/dependencies 2.md

Dependencies & standalone-ness

This document is the single source of truth for "what does conformallab++ require vs. what does it optionally use". Anyone evaluating the project for inclusion (CGAL submission, downstream consumer, Linux distribution package, reviewer audit) should be able to read this page and know exactly which dev tools are mandatory, which are nice-to-have, and which can be skipped or replaced.

TL;DR

Layer	What is required	What is optional
Library use (header-only, end-user code includes our headers)	C++17 compiler, CMake ≥ 3.20, Eigen ≥ 3.4 (headers), CGAL ≥ 5.6 (headers), Boost ≥ 1.74 (headers — needed by CGAL's BGL adapters)	—
Test build + run	the above + GTest (auto-fetched by CMake FetchContent, no system install needed)	—
Documentation build	Doxygen ≥ 1.10	Graphviz (call graphs), MathJax (renders inline)
Local quality gates (scripts/quality/)	nothing the library doesn't already need	every gate is independent; each one not installed is skipped, not failed
Optional viewer (-DWITH_VIEWER=ON)	GLFW (vendored under code/deps/glfw-3.4), libigl, OpenGL system headers	—

The library itself is header-only. There is no compiled .so / .a / .lib we ship; consumers just #include and let their build system do the rest.

Library deps (required to build/use the C++ headers)

Dep	Version	Header-only?	Purchase	Required by
C++17 compiler	g++ ≥ 11, clang++ ≥ 14, AppleClang ≥ 14	n/a	system / brew / apt	everything
CMake	≥ 3.20	n/a	system / brew / apt	build orchestration
Eigen	≥ 3.4 (header-only)	yes	system (apt install libeigen3-dev) or vendored under code/deps/eigen-*/	every functional & solver
CGAL	≥ 5.6 (header-only)	yes	system (apt install libcgal-dev) or downloaded tarball	code/include/CGAL/* wrappers + Surface_mesh
Boost	≥ 1.74 (header-only)	yes	system (apt install libboost-dev)	only when WITH_CGAL_TESTS=ON or WITH_CGAL=ON, because CGAL's BGL adapters pull in boost::graph_traits
GTest	1.14	yes (auto-fetched)	FetchContent_Declare in code/CMakeLists.txt — never installed system-wide	tests only

Notes:

• The library headers in code/include/*.hpp use only Eigen + STL.
• The CGAL wrapper headers in code/include/CGAL/*.h add CGAL + Boost (transitively).
• code/deps/single_includes/json.hpp is the vendored nlohmann/json header — used by serialization.hpp only. No system install needed.

Build modes — what each requires

Mode	CMake invocation	Extra system deps
Fast / pure-math tests (default)	cmake -S code -B build	none beyond C++17 + CMake
CGAL headless tests	cmake -S code -B build -DWITH_CGAL_TESTS=ON	Boost headers
Full build (CLI + viewer)	cmake -S code -B build -DWITH_CGAL=ON	Boost + Wayland/X11 dev headers
Coverage / sanitizers / etc.	see scripts/quality/	per-script (each documents its prereqs and skips if missing)

The -DWITH_* flags all default to OFF. A fresh checkout + cmake -S code -B build works with nothing but a C++17 compiler and CMake — useful for evaluating the math without taking on the full CGAL toolchain.

Local quality gates — all optional, each independently skippable

scripts/quality/ contains 12 gate scripts. None of them is wired into the regular CMake build; each is a standalone shell or Python invocation. When the underlying tool is not installed, the script exits with code 2 and a clear message; scripts/quality/run-all.sh recognises this as SKIP, not FAIL.

Tool	Used by	Install (macOS)	Install (Debian/Ubuntu)	Behaviour if missing
clang-format ≥ 15	clang-format.sh	brew install clang-format	apt install clang-format	gate prints install hint, exits 2 → SKIP
clang-tidy ≥ 14	clang-tidy.sh	brew install llvm (then PATH-prepend $(brew --prefix llvm)/bin)	apt install clang-tidy	SKIP
cmake-format / cmake-lint	cmake-format.sh	pip3 install --user cmakelang + PATH-prepend ~/.local/bin	pip3 install --user cmakelang	SKIP
codespell	codespell.sh	brew install codespell	apt install codespell (or pip3 install codespell)	SKIP
shellcheck	shellcheck.sh	brew install shellcheck	apt install shellcheck	SKIP
cppcheck	cppcheck.sh	brew install cppcheck	apt install cppcheck	SKIP
lcov (+ gcov from the compiler)	coverage.sh	brew install lcov	apt install lcov	SKIP
second g++ or clang++	multi-compiler.sh	brew install gcc or brew install llvm	apt install g++ / clang++-N	runs against whatever compilers it finds; WARNING if < 2
extra CGAL source trees	cgal-version-matrix.sh	manually git clone under ~/cgal/<ver>/ (or pass CGAL_ROOTS=...)	same	exits 2 → SKIP with explicit recovery hint

How to disable a gate temporarily

Two options:

1. Don't install the tool — run-all.sh skips it.
2. Remove the line from GATES_FAST / GATES_SLOW in run-all.sh — the script is a 5-line edit; no separate "disabled" flag system.

There is no global "disable all quality gates" switch by design. If the gates feel heavy, run only the fast subset (run-all.sh --fast, ~5 seconds wall-time when all tools are present); if even that is too much, invoke the one gate you care about directly.

CONFORMALLAB_WARNINGS_AS_ERRORS — the only CMake-level quality flag

By default the build adds -Wall -Wextra -Wpedantic but does not fail on warnings. Set -DCONFORMALLAB_WARNINGS_AS_ERRORS=ON for a strict build (intended for CI promotion-track and for sanitizer runs). Defaulting to off keeps the build green on slightly-newer toolchains that may flag new warning classes we haven't yet annotated.

CI gates (active on every PR via .gitea/workflows/)

These run inside the git.eulernest.eu/conformallab/ci-cpp:latest container, so the tools are baked into the image — contributors do not need any of them locally:

Gate	Workflow file
ctest (fast + CGAL suites)	cpp-tests.yml
test-count consistency	same
End-to-end try_it.sh	same
Markdown link check	markdown-links.yml
Doxygen build + Codeberg Pages publish	doxygen-pages.yml
Mirror to Codeberg	mirror-to-codeberg.yml

The local quality gates under scripts/quality/ are not in CI today. Each one's promotion path is documented in scripts/quality/README.md.

Verification of the standalone claim

Test recipe (any UNIX, ~30 s):

# Strip PATH down to system + brew core (no quality tools).
env -i PATH="/usr/bin:/bin:/opt/homebrew/bin" HOME="$HOME" \
    cmake -S code -B /tmp/build-standalone

# Build the fast test suite.
cmake --build /tmp/build-standalone --target conformallab_tests

# Run them.
ctest --test-dir /tmp/build-standalone -E "^cgal\."

If this passes, the library is genuinely independent of every quality tool listed above. Tested locally on macOS-arm64 — green.

For the CGAL-mode equivalent (adds Boost headers as a system dep):

env -i PATH="/usr/bin:/bin:/opt/homebrew/bin" HOME="$HOME" \
    cmake -S code -B /tmp/build-cgal -DWITH_CGAL_TESTS=ON
cmake --build /tmp/build-cgal --target conformallab_cgal_tests
ctest --test-dir /tmp/build-cgal -R "^cgal\."

What is not in this repo (out of scope)

• No package-manager metadata (Debian .deb, RPM, Conan, vcpkg, …) — yet. Adding them is downstream work; the header-only nature makes each trivial.
• No language bindings (Python, …) — out of scope; the library is C++.
• No GPU compute path — out of scope; numerical work is CPU-only.