Build system

CNA snapshot 009d40f5  ·  Development › Build System  ·  source links pinned to 009d40f5

The root CMake project composes physical module targets and one implementation from each backend axis. Presets capture the developer configurations the repository supports; target names, not the CNA umbrella, drive focused builds. This page is the command entry point for a maintainer: what a configure needs and refuses without, which presets and build presets exist, how to select backends by hand, what to rebuild after a given kind of change, how to read the configure log, and where generated artefacts come from. The configure-to-link trace is on CMake architecture; install steps for a first build are in Building CNA.

Prerequisites

The build has a small hard floor and many conditional dependencies. Backend libraries are needed only for configurations that select them, and several optional features are three-state switches (OFF, AUTO, ON) whose AUTO default silently degrades the configuration instead of failing. Inspect the configure output (reading the configure log) and never mistake an unavailable optional backend for a runtime failure.

• Toolchain. CMake 3.20 or newer (cmake_minimum_required in CMakeLists.txt) and a C++23 compiler with extensions off (CMAKE_CXX_STANDARD 23, CMAKE_CXX_EXTENSIONS OFF). Enabling the C API adds C17. The linked-once libcna.so layout needs CMake 3.27 and a native ELF GNU or Clang toolchain; CMake does not check compiler versions. The presets that inherit base-ninja use Ninja and turn ccache on; presets such as web and devices-* declare no generator.
• Python 3. Several configure-time gates and CTest entries run Python scripts: the platform ratchet, the non-production SDL audit, the hot-path lint, the XNA pipeline parity gates and the module link-closure tests. Without an interpreter they are skipped with a status line rather than failing, so a configure that "passed" on a machine without Python did not run them.
• git. Needed for git submodule update --init and, at configure time, to apply the vendored-SDL patch series when the SDL prebuilt is (re)built (the SDL prebuilt); a missing git there is a configure error.
• Submodules. third_party/SDL, SDL_image, SDL_mixer, third_party/draco and vendor/googletest. Each missing one stops the configure with a message that names the directory and tells you to run git submodule update --init (non-recursive: the recursive form only fetches nested codec submodules CNA disables). With CNA_ENABLE_SDL=OFF the SDL ones are never read; CNA_ENABLE_DRACO=OFF and CNA_BUILD_TESTS=OFF remove the others.
• Sibling repositories. ../sharp-runtime on its next branch for every build (missing: configure error naming CNA_SHARP_RUNTIME_ROOT); ../easy-gl with ../meta-gl when any of the five GL identities is selected, including the Linux default; ../free-direct only for FREEDIRECT. They are separate checkouts, not submodules. The first-build clone commands are in Building CNA, step 2.
• Optional three-state features. CNA_ENABLE_VIDEO (FFmpeg, found through four pkg-config modules), CNA_CNB_ZSTD (libzstd for compressed .cnb chunks), CNA_ENABLE_FONT_PIPELINE (FreeType for the .spritefont route) and CNA_ENABLE_MEDIA_PIPELINE (FFmpeg-based build-time importers); zlib for binary FBX arrays is detected without a switch. Draco defaults ON and is off by default only under Emscripten.
• Backend packages. find_package(Vulkan REQUIRED) for VULKAN, find_package(OpenGL REQUIRED) for OPENGL4, the X or Wayland development packages for CNA_PLATFORM=X11 or WAYLAND (refused with the package names, never replaced by SDL3), and the SDL submodules unless CNA_ENABLE_SDL=OFF.

How CMake is structured

CMake architecture follows the configure order, the target graph, the generated renderer registry, the static-archive cycles, the shared-library mode, the SDL prebuilt and a worked renderer addition. In short:

• Root policy and options in CMakeLists.txt establish language and toolchain behaviour, then the version identity, the linker, ccache and the test-display policy.
• Selection files resolve the platform, audio and renderer identities and decide whether SDL is needed at all, before any dependency is configured.
• Each physical module declares its own static target, include root and dependencies through cna_add_module; the modules are entered from modules/CMakeLists.txt.
• Backend implementation targets attach only for the selected or requested identities; a generated registry lists them and a descriptor gate compiles the ones you did not select.
• CNA is an INTERFACE umbrella over the runtime modules plus the selected renderer. It has no sources, so it is not a buildable target: build a real target by name, or build everything.
• Test, harness and probe registration comes after module composition, so those files can name the final targets.

Useful configurations

The repository ships 17 visible configure presets (plus a hidden Ninja base) and 17 build presets. Each configure preset writes its tree to ${sourceDir}/cmake-build-<preset> (the multi-renderer tree is cmake-build-multi and the iOS simulator tree cmake-build-ios-sim). Read both halves of the JSON: a configure preset existing does not imply a build preset of the same name.

