I need to modify a platform backend

CNA snapshot c1c316b9  ·  Development › Maintainer Handbook  ·  source links pinned to c1c316b9

CNA has three implementations of one platform contract, SDL3, HEADLESS and TERMINAL, and most platform changes touch either the contract or exactly one of them. The risk is in the difference: a change that is correct for SDL3 under one video driver and silently wrong under another (SDL reaches Windows, X11, Wayland, macOS, iOS, Android and the browser through its own drivers), a refusal Headless or Terminal no longer makes truthfully, or a capability that is advertised before its service is complete. This recipe gives the routine for changing a backend or the contract safely: who owns which decision, how the conformance suite holds every backend to the same rules, how to compare a sibling backend, how a new suite is registered so it actually runs, and which mechanical gates a platform change must pass. Everything was read from the CNA source at snapshot c1c316b9; nothing was built or run.

Find the owner

Decide first which of four things you are changing. The answer fixes where the test goes and which siblings must move with you.

The contract a backend is held to

These rules are enforced by the implementation-neutral conformance suite in PlatformConformanceTests.cpp, which is parameterised over PlatformFactory::GetAvailable(): SDL3 when it is selected, Headless always, and Terminal on POSIX. Adding a backend to that list is what enrols it. Its test names take the form EveryImplementation/PlatformConformance.<Case>/<Backend>.

A sibling comparison is useful but is not what the suite does: CNA's contract document describes SDL3 as the reference implementation, whereas the parameterised cases assert the same rules on each implementation and never diff one against another. Read SDL3 as the behavioural sibling, and the suite as the oracle.

Who owns window, event, input and present

Read first

1. IPlatform.hpp, IPlatformWindow.hpp and PlatformCapabilities.hpp: the promises, before any backend.
2. docs/platform-abstraction.md: the contract's own rules and the twelve-step procedure for adding an implementation. Its implementation table lists the three backends and says a new implementation is for a host SDL3 cannot reach, not a second route to a window system SDL3 already drives; the selection files are authoritative.
3. PlatformConformanceTests.cpp: the behaviour any backend, new or old, must preserve.
4. The backend page for the one you are changing, then the sibling that solves the same problem differently (below).
5. Game.cpp: PollEvents, Tick and the platform installation, to see exactly what the consumer assumes.

Compare a sibling backend

Read the sibling for the same concern before deciding a behaviour is a bug. The differences below are deliberate, not accidents to normalise.

Inside SDL3 the comparable differences come from SDL’s video drivers: a bare Xvfb has no window manager, a Wayland compositor applies its own scale and configures windows asynchronously, and Windows scales by DPI. CnaPlatformSdl3X11Tests and CnaPlatformSdl3WaylandTests run the window suites under the x11 and wayland drivers on private servers, and Sdl3WindowTest.NativeHandleMatchesTheVideoDriver checks the handle each driver hands a renderer.

Terminal is a byte-stream decoder, not a sibling to normalise toward. A new event, service or key mapping needs the full set: extend the taxonomy helpers, every mapper, the bridge where it applies, and the golden transcript.

Reproduce narrowly

Select the backend at configure time and run only its cases. The Sdl3* suites are compiled into the tree only when SDL3 is selected, and the Terminal* suites only off Windows.

# Headless (and Terminal on POSIX) in one SDL-free binary; this mirrors the axes of the platform
# workflow's SDL-free job (its own configure uses ALSA audio)
cmake -S . -B cmake-build-headless -G Ninja -DCMAKE_BUILD_TYPE=Debug \
      -DCNA_PLATFORM=HEADLESS -DCNA_ENABLE_SDL=OFF -DCNA_AUDIO_PLATFORM=NULL \
      -DCNA_GRAPHICS_RENDERER=HEADLESS -DCNA_BUILD_TESTS=ON \
      -DCNA_PLATFORM_CTEST_BINARY=CnaPlatformModuleTests
cmake --build cmake-build-headless --target CnaPlatformModuleTests
./cmake-build-headless/CnaPlatformModuleTests \
      --gtest_filter='EveryImplementation/PlatformConformance.*'   # from the repository root
ctest --test-dir cmake-build-headless -N -L platform        # what is registered, and needs what

# SDL3 under its x11 and wayland drivers, in an SDL3 tree with tests enabled
ctest --test-dir <sdl3-tree> -R '^CnaPlatformSdl3(X11|Wayland)Tests$' --output-on-failure

CNA_PLATFORM_CTEST_BINARY=CnaPlatformModuleTests points the platform CTest entries at the focused binary, as that CI cell does; the binary does not contain the graphics and runtime suites, so it proves a smaller contract (the window-ownership and event-golden tests live in other modules). Read the exact selector and refusal rules in the reserved and refused identities table: a request outside the offered set is a configure error, never a fallback to SDL3, and the retired WIN32, X11 and WAYLAND values say to use SDL3.

