CNA-BUG-236: docs/platform-abstraction.md's Implementations table lists five backends and omits X11 and Wayland

CNA snapshot 009d40f5  ·  Known Issues › Current bugs  ·  source links pinned to 009d40f5

CNA's platform-abstraction document lists SDL3, SDL2, WIN32, HEADLESS and TERMINAL in its Implementations table, but PlatformSelection.cmake offers seven implementations, adding the native X11 and WAYLAND backends.

Identifier

CNA-BUG-236

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

None

Affected contract

docs/platform-abstraction.md, the Implementations table

Expected behaviour

docs/platform-abstraction.md is CNA's own contract document for the platform boundary, and its Implementations table is where a maintainer reads which backends exist. It should list every implementation cmake/PlatformSelection.cmake offers.

Actual behaviour at TARGET

The Implementations table has rows for SDL3, SDL2, WIN32, HEADLESS and TERMINAL only, and the compile-scope paragraph beneath it (HEADLESS always, TERMINAL on POSIX, WIN32 only when selected) does not mention X11 or WAYLAND either. PlatformSelection.cmake also offers X11 and WAYLAND, the two native Unix backends, each with its own modules/platform/src subtree, ctest suites or CI cell, and user guide (platform-x11.md, platform-wayland.md). Elsewhere the document covers X11 (its introduction has a configure example and a paragraph linking platform-x11.md) but never mentions CNA_PLATFORM=WAYLAND: Wayland appears only as a NativeWindowSystem value in the native window handle table, and the 'Adding an implementation' section is generic and describes neither backend.

Source locations

• docs/platform-abstraction.md — the Implementations table (five rows; X11 and WAYLAND absent)
• cmake/PlatformSelection.cmake — offers SDL3, SDL2, X11, WAYLAND, HEADLESS, TERMINAL and WIN32

Evidence

Checked by reading the Implementations table in docs/platform-abstraction.md and the _cna_platforms_available construction in PlatformSelection.cmake at 009d40f5. Not executed. The Development platforms overview already notes this discrepancy and treats the selection files as authoritative.

Independent re-verification: Checked by reading the Implementations table, the introduction and the native window handle table of platform-abstraction.md against the _cna_platforms_available construction in PlatformSelection.cmake at 009d40f5. Not executed. The earlier wording that the rest of the file and the 'Adding an implementation' section describe both backends was wrong for WAYLAND and for that section; the defect is the table and compile-scope paragraph, plus the missing WAYLAND coverage.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

No check compares the document's table against the platform-selection file.

Regression test

Add X11 and WAYLAND rows; optionally a documentation check asserting the table's rows match the offered set in PlatformSelection.cmake.

Blast radius

Maintainers reading the contract document to learn which platform backends exist. The build and the backends themselves are unaffected.

Workaround

Treat cmake/PlatformSelection.cmake and the Native Platforms guide as authoritative for the backend list.