14134b99ce
README.md: reduced from 703 to ~75 lines — what/why, status, quick start, minimal usage example, navigation table to doc/ files. doc/architecture/overall_pipeline.md: trimmed — roadmap, extension points, declarative pipeline YAML, and references sections removed (each now has its own dedicated file). Replaced with a link table. New files: doc/getting-started.md — build modes, single-test invocation, CLI doc/api/pipeline.md — full pipeline API with code for all 3 geometries doc/api/extending.md — new functionals, geometry modes, Java porting guide doc/api/contracts.md — processing unit preconditions/provides table doc/api/cgal-package.md — Phase 8 CGAL package design + YAML pipeline (TODO) doc/math/geometry-modes.md — Euclidean/Spherical/HyperIdeal comparison doc/math/references.md — all papers by module doc/roadmap/phases.md — Phases 1–10 with porting/research boundary doc/roadmap/java-parity.md — Java vs C++ feature parity table doc/contributing.md — language policy, test standards, release flow Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
143 lines
3.6 KiB
Markdown
143 lines
3.6 KiB
Markdown
# Getting Started
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Minimum | Notes |
|
|
|---|---|---|
|
|
| C++ compiler (GCC or Clang) | C++17 | GCC 11+ or Clang 14+ recommended |
|
|
| CMake | 3.20 | |
|
|
| Boost headers | 1.70 | Only for `-DWITH_CGAL_TESTS=ON` or `-DWITH_CGAL=ON` |
|
|
| Wayland/X11 dev headers | — | Only for `-DWITH_CGAL=ON` (viewer) |
|
|
|
|
All other dependencies (Eigen 3.4, CGAL 6.1.1, libigl 2.6, GLFW 3.4, GTest 1.14)
|
|
are bundled as tarballs in `code/deps/tarballs/` and extracted automatically at CMake
|
|
configure time. No internet access is required at build time (except GTest, fetched via
|
|
`FetchContent` from GitHub).
|
|
|
|
Install Boost on your system:
|
|
```bash
|
|
# Ubuntu / Debian
|
|
apt install libboost-dev
|
|
|
|
# macOS
|
|
brew install boost
|
|
```
|
|
|
|
---
|
|
|
|
## Clone
|
|
|
|
```bash
|
|
git clone https://codeberg.org/TMoussa/ConformalLabpp
|
|
cd ConformalLabpp
|
|
```
|
|
|
|
---
|
|
|
|
## Build modes
|
|
|
|
Three modes with increasing dependencies:
|
|
|
|
### Mode 1 — Fast tests (default, no system dependencies)
|
|
|
|
Pure-math tests: Clausen functions, hyper-ideal geometry, matrix utilities.
|
|
|
|
```bash
|
|
cmake -S code -B build
|
|
cmake --build build --target conformallab_tests -j$(nproc)
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
Expected: **36 tests pass**.
|
|
|
|
### Mode 2 — CGAL tests, headless (recommended for CI and development)
|
|
|
|
Full CGAL test suite. Requires Boost headers only — no display, no Wayland, no GLFW.
|
|
|
|
```bash
|
|
cmake -S code -B build -DWITH_CGAL_TESTS=ON
|
|
cmake --build build --target conformallab_cgal_tests -j$(nproc)
|
|
ctest --test-dir build -R "^cgal\." --output-on-failure
|
|
```
|
|
|
|
Expected: **158 tests pass, 2 skipped** (intentional stubs for Phase 9 items).
|
|
|
|
### Mode 3 — Full local build (CLI app + interactive viewer)
|
|
|
|
Requires Wayland or X11 development packages (`wayland-scanner`, `libx11-dev`, etc.).
|
|
Automatically enables the viewer library (GLFW + libigl).
|
|
|
|
```bash
|
|
cmake -S code -B build -DWITH_CGAL=ON
|
|
cmake --build build -j$(nproc)
|
|
```
|
|
|
|
> **Note:** `-DWITH_CGAL=ON` implies `-DWITH_VIEWER=ON`. Do not use this in headless
|
|
> environments — it will fail with `Failed to find wayland-scanner`.
|
|
|
|
---
|
|
|
|
## Running a single test
|
|
|
|
```bash
|
|
# By GTest filter (fastest, full output)
|
|
./build/conformallab_cgal_tests --gtest_filter="NewtonSolver*"
|
|
./build/conformallab_tests --gtest_filter="Clausen*"
|
|
|
|
# By CTest regex
|
|
ctest --test-dir build -R "cgal.NewtonSolver" --output-on-failure
|
|
```
|
|
|
|
All CGAL tests have the prefix `cgal.` in CTest (set in `tests/cgal/CMakeLists.txt`
|
|
via `TEST_PREFIX "cgal."`).
|
|
|
|
---
|
|
|
|
## First run — CLI app
|
|
|
|
After a full build (`-DWITH_CGAL=ON`):
|
|
|
|
```bash
|
|
# Euclidean conformal layout
|
|
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
|
|
|
|
# Spherical layout
|
|
./bin/conformallab_core -i input.off -g spherical -o sphere.off
|
|
|
|
# Hyperbolic layout (HyperIdeal)
|
|
./bin/conformallab_core -i input.off -g hyper_ideal -o hyperbolic.off
|
|
|
|
# Show input mesh in interactive viewer
|
|
./bin/conformallab_core -i input.off -s
|
|
|
|
# All options
|
|
./bin/conformallab_core --help
|
|
```
|
|
|
|
## Example programs
|
|
|
|
```bash
|
|
./build/examples/example_layout [input.off] [layout.off] [result.json]
|
|
./build/examples/example_euclidean [input.off] [output.off]
|
|
./build/examples/example_hyper_ideal [input.off] [output.off]
|
|
./build/examples/example_viewer [input.off] # interactive, requires WITH_VIEWER
|
|
```
|
|
|
|
`example_layout.cpp` is the best starting point — it shows the complete pipeline in ~120 lines.
|
|
|
|
---
|
|
|
|
## Rebuilding the CI Docker image
|
|
|
|
The CI runner is a self-hosted Raspberry Pi (ARM64). After changes to
|
|
`.gitea/docker/Dockerfile.ci-cpp`:
|
|
|
|
```bash
|
|
docker buildx build \
|
|
--platform linux/arm64 \
|
|
-f .gitea/docker/Dockerfile.ci-cpp \
|
|
-t git.eulernest.eu/conformallab/ci-cpp:latest \
|
|
--push \
|
|
.gitea/docker/
|
|
```
|