Which host a result came from is part of the result. Suites that need a server go through launchers that start a private one and exit 77 (a skip, not a pass) when it is absent: tools/platform/x11_test_server.sh (private Xvfb), tools/platform/wayland_test_server.sh (private headless Weston), and tools/platform/run_gpu_tests_private.sh for a real GPU. A bare Xvfb has no window manager, so maximise, minimise, EWMH fullscreen and focus do not occur there and asserting them tests the environment. On Windows the windows driver is exercised by the native MSVC SDL3 job in platform-ci.yml, which runs only on manual dispatch.

Make the smallest change

• Contract first, then every backend. Change the neutral contract only if every platform needs the concept. Then implement it or refuse it in each backend, with a false capability, a null accessor and PlatformNotSupportedException, and give Headless a truthful refusal or value first.
• Capabilities start false. Flip a flag only when the accessor and its refusal behaviour are complete, and derive it where the service is created.
• Translate at the edge. Native input becomes CNA enums and owning event values inside the backend. Do not let an SDL_* type or an event-lifetime string across the contract; SDL headers stay inside src/Sdl3.
• Give every native resource an explicit owner and test constructor failure as well as teardown order. The window wrapper, its back-pointers and the platform have a fixed destruction order; a callback must not observe a destroyed owner.
• Keep host policy out of the backend. Process-wide settings such as timer resolution or the current directory are the application’s decision. Keep Delay from changing process-global timer state.
• Poll once per frame, never in a hot loop. No platform call inside a draw, audio or input inner loop, and no allocation once the batch reaches steady-state capacity.

Mechanical gates and where a suite is registered

A platform change runs the seven boundary gates listed in the contract document; they also run in the HEADLESS cell of the platform CI workflow, and two of them run at configure time when a Python 3 interpreter is found.

python3 tools/platform/sdl_inventory.py --check
python3 tools/platform/sdl_classify.py --check
python3 tools/platform/renderer_sdl_audit.py --check
python3 tools/platform/sdl_ratchet.py --check --strict
python3 tools/platform/hot_path_lint.py
python3 tools/platform/nonproduction_sdl_audit.py --check
python3 tools/platform/check_contract.py

The SDL ratchet keeps a checked-in budget that may go down and never up, and counts any SDL reference outside its allowlist (the platform module, the SDL3 audio implementation and its mixer, and the SDL-based renderer families) as a boundary regression; the hot-path lint rejects platform calls through a platform receiver inside per-pixel, per-vertex, per-sample or per-event loops, and a justified exception carries // CNA_PLATFORM_HOT_PATH_OK: <reason>. Configure-time options: CNA_PLATFORM_RATCHET and CNA_PLATFORM_RATCHET_STRICT (both on) and CNA_PLATFORM_HOT_PATH_LINT (on). The audits protect architecture and classification; a heuristic check under-reports by design, so a pass is not proof and a failure is real.

New test files must reach CTest, and that is the step most often forgotten. Backend-specific test sources are filtered out of every tree that did not select that backend by patterns in UnitTests.cmake (Sdl3* when SDL3 is not selected, Terminal* on Windows); a new backend's files need the same treatment, or every other configuration fails to link. The display-independent contract runs as CnaPlatformTests (shuffled and repeated three times) through a filter of suite-name tokens, and the window half as CnaPlatformWindowTests in its own process with SDL's dummy video driver; a new suite whose name matches none of those tokens is discovered as an individual case but is absent from the grouped entry, so extend the filter or add a dedicated registration with its launcher. Suites that need a real window system get dedicated entries that start a private server: CnaPlatformSdl3X11Tests (private Xvfb) and CnaPlatformSdl3WaylandTests (private headless Weston), each skipping (77) where its server is missing. The general test layout is on Test architecture, and the how-to for the tests themselves is Add a regression test.

Prove it

1. The conformance case (or a new one) fails before the change on the backend in question, and the backend's own mapper test pins the translation.
2. The neighbouring backends still pass the same suite: at least Headless and the sibling that solves the same problem, in a tree that selected each (a conformance run in one tree covers the selected backend, Headless and Terminal).
3. The event-semantics golden test is unchanged, or its transcript diff is deliberate and reviewed.
4. The seven gates pass, and, for anything touching a shared path, the SDL-free cell (CNA_ENABLE_SDL=OFF, Headless) still configures and links without SDL.
5. A real-host smoke run with a renderer that exercises the changed seam (window, GL context, Vulkan surface or presenter): the host, the display server and the skip count stated. Where the change is host-specific, say plainly what was not run: native Windows, a real desktop, a real compositor, a physical device.

Check the blast radius

Review checklist

• Is every new capability flag matched by a non-null accessor and a refusing path on the backends that lack it, and does EveryServiceIsNullExactlyWhenItsCapabilityIsFalse still hold?
• Does anything native (a pointer, a constant, a string that outlives its event) cross the contract?
• Does the change alter event order, batch clearing or snapshot timing, and is the golden transcript consistent with that?
• Are logical size, drawable pixels and scale still three separate values, with Sync() respected?
• Are ownership and destruction order stated and tested for constructor failure and for a window that outlives its platform?
• Do the seven gates pass, and is any hot-path exception justified in a comment?
• Is each new suite registered (source filter, grouped entry or launcher), and does the report distinguish skipped, environment-limited and real-host results?