I need to change build configuration

CNA snapshot 009d40f5  ·  Development › Maintainer Handbook  ·  source links pinned to 009d40f5

Use this recipe to add or change a CMake option, a default, a value of one of the three selectors, a renderer combination rule, a preset, a CI configuration or a pinned third-party source. CNA's configure step is also its validation step: a wrong combination is meant to fail at configure time with a message that names the option, and the decision code is written so that the refusal can be tested in milliseconds. The trace of the whole configure is on CMake architecture; this page is the procedure and the rules a change has to keep. Everything was read at 009d40f5 from CMake, presets and workflows; nothing was configured or run.

Find the owner

Read first

1. CMakeLists.txt from the top through add_subdirectory(modules): the order is functional (selection precedes the SDL sub-build; the private compile policy is attached last to every CNA-owned target).
2. The one selection file you are changing, and the cmake -P case that tests it (cmake/Tests).
3. UnitTests.cmake around the CnaAudioPlatformSelection_* loop and ModuleProbes.cmake around CnaRendererDefaultSelection_*: the registration patterns.
4. platform-ci.yml: the tuple matrix and the sdl-enable-matrix job that asserts a configure fails.
5. Then the CMake option index, selection axes and the user-facing Building CNA: CMake options.

Rules an option must follow

The shape of a tri-state option, as CNA_DIAGNOSTICS and CNA_ENABLE_VIDEO write it (a template for a new option, not an existing one):

set(CNA_ENABLE_FOO "AUTO" CACHE STRING "Enable Foo (OFF, AUTO, or ON)")
set_property(CACHE CNA_ENABLE_FOO PROPERTY STRINGS OFF AUTO ON)
string(TOUPPER "${CNA_ENABLE_FOO}" _cna_enable_foo_normalized)
if(NOT _cna_enable_foo_normalized MATCHES "^(OFF|AUTO|ON)$")
    message(FATAL_ERROR
        "CNA_ENABLE_FOO must be OFF, AUTO, or ON (received '${CNA_ENABLE_FOO}').")
endif()
set(CNA_ENABLE_FOO "${_cna_enable_foo_normalized}" CACHE STRING
    "Enable Foo (OFF, AUTO, or ON)" FORCE)
unset(_cna_enable_foo_normalized)

The three selectors and their refusals

The selectors are independent by design. The one hidden coupling is deliberate and refused explicitly in Sdl2OnlyConfiguration.cmake: an SDL2 platform with SDL3 audio (and the reverse) would put two SDL generations exporting the same symbols in one process, and SDL2 platform plus SDL2 audio also refuses the renderers that link SDL3 directly. A new coupling between selectors is a design change and needs an entry in the selection axes index.

Renderer combination rules and the registry

• Combination rules are real, demonstrated conflicts with a stated reason. At TARGET: PORTABLEGL cannot join a real-GL renderer (it defines the global gl* symbols); GDI cannot join SOFTWARE (it recompiles the same translation units with a different definition); and identities cannot span the Windows-only, Emscripten-only and macOS-only partitions. Five EasyGL identities can coexist since GL profile became a runtime value, although a variable and a comment in RendererCombinations.cmake still describe the removed rule. The rejection function joins its reason from ARGN: write the reason as adjacent literals with no ;, which CMake would split.
• The registry is generated. cna_generate_renderer_registry writes generated/CnaRendererRegistry.generated.cpp into the build tree from the identity map in RendererRegistry.cmake; an identity with no row is a configure error naming the three places to register it. The explicit table exists because a static-initialiser self-registration would be discarded by the linker inside an archive. The first identity is the build's default.
• Identity macros. An arm of cna_configure_renderer_identity appends its macro to _cna_identity_defines; it must never call add_compile_definitions, which is directory-scoped and would define that identity's macro for every renderer in the set. scripts/check_runtime_renderer_discipline.py (RuntimeRendererDiscipline) fails on a new one.
• Target gates versus resource gates. A gate that decides whether a target exists and runs against the default renderer must test equality with CNA_GRAPHICS_RENDERER; a gate that decides whether a resource is available may test membership in the set (graphics examples). In a single-renderer build they coincide, which is why the mistake is easy to make.
• Adding a whole renderer family is the worked example on CMake architecture; do not copy a neighbour's family CMake without knowing which special relationship applies.