No preset selects VULKAN, OPENGL4, SDL_GPU, WEBGPU, X11 or WAYLAND, the C API, or a Windows target: configure those by hand, as in the next section. The multi-renderer set contains only CPU renderers, so it needs no GPU; the private display wrapper is for tests in a hand-configured GPU tree (GPU and window tests).

Manual selection

cmake -S . -B build/dev \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCNA_PLATFORM=HEADLESS \
  -DCNA_GRAPHICS_RENDERER=HEADLESS \
  -DCNA_AUDIO_PLATFORM=NULL
cmake --build build/dev --parallel

These identities exist at this snapshot, and combinations are still constrained by target logic and test needs; prefer a repository preset when one expresses the task. Two things surprise people. With the default CNA_ENABLE_SDL=AUTO the vendored SDL is configured and built even for the display-free selection above, because AUTO means "exactly as before"; only -DCNA_ENABLE_SDL=OFF gives an SDL-free tree. And the HEADLESS platform, HEADLESS renderer and NULL audio choice is three independent decisions, not one "headless" switch.

# SDL-free native X11 with several renderers compiled in (the shape of the CI x11-sdl-free-gpu cell;
# OPENGL33 needs the easy-gl and meta-gl siblings, VULKAN the Vulkan headers)
cmake -S . -B build/x11 -G Ninja \
  -DCNA_ENABLE_SDL=OFF -DCNA_PLATFORM=X11 -DCNA_AUDIO_PLATFORM=ALSA \
  -DCNA_GRAPHICS_RENDERER=OPENGL33 \
  -DCNA_GRAPHICS_RENDERERS="OPENGL33;VULKAN;SOFTWARE;HEADLESS"

# One GPU renderer, everything else default
cmake -S . -B build/vk -DCNA_GRAPHICS_RENDERER=VULKAN

What configure refuses, and where

Invalid combinations fail at configure time with a named reason and never fall back silently. The table lists the refusals a hand-written selection can hit and the file that raises each; the first three are the ones people meet first.

I changed this — what must I rebuild?

Reading the configure log

The configure prints one status line per decision that matters, and most build surprises are explained by one of them. Search the log for these prefixes before debugging a "missing feature".

Build speed and disk use

The build-speed controls are collected in cmake/BuildPerformance.cmake and documented in docs/build-performance.md; public ABI facts stay in cna_build_config, and everything below is target-scoped private policy.

• ccache. CNA_USE_CCACHE defaults to ON. When ccache is found, both compiler launchers become cmake -E env CCACHE_BASEDIR=<dir> ccache. The base directory is CNA_CCACHE_BASEDIR: the exported CCACHE_BASEDIR if set, otherwise the directory above the source tree, so one translation unit hashes the same from every build tree. cmake --build <dir> --target cna_ccache_stats prints the statistics.
• One shared library. CNA_SHARED_LIBRARY (default ON on native ELF GNU or Clang with CMake 3.27) links the engine once into libcna.so. A configuration that previously carried a full static copy in every test executable (about 104 MB per Debug executable across 798 executables, by the measurement recorded in the root CMakeLists.txt) now carries it once; a renderer .cpp edit no longer relinks every test.
• Linker and debug information. CNA_LINKER (AUTO tries mold then lld on native ELF), CNA_DEBUG_INFO (FULL, LINE_TABLES, SPLIT; Debug builds only, and not combinable with sanitizers).
• Sanitizers. CNA_SANITIZE=address,undefined with CNA_SANITIZE_OPTIMIZATION; ASan with TSan and TSan with MSan are refused, and MSVC and Emscripten are unsupported. The instrumentation is attached to CNA-owned targets and sharp-runtime, not to vendored SDL or ENet.
• Pilots. CNA_ENABLE_PCH (content test objects; that target bypasses ccache), CNA_ENABLE_UNITY_BUILD (the core and math modules; refused for Emscripten and cross builds) and CNA_ENABLE_IPO.
• Vendored SDL jobs. CNA_MAX_VENDORED_BUILD_JOBS (default 2) bounds the parallelism of the configure-time SDL sub-builds.
• Configure audits. The slow configure-time Python audits cache their success by a content fingerprint of their inputs (CNA_CONFIGURE_AUDIT_CACHE, default ON), so an unchanged tree does not re-run them.

Generated artifacts

Build directories, compiled content and generated code belong to their configured output trees unless a generation rule explicitly checks them in. Some generated files live in the build tree (the renderer registry, CNA/Version.hpp, the Wayland protocol bindings) and are never committed; others are committed and guarded by a gate that fails when the file no longer matches what its generator writes (the SPIR-V and shader-package headers, the C API baselines and coverage inventories, the XNA pipeline parity report, the glTF goldens). Before committing a generated change, locate the generating target or script and reproduce the file from clean input. The full table is in the repository map; the source-side entry points are CMakeLists.txt and CMakePresets.json, and the generated CMake option index lists the declared options.