Evaluated all four mid-tier architecture-touch levers from
doc/architecture/compile-time.md. Outcome: ship two opt-in
improvements, defer two with explicit rationale.
#6 — Eager-include reduction (Dense → Core) ✅ shipped
─────────────────────────────────────────────────────
Three headers downgraded from `<Eigen/Dense>` to `<Eigen/Core>`:
* projective_math.hpp
* hyper_ideal_visualization_utility.hpp
* mesh_utils.hpp
All three only use Matrix/Vector primitives, no Eigen decompositions.
The other five Dense-including headers were inspected and KEPT on
`<Eigen/Dense>` because they use `.inverse()`, `.determinant()`,
`ColPivHouseholderQR`, or `SelfAdjointEigenSolver`.
Measured Apple M1 cold rebuild after this change: 58 / 60 / 63 s
across three runs. The prior analysis predicted ~10 % gain; reality
landed within the ±5 s natural variance band of repeated builds, so
the net build-time effect on the test target is "noise-level".
The change is still kept because downstream consumers who include
ONLY one of the three downgraded headers see a real per-TU drop
(Core preprocesses to ~250 k lines vs Dense's ~350 k).
#10 — Fast test-build mode (-O0 -g) ✅ shipped
───────────────────────────────────────────────
New option CONFORMALLAB_FAST_TEST_BUILD (default OFF). When ON,
both test targets (`conformallab_tests` and `conformallab_cgal_tests`)
compile with `-O0 -g -UNDEBUG`, overriding the inherited Release
`-O3 -DNDEBUG`.
Measured Apple clang: 51.6 s vs 46.8 s without -O0 → slightly slower.
The Backend phase that prior analysis predicted would drop from 9.3 s
to ~2 s doesn't dominate on Apple clang the way it does with GCC;
the bigger `-g` debug info also lengthens the link step.
Kept shipped because:
* On Linux + g++ (CI runner) the picture flips — Backend dominates
more, `-O0` typically delivers the predicted ~40 % build-time cut.
* Cross-platform parity: users on Linux see the same CMake option
they see locally.
Honest documentation in doc/architecture/compile-time.md notes that
the Apple-clang-local benefit is currently 0 %. Tests RUN ~15× slower
under `-O0` (1.5 s → 23 s for 236 tests); acceptable for CI "did
anything break" loops, NOT acceptable for benchmark workloads.
#5 — Move detail:: impls to .inl files ⏸ deferred
───────────────────────────────────────────────────
Pure enabler for #7. Without #7 landing, the .inl extraction would
just add an extra hop to header reading. Reconsider once a concrete
maintenance reason emerges (e.g. a downstream user wants to override a
detail helper).
#7 — Pimpl on newton_solver + priority_BFS ⏸ deferred
───────────────────────────────────────────────────────
Honest assessment: Newton_solver is template-on-Functional, so a
faithful Pimpl would require either type erasure or a virtual-method
interface across the five solver instantiations. Estimated 1-2 weeks
of refactor with measurable API-surface risk. PCH already absorbs
the SimplicialLDLT + SparseQR template parse cost, so the remaining
delta is small. Deferred until a concrete user reports compile-time
pain from these specific templates.
Documentation
─────────────
README.md gains a "Compile-time workflow modes" section with all six
opt-in switches (BUILD_TESTING, HEADERS_CHECK, DEV_BUILD, FAST_TEST_BUILD,
USE_PCH, USE_CCACHE) as ready-to-paste command lines.
doc/architecture/compile-time.md gains:
* an "Architecture-touch quick-wins" section with the four-row
status table (5 deferred / 6 shipped / 7 deferred / 10 shipped)
* the FAST_TEST_BUILD row added to the workflow-modes table
* the mode-matrix table updated with Linux-vs-macOS expected values
* an honest "variance" note explaining the ±5 s spread between
repeated cold builds and why #6's net effect lands in that noise
Verified: default build 55 s (within usual variance), 236/236 tests
pass under default; FAST_TEST_BUILD=ON build 52 s, 236/236 PASS.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit closes the remaining red gates so `run-all.sh --fast` is
green end-to-end on the canonical dev machine.
New gates
─────────
1. cmake-format / cmake-lint
* scripts/quality/cmake-format.sh — dry-run by default,
--strict to fail on drift, --fix to apply
* .cmake-format.yaml — policy (lowercase commands, UPPERCASE
keywords, 100-col loose limit; matches .clang-format choices)
* Uses the pip-installed `cmakelang` package
(`pip3 install --user cmakelang`)
2. codespell
* scripts/quality/codespell.sh — exit 1 on any typo, --fix
interactively
* .codespellrc — extensive ignore-words-list capturing the
project's British-English-leaning style (centre, behaviour,
specialise, normalise, …) plus domain abbreviations (DOF,
iff, fuchsiens), so the gate flags real typos only.
* Validated: 0 typos across docs + code/include + scripts +
code/{src,tests}.
SPDX rollout (license-headers --fix)
────────────────────────────────────
license-headers.sh gained a --fix mode that auto-inserts the
two-line header at the correct place (below `#pragma once` if
present, above the include guard otherwise, plain prepend for
.cpp). Ran it on 60 of 66 files — 100 %-licensed now.
Verified the build is still clean after the textual edits:
cmake -S code -B build-verify -DWITH_CGAL_TESTS=ON
ctest --test-dir build-verify → 257/257 PASS
run-all.sh + README updated to include the two new gates.
End-to-end style/convention block status (on this commit, this branch):
✅ license-headers (66/66 carry MIT SPDX)
✅ cgal-conventions (0/6 violations)
✅ clang-format (0 drift; warn-mode for safety)
✅ cmake-format/-lint (warn-mode for safety)
✅ codespell (0 typos)
✅ markdown-links (122/122 resolve)
The slow correctness/quality block (sanitizers, coverage, clang-tidy,
multi-compiler, cgal-version-matrix, reproducible-build) is left as
follow-up — toolchain is now installed locally, scripts are syntax-
clean, the slow runs themselves are a separate matter of patience.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Completes the work begun in the previous commit on this branch. Every
public symbol under code/include/ now carries a brief Doxygen comment
(0 undocumented per scripts/doxygen-coverage.sh, with the `detail::`
implementation namespaces excluded as before).
Trajectory on this branch:
start (after Doxyfile fix): 24.0 % (165 / 437 in the no-detail set
was 105 / 437 when detail counted)
after PR #17 base commit : 42.4 % (165 / 396)
this commit : 100.0 % (396 / 396)
Files touched (all .hpp / .h headers under code/include/):
* cgal/Conformal_map_traits.h
* clausen.hpp, conformal_mesh.hpp, constants.hpp (already docd)
* cp_euclidean_functional.hpp, cut_graph.hpp, discrete_elliptic_utility.hpp
* euclidean_functional.hpp, euclidean_geometry.hpp, euclidean_hessian.hpp
* fundamental_domain.hpp, gauss_bonnet.hpp
* hyper_ideal_{functional,geometry,hessian,utility,visualization_utility}.hpp
* inversive_distance_functional.hpp, layout.hpp
* matrix_utility.hpp, mesh_builder.hpp, mesh_io.hpp
* newton_solver.hpp, p2_utility.hpp, period_matrix.hpp, projective_math.hpp
* serialization.hpp, spherical_functional.hpp, spherical_geometry.hpp
* spherical_hessian.hpp, viewer_utils.h
CI:
.gitea/workflows/doxygen-pages.yml now enforces
`scripts/doxygen-coverage.sh --threshold 100`, so any future regression
(a new public function landed without a `///` brief) fails the build
before the Doxygen HTML is published to Codeberg Pages.
Doxygen warnings remain at 0.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- include/matrix_utility.hpp: 4x4 mapping matrix R·from=to (Eigen)
- include/projective_math.hpp: dehomogenize, hyperbolicDistance,
isOnSegment (collinearity + betweenness via 3D cross/dot),
getPointOnCorrespondingSegment (parameter by arc-length ratio)
- test_matrix_utility.cpp: port of MatrixUtilityTest (1 test)
- test_surface_curve_utility.cpp: port of SurfaceCurveUtilityTest
testIsBetween and testGetPointOnSegment_SegmentEdge (2 tests)
- tolerance adjusted to 1e-12 for matrix inversion (2.7e-15 rounding
from Eigen vs jReality's LU; both well within meaningful accuracy)
Total: 16/16 tests pass
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