Prove a selector change

1. A script-mode case for the decision. Follow the audio loop in UnitTests.cmake: add_test(NAME CnaAudioPlatformSelection_<CASE> COMMAND cmake -DCNA_AUDIO_SELECTION_FILE=... -DCNA_AUDIO_SELECTION_CASE=<CASE> -DCNA_AUDIO_SELECTION_EXPECTED=<phrase> -P cmake/Tests/AudioPlatformSelectionCase.cmake) with the audio;platform labels. Cover the default, every implemented value, every reserved value and an unknown value. The renderer default cases carry an outcome (ACCEPT or REJECT) and, for refusal, expected text. Keep the control cases (an accepted case, an unknown name still unknown): a refusal that refuses everything would pass every reject case.
2. A nested configure only where detection or a real project is needed (CnaWaylandPlatformSelection, CnaSdlOffFindsNoSdlPackage configure a work directory with the generator under test).
3. A CI cell for the expected outcome. Copy the sdl-enable-matrix pattern: a matrix row with expect: configure-succeeds|configure-fails, configure with set +e, then assert the status and, for a failure, grep the diagnostic. It proves the refusal, and builds nothing.
4. Single, multi and default. Configure a single-identity tree, a multi-renderer set with a different default, and the unchanged default; inspect the generated registry and the final link line. scripts/check_renderer_configure_sweep.sh configures every identity (skipping ones whose SDK is absent) without building.
5. Run the identity, combination and discipline checks (Python) after any list edit; check_renderer_identities.py follows each identity through to its descriptor accessor and checks documented counts.

Presets, CI and documentation

• Presets. CMakePresets.json has 17 visible configure presets and a hidden base-ninja parent (Ninja, CNA_EXPORT_COMPILE_COMMANDS, CNA_USE_CCACHE), and its own list of 17 build presets; macos, ios, ios-simulator and multi-renderer have no build preset. Binary directories are ${sourceDir}/cmake-build-<name>. The dev, unit and release-modules closures deliberately omit tests, demos, the C API, networking, FFmpeg and Draco; PCH, unity and IPO stay opt-in presets. tools/build/check_build_performance_policy.py (run in general-tests-ci.yml) resolves preset inheritance and fails if those closures regain the omitted features or if routine policy is written into global CMAKE_CXX_FLAGS, linker flags or add_compile_options.
• Workflows. The selection matrix lives in platform-ci.yml (SDL3 + OPENGLES3, SDL2 + OPENGLES3 with SDL2 audio, SDL3 + VULKAN, SDL3 + SOFTWARE, HEADLESS with NULL audio, TERMINAL + SOFTWARE with NULL audio, SDL-free X11 cells with NULL and ALSA audio, Win32 under Wine and native, and the SDL-switch job). multi-renderer-ci.yml builds HEADLESS;SOFTWARE;STUB and a single-renderer control, because the property that matters is that single-renderer builds did not change. Path filters exclude Markdown and docs/. Sibling checkouts use clone_siblings.sh (candidate branches, then next, then develop). Twenty workflow files exist; the C API has five build-free gate workflows and no build workflow (Update the C API).
• Documentation. A user-visible option needs the site's options table, the presets and, for renderers, the renderer guide; the generated option index is regenerated from the source, not edited.

Third-party sources, patches and siblings

