4.8 KiB
ADR-0077: Scoped native 2D client dependencies
Status
Accepted for M9.1's isolated probe and M9 engineering client. No final 3D renderer, audio, UI toolkit, physics engine or transport is selected here.
Context
M9 needs a native Windows/Linux window, input events and simple 2D primitives. The headless libraries must configure, build and run without graphical dependencies. M6 views already expose immutable value data; no SDL types belong in those APIs.
Decision
Use SDL 3.4.16, zlib licensed, for window/events and SDL_Renderer. Build a
shared library from an explicitly prepared SHA-256-pinned upstream source archive.
tools/sdl3-pin.cmake is the machine-readable pin. Normal CMake configuration
never downloads it. The dependency and evo-client-probe are opt-in; only the
probe links SDL at M9.1. ADR-0078 extends this to the M9.2 platform adapter and
its native tests, with direct X11 linking on Linux for lifecycle correctness.
Select SDL's small 2D abstraction rather than direct Vulkan for this scope. Retain its platform renderer selection and allow the probe to explicitly request Vulkan, Direct3D11 or software without silently substituting another backend. Disable unused audio, camera, joystick, haptic, sensor and SDL_GPU subsystems. Keyboard and mouse events remain. Audio and final UI are explicitly deferred.
This is a scoped amendment to ADR-0003, following the explicit-source approach already used for PostgreSQL: do not require adoption of a general package manager for one self-contained client dependency. vcpkg/Conan measured comparison remains open before a broader dependency graph. No claim is made that either was benchmarked. Archive preparation can use an existing verified download for offline rebuilds.
Alternatives considered
| Option | Value | Cost / disposition |
|---|---|---|
| SDL3 + direct Vulkan | Explicit resource/synchronization control and future compute | Swapchain, shaders, pipeline and allocator work exceeds this 2D gate; defer to measured need / M13 |
| SDL3 + SDL_GPU | Portable explicit GPU API with shader pipelines | Shader build/distribution and more resource lifetime work; useful later, not required for basic views |
| SDL3 + SDL_Renderer | Window/events plus accelerated primitives and textures from one dependency | Less pipeline control; selected for scoped 2D client, not a permanent engine-wide abstraction |
| GLFW + Vulkan | Narrow window/input layer | Still needs the renderer work above and another dependency choice; no demonstrated M9 advantage |
| vcpkg manifest | Baselines/features and strong CMake/MSVC integration | Broader tool bootstrap/registry governance for one archive; remains a candidate |
| Conan lockfile | Profiles, binary packages and revision locks | Python/recipe/tool bootstrap and profile governance; remains a candidate |
These are scope/maintenance comparisons, not measured performance rankings. The probe records actual backend, SDL version and execution result; size/build measurements and platform limits belong in the M9.1 validation record.
Benefits
One established C API with explicit return checks, uncomplicated RAII adapters and small review surface for generated C++. No engine dependency and no changes to simulation rules, formats or public headers. Software rendering permits CI pixel checks without pretending to test a GPU driver.
Costs
Shared-library packaging and license retention; platform-specific SDL build options and system video libraries. Main-thread event/render calls. A later renderer may replace the private adapter rather than inherit an unsuitable 2D abstraction.
Risks
Backend-dependent pixels/performance, driver availability, DPI/event differences, untrusted asset decoders and dependency updates. Synthetic event injection proves queue plumbing only; actual keyboard/focus/DPI acceptance stays in M9.2/M9.3. No user assets are decoded by this probe. Retain upstream third-party notices alongside the SDL license for distribution; audit the enabled build at packaging.
Consequences and evidence
Preparation is explicit; missing sources fail with instructions. An ordinary headless configure never evaluates SDL. Upgrades change version and hash together, rerun platform probes and review upstream changes. Client rendering is approximate presentation, never authoritative biological state.
Primary sources checked 2026-10-01:
- SDL 3.4.16 release: stable bugfix release, active release maintenance.
- SDL 2D API: primitives/textures and main-thread requirement.
- SDL GPU API: alternative explicit pipeline API.
- License/build/platform documentation is retained in the pinned source archive
(
LICENSE.txt,docs/README-cmake.md,docs/README-platforms.md).