7b097fbdd1
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m2s
API Docs / doc-build (pull_request) Successful in 46s
Markdown link check / check (pull_request) Successful in 47s
C++ Tests / test-cgal (pull_request) Failing after 10m51s
C++ Tests / quality-gates (pull_request) Successful in 2m21s
Two reviewer-facing additions:
1. New `quality-gates` job in .gitea/workflows/cpp-tests.yml
──────────────────────────────────────────────────────────
Runs in parallel with test-cgal after test-fast. Installs
`codespell` + `shellcheck` (apt) into the existing ci-cpp container,
then executes four scripts strictly (exit 1 on any finding):
* license-headers.sh — 66/66 files carry SPDX MIT
* cgal-conventions.py — 0 violations across 6 CGAL public headers
* codespell.sh — 0 typos across docs + source + scripts
* shellcheck.sh — 0 findings across 16 shell scripts
Each ran at 0 findings locally for weeks before promotion. The
gates are now contractual: a regression fails the PR. Total
wall-time on the eulernest runner: ~30 s.
2. New code/deps/THIRD-PARTY-LICENSES.md
──────────────────────────────────────
Enumerates every vendored dependency under code/deps/, plus the
auto-fetched GoogleTest, plus the system-required Boost, with:
* upstream project + version + SPDX identifier
* compatibility note for MIT distribution
* a downstream-packager license matrix (header-only consumer
vs CLI binary) clarifying the LGPL §3 vs §4 distinction
relevant to CGAL's header-only consumption
Required for any future Linux-distribution packaging and for the
CGAL submission's compliance check. Cross-referenced from
doc/architecture/dependencies.md.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
152 lines
7.8 KiB
Markdown
152 lines
7.8 KiB
Markdown
# 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.
|