Recently added mechanisms at this snapshot: the persistent SDL prebuilt is now reused only while a build manifest still matches (SdlPrebuiltFingerprint.cmake: SHA-256 over the vendored source tree without .git, every patch in order with its hash, and every sub-build argument; ccache launcher excluded), so a moved source, an edited patch or changed arguments rebuild it once and an interrupted build is retried; two SDL_gpu Vulkan barrier patches are staged from a copy so the vendored tree stays pristine (cmake/patches); CNA_OPENGL4_COMPILED_EFFECTS was added in the shape of the other eight compiled-effect options; with CNA_ENABLE_SDL=OFF MojoShader now builds on the C library without its SDL_gpu adapter (FNA3D still needs SDL and is refused by name); the EasyGL test filter lists only the five EasyGL identities; and an OpenGL4 GL-error output gate joins the Vulkan validation gate. Both output gates turn a printed message into a test failure through FAIL_REGULAR_EXPRESSION, for problems that appear at teardown beyond any in-process assertion.

To change a pin: change the tag or commit, refresh any patch series against exactly that revision (a patch that does not apply stops the configure and names itself), and rely on the manifest to rebuild the SDL prebuilt; to force it, delete the prebuilt root that configure prints. The C API package is the only installable target (modules/c-api/CMakeLists.txt): the C++ framework has no install() rules.

Shared library and build performance

• CNA_SHARED_LIBRARY defaults ON on native ELF with GNU or Clang and CMake 3.27 or newer; the decision precedes every target because archives inside libcna.so need position-independent code, and it is a configure error elsewhere. The C API links module archives directly and stays self-contained. CNA_ENABLE_IPO is refused with sanitizers and with CNA_C_API_BUILD_STATIC=ON.
• ccache. CNA_USE_CCACHE (ON) wraps compilers with a launcher that exports CCACHE_BASEDIR from CNA_CCACHE_BASEDIR (the environment's value wins when set; otherwise the parent of the source directory), so the same translation unit hashes identically across build trees; cmake --build <dir> --target cna_ccache_stats shows the cache. CNA does not change global ccache sloppiness, and it documents an apparent 0% direct-hit rate that turned out to be an unwritable statistics directory. Read counters as deltas, not lifetime rates.
• Focused targets and linkers. Module test executables share object libraries with CnaTests; CNA_LINKER selects AUTO (Mold, then LLD), DEFAULT, MOLD or LLD; CNA_DEBUG_INFO=LINE_TABLES and the PCH and unity pilots are opt-in and measured in docs/build-performance.md. Compare a change only against the same compiler, renderer, cache state and target.

Traps

• An unread cache entry. Forgetting a removed identity would make -DCNA_RENDERER_X=ON silently configure the default; that is why each retired name is checked on that route too, and why a value not consumed anywhere is worse than a refusal. The check does not reach a misspelled or never-existing name: -DCNA_RENDERER_D3D9=ON is still an unread cache entry at this snapshot, so read the CNA: Using <X> graphics renderer line after such a configure.
• A default that moves. The per-host default lives in one file used by two consumers so the SDL-free decision cannot drift from the renderer default; do not restate it.
• Stale comments in selection files. PlatformSelection.cmake says “two of the five” while seven platforms exist; ModuleProbes.cmake still speaks of 42 identities; RendererCombinations.cmake describes a rule P11 removed. Trust the code and the identity table.
• Presets that hide a failure. A preset is a convenience, not a matrix: dev is not evidence for a renderer, C API, network, media or Draco change (What to test after changing X).
• Directory-scoped commands in selection code. add_compile_definitions and friends leak across the set and do not run in script mode.
• A nested sub-build inherits nothing. SDL is configured by separate CMake invocations; settle Apple sysroot and architecture before launching them.

Review checklist

• The option's name, type, default and normal form follow the table; the default build is unchanged.
• Every invalid value or combination fails at configure time by name; nothing is substituted.
• A script-mode or nested test asserts the refusal with a short phrase, plus a control that accepts; a CI cell asserts the expected outcome where a real configure is needed.
• Presets, workflow cells, the site option table and, for renderers, the combination document agree; single, multi and default configurations were considered.
• Pins, patches and offline overrides are recorded; anything not configured or run is stated as such.

Related: Blast radius and readiness, Test architecture, Fix a renderer bug and Make a release.