Implement M9.1 scoped SDL3 native client dependency probe
This commit is contained in:
@@ -2,7 +2,8 @@
|
||||
|
||||
## Status
|
||||
|
||||
Dependency-free proof adopted; vcpkg manifest proposed at first dependency gate.
|
||||
Dependency-free proof adopted; general package-manager comparison remains open.
|
||||
ADR-0077 accepts a scoped explicit-source SDL dependency for M9 only.
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# 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. M9.2 will introduce the actual platform/render boundary.
|
||||
|
||||
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](https://github.com/libsdl-org/SDL/releases/tag/release-3.4.16): stable bugfix release, active release maintenance.
|
||||
- [SDL 2D API](https://wiki.libsdl.org/SDL3/CategoryRender): primitives/textures and main-thread requirement.
|
||||
- [SDL GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU): 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`).
|
||||
@@ -87,3 +87,5 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
- [ADR-0074: World backup bundles and verified restore](0074-world-backup-and-restore.md) - accepted for M8.7 snapshot-consistent online bundles (dump + immutable objects + manifest), fail-closed audited restore on independent storage, isolated rebuild through clones; destination, encryption, schedule and WAL archiving pending.
|
||||
- [ADR-0075: World0 acknowledgment gate, host-loss recovery and promotion](0075-world0-acknowledgment-gate.md) - accepted for M8.8 ratified dev/stage RPO/RTO, World0 launch blocked (policy-enforced) until acknowledgements survive host loss in an independent failure domain, explicit-rewind in-place restore, barrier-based fencing of a superseded database, promotion only of stage-pinned digests.
|
||||
- [ADR-0076: Upgrade rehearsal on clones, version barrier in dev/stage, and node growth](0076-upgrade-and-growth.md) - accepted for M8.9 accelerated clone runs compared state-for-state before a build change, failed-migration recovery, guarded in-cluster barrier, stores/compute node labels with policy-checked placement.
|
||||
|
||||
- [ADR-0077: Scoped native client dependencies](0077-scoped-native-client-dependencies.md) - SDL 3.4.16 window/events and 2D renderer for the opt-in M9.1 probe; no simulation dependency.
|
||||
|
||||
Reference in New Issue
Block a user