my little airport =)

4 min read

ADR-006: SDL is the v0.2.0 desktop frontend technology

Date: 2026-07-20

Status: Accepted

Context

v0.2.0 needs the first real desktop application and the first visual frontend. The frontend must render a small animated pet, receive keyboard and pointer input, handle window lifecycle, and remain separate from Pet Core.

The project also expects more frontends later, including embedded and hardware frontends. Choosing a desktop frontend must therefore prove the app and frontend boundary without making the desktop library the product architecture.

The Core already provides the required boundary shape: hosts call public Core APIs, receive PetSnapshot, and dispatch supported semantic actions. A desktop renderer does not need to enter the Core to do its work.

Decision

v0.2.0 uses SDL for the desktop visual frontend. The component lives under frontends/sdl, builds as pet_frontend_sdl, and is consumed by the apps/desktop executable pet_desktop.

SDL is a frontend dependency only. Pet Core must not include SDL headers, link SDL libraries, expose SDL types, or depend on an SDL event, clock, window, renderer, surface, texture, filesystem, or image loading API.

The SDL dependency is pinned during implementation. The pin may be a release version or an exact source commit, but it must be deterministic and recorded in build configuration. Local dependency override variables are allowed so development and offline rebuilds are possible without changing project source.

PNG loading for v0.2.0 uses the selected pinned SDL path when the pinned SDL version provides it. If the selected SDL pin does not provide the accepted PNG loading path, the image loading dependency must be separately pinned as a frontend dependency. In both cases the dependency stays outside Core.

Third-party headers and generated dependency files are not project code. Project warning, tidy, and formatting rules must not turn third-party diagnostics into Pet findings.

Consequences

SDL gives one portable desktop frontend target for Linux now and keeps a realistic path for native Windows and macOS work later. Only Linux desktop verification is required for v0.2.0; other platforms remain design goals until real evidence exists.

The dependency choice does not create a generic frontend support layer. The SDL frontend is the first real example. Shared frontend helpers wait until another frontend provides duplication evidence.

The desktop app can exercise the whole product path from platform input and time to Core state, snapshot, presentation role, animation, and rendering. That makes the release useful as a reference for future frontends.

The price is dependency management. SDL must be pinned, optionally overridden locally, isolated from project diagnostics, and disabled when the SDL frontend is not selected. Core-only and headless builds must continue to configure without SDL.

Alternatives considered

Raylib. Smaller and pleasant for quick graphical demos. Rejected because SDL is the stronger long-term desktop boundary for this project: input, window lifecycle, renderer control, and broader platform expectations matter more than the shortest demo path.

A terminal or text UI. Would avoid graphical dependencies. Rejected because v0.2.0 must prove visual frontend boundaries, assets, animation, and pointer input.

A custom platform window and renderer. Would reduce third-party dependency risk. Rejected because it spends the release on platform code instead of proving the product architecture.

A web frontend. Useful later, especially for rapid inspection. Rejected for this release because it would introduce a different runtime stack and would not help the near-term embedded and local desktop reference goals as directly.

Making SDL a host app dependency instead of a frontend dependency. Rejected because it would blur the app/frontend boundary. The app owns lifecycle and composition; the frontend owns rendering, assets, animation, and raw input classification.

References

Graph View