293 lines
6.5 KiB
Markdown
293 lines
6.5 KiB
Markdown
# Build
|
|
|
|
## Status
|
|
|
|
```text
|
|
BUILD_SYSTEM=MESON_NINJA
|
|
PUBLIC_API_LANGUAGE=C17
|
|
IMPLEMENTATION_LANGUAGES=C17_CXX17
|
|
BUILD_PARALLELISM=HOST_AWARE
|
|
RESOURCE_UTILIZATION_POLICY=MAXIMUM_SAFE_USEFUL_THROUGHPUT
|
|
SERIALISM_REQUIRES_PROOF=CANONICAL
|
|
```
|
|
|
|
Meson is the build-system authority. Do not duplicate dependency-version truth
|
|
in this document when `meson.build` already enforces it.
|
|
|
|
## Requirements
|
|
|
|
Lardon3D targets Linux.
|
|
|
|
Primary toolchain:
|
|
|
|
```text
|
|
Clang or GCC
|
|
Meson
|
|
Ninja
|
|
pkg-config
|
|
```
|
|
|
|
Major dependencies currently include ncursesw, SQLite, OpenSSL, GIO/GLib,
|
|
OpenCV, LibRaw, libexif, libpng, libdeflate and Ceres. Vulkan remains optional
|
|
at configuration level.
|
|
|
|
Public APIs are C17. Implementation is mixed C17/C++17.
|
|
|
|
## Bootstrap examples
|
|
|
|
These commands install only the basic compiler/build front end; Meson remains
|
|
authoritative for the complete dependency set.
|
|
|
|
Debian/Ubuntu:
|
|
|
|
```sh
|
|
sudo apt install clang meson ninja-build libncursesw5-dev pkg-config
|
|
```
|
|
|
|
Fedora:
|
|
|
|
```sh
|
|
sudo dnf install clang meson ninja-build ncurses-devel pkg-config
|
|
```
|
|
|
|
Arch Linux:
|
|
|
|
```sh
|
|
sudo pacman -S clang meson ninja ncurses pkgconf
|
|
```
|
|
|
|
## Standard build
|
|
|
|
First configuration:
|
|
|
|
```sh
|
|
CC=clang CXX=clang++ meson setup build
|
|
```
|
|
|
|
Existing tree:
|
|
|
|
```sh
|
|
meson setup --reconfigure build
|
|
meson compile -C build
|
|
```
|
|
|
|
Do not hard-code `-j8` as project policy.
|
|
|
|
Meson/Ninja should use host-appropriate parallelism unless a specific
|
|
validation has a reason to constrain it.
|
|
|
|
## Build parallelism policy
|
|
|
|
The build is not governed by a portable fixed job count.
|
|
|
|
Canonical policy:
|
|
|
|
```text
|
|
preserve the interactive host reserve
|
|
then use maximum safe useful throughput
|
|
```
|
|
|
|
A reference host measurement such as 8 or 12 useful jobs is evidence for that
|
|
host at that time, not a repository constant.
|
|
|
|
If memory-heavy compilation or another active workload creates pressure,
|
|
reduce build width for that run. Do not convert the temporary reduction into a
|
|
global documentation rule.
|
|
|
|
## Reconfigure versus wipe
|
|
|
|
Prefer incremental reuse:
|
|
|
|
```sh
|
|
meson setup --reconfigure build
|
|
meson compile -C build
|
|
```
|
|
|
|
Use `--wipe` only when a fresh configuration is actually required, such as:
|
|
|
|
- switching sanitizer configuration in the same directory;
|
|
- changing compiler family;
|
|
- changing a configuration whose cached state cannot be reused safely;
|
|
- reproducing a clean release/global-maintenance proof;
|
|
- recovering from a stale or corrupt build directory.
|
|
|
|
A normal edit/test loop should not wipe the build tree repeatedly.
|
|
|
|
## Release build
|
|
|
|
Use an explicit release directory or deliberate reconfiguration.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
CC=clang CXX=clang++ meson setup build-release --buildtype=release
|
|
meson compile -C build-release
|
|
```
|
|
|
|
For LTO:
|
|
|
|
```sh
|
|
CC=clang CXX=clang++ meson setup build-release-lto --buildtype=release -Db_lto=true
|
|
meson compile -C build-release-lto
|
|
```
|
|
|
|
Separate directories avoid destroying a useful incremental debug tree.
|
|
|
|
## Vulkan configuration
|
|
|
|
Portable CPU-only proof:
|
|
|
|
```sh
|
|
CC=clang CXX=clang++ meson setup build-portable -Dvulkan_orb=disabled
|
|
meson compile -C build-portable
|
|
```
|
|
|
|
Vulkan-enabled proof:
|
|
|
|
```sh
|
|
CC=clang CXX=clang++ meson setup build-vulkan -Dvulkan_orb=enabled
|
|
meson compile -C build-vulkan
|
|
```
|
|
|
|
A Vulkan-on build is not automatically a proof that every scientific path uses
|
|
or should use the GPU.
|
|
|
|
Current production GPU promotion remains limited by each subsystem's validated
|
|
backend contract.
|
|
|
|
## Validation
|
|
|
|
Normal configured tests:
|
|
|
|
```sh
|
|
meson test -C build --print-errorlogs
|
|
```
|
|
|
|
Whitespace/style boundary:
|
|
|
|
```sh
|
|
git diff --check
|
|
```
|
|
|
|
Public C header probe:
|
|
|
|
```sh
|
|
cc -x c -std=c17 -fsyntax-only -Iinclude -include lardon3d/<header>.h /dev/null
|
|
```
|
|
|
|
Use `docs/development/testing.md` for sanitizer and validation policy.
|
|
|
|
## ASan / UBSan build
|
|
|
|
Example dedicated directory:
|
|
|
|
```sh
|
|
CC=clang CXX=clang++ meson setup build-asan -Db_sanitize=address,undefined
|
|
meson compile -C build-asan
|
|
meson test -C build-asan --print-errorlogs
|
|
```
|
|
|
|
Do not claim an unqualified full LeakSanitizer pass from the retained global
|
|
maintenance checkpoint. The external OpenCL loader qualification documented in
|
|
the canonical audit remains part of that evidence.
|
|
|
|
## TSan build
|
|
|
|
Use TSan only with the configuration that matches the intended proof.
|
|
|
|
The retained global maintenance concurrency proof used GCC/G++ with Vulkan
|
|
disabled, because the project TSan matrix and the Vulkan runtime validation are
|
|
separate evidence boundaries.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
CC=gcc CXX=g++ meson setup build-tsan -Db_sanitize=thread -Db_lundef=false -Dvulkan_orb=disabled
|
|
meson compile -C build-tsan
|
|
meson test -C build-tsan --print-errorlogs
|
|
```
|
|
|
|
The exact target subset, suppression qualification and repetition evidence are
|
|
documented in `docs/development/concurrency.md` and the global maintenance
|
|
audit.
|
|
|
|
## Current retained maintenance checkpoint
|
|
|
|
The canonical detailed evidence is:
|
|
|
|
```text
|
|
docs/architecture/global_maintenance_audit.md
|
|
GLOBAL_MAINTENANCE_AUDIT=PASS/FROZEN
|
|
```
|
|
|
|
The 2026-09-01 checkpoint retained:
|
|
|
|
```text
|
|
portable Clang/Clang++ build and suite
|
|
Vulkan-on Clang/Clang++ build and suite
|
|
ASan/UBSan qualified run
|
|
portable GCC/G++ TSan matrix
|
|
public-header C17/C++17 probes
|
|
ABI and application-link checks
|
|
independent review
|
|
```
|
|
|
|
Those exact historical counts belong to the audit and should not be duplicated
|
|
as a new current build contract.
|
|
|
|
## Build directory layout
|
|
|
|
A configured Meson tree typically contains:
|
|
|
|
```text
|
|
build/
|
|
src/
|
|
tests/
|
|
compile_commands.json
|
|
```
|
|
|
|
Exact generated layout is Meson/Ninja output and may evolve.
|
|
|
|
## Environment
|
|
|
|
Common variables include:
|
|
|
|
| Variable | Purpose |
|
|
| --- | --- |
|
|
| `CC` | C compiler |
|
|
| `CXX` | C++ compiler |
|
|
| `CFLAGS` | additional C flags |
|
|
| `CXXFLAGS` | additional C++ flags |
|
|
| `LDFLAGS` | additional linker flags |
|
|
|
|
Prefer Meson options for project features rather than ad-hoc environment flags
|
|
that make builds difficult to reproduce.
|
|
|
|
## Troubleshooting
|
|
|
|
Check ncursesw discovery:
|
|
|
|
```sh
|
|
pkg-config --libs ncursesw
|
|
```
|
|
|
|
If Clang is unavailable, GCC is supported where the current Meson checks allow
|
|
it.
|
|
|
|
For a slow build, first preserve the existing build tree and let Ninja use
|
|
normal host-aware scheduling. Reduce concurrency only when actual host pressure
|
|
or another active workload justifies it.
|
|
|
|
`ccache` may be used when available, but it is optional operational tooling and
|
|
not part of scientific identity.
|
|
|
|
## Rules
|
|
|
|
```text
|
|
NO_FIXED_GLOBAL_J8=YES
|
|
NO_REPEATED_UNCHANGED_WIPE=YES
|
|
HOST_AWARE_BUILD_PARALLELISM=YES
|
|
```
|
|
|
|
Build configuration is operational state. It must not silently redefine
|
|
scientific formats, fingerprints or persistence contracts.
|