# 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](https://github.com/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):

```bash
# 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):

```bash
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.