linux: Wayland unavailable where libxkbcommon is older than 1.10 #289

SDL's Wayland driver probably doesn't load on Linux distributions whose libxkbcommon is older than 1.10. Ubuntu 24.04 ships 1.6, Debian 12 ships 1.5. If so, fizzy falls back to X11 there (XWayland on a Wayland desktop), losing the Wayland-only work: frame insets for the drawn shadow (linux_titlebar.zig, SDL patch 6) and the compositor blur (wayland_blur.zig).

Found while doing #280 step A1 (fizzyedit/sdl_zig#1). The test binary there is built from the same sdl_zig as fizzy. On the ubuntu-24.04 runner under headless weston, SDL_VIDEO_DRIVER=wayland failed with "wayland not available" while X11 worked. In an ubuntu:26.04 container the same binary worked on Wayland. I haven't yet run a fizzy binary on 24.04 to confirm it there.

Cause

• sdl_zig builds SDL against libxkbcommon 1.13.2's headers (build.zig.zon, .xkbcommon), and src/linux.zig sets SDL_XKBCOMMON_VERSION_* from that dependency's version.
• SDL loads libxkbcommon at runtime (SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_XKBCOMMON = "libxkbcommon.so.0"). Which symbols it requires is decided at compile time by SDL_XKBCOMMON_CHECK_VERSION.
• src/video/wayland/SDL_waylandsym.h requires xkb_keymap_mod_get_mask as SDL_WAYLAND_SYM (not _OPT) when built against 1.10 or newer. On an older libxkbcommon the lookup fails, and the whole Wayland driver reports itself unavailable.
• SDL_waylandevents.c has a fallback path that builds the masks from xkb_keymap_mod_get_index, but which path is used is also decided at compile time.

Upstream main and release-3.4.x are the same, so this isn't something fizzy's patches introduced. It only bites builds like ours, which compile against newer headers than the machines they run on. Distribution packages compile against their own libxkbcommon.

I checked the other version-gated symbols in SDL_waylandsym.h. They need wayland 1.20 (2021) and xkbcommon 1.0 (2020), which every supported distribution has. Only the 1.10 symbol is a problem.

Fix

Recommended: an SDL patch, written to go upstream. Make xkb_keymap_mod_get_mask an SDL_WAYLAND_SYM_OPT. At runtime, use it when it loaded and fall back to the mod_get_index path otherwise, so both paths are compiled whenever the headers are 1.10 or newer. That fits SDL's own reason for loading these libraries dynamically (one binary across distributions), so upstream should take it. It goes on fizzy-3.4 as patch 8, with an upstream PR (#280 Track C).

Rejected: pinning sdl_zig's xkbcommon headers to an older release, or lying about the version. Either silently drops the 1.10 path everywhere, so it is a workaround, not a fix.

Test (#280 Track A, so it can't come back): a test-fizzy suite that starts the Wayland driver under headless weston and checks that the keyboard modifier masks come out right. CI runs it in an ubuntu:24.04 container, the oldest distribution we support. It must fail on the current fork and pass with the patch. More generally, the Linux test jobs should run on the oldest supported distribution as well as a current one. That would have caught this.

Part of #280.

🤖 Generated with Claude Code