sdl: ship SDL3 alongside SDL2

[edumeneses]

Closes #6.

Adds an SDL3 3.4.14 build to every platform that already builds SDL2, installed to $INSTALL_PREFIX/SDL3 next to the existing $INSTALL_PREFIX/SDL2. This unblocks the gamepad work — the releases are no longer stuck on SDL2.

SDL3's ABI has been stable since 3.2.0 (Jan 2025); the breaking API churn all predates it and upstream is now on its 15th stable release. Nothing left to wait for.

Why SDL2 stays

I looked at whether this could be contained to this repo. It can't be, if SDL2 is replaced. libossia is the actual consumer and it is SDL2-only in three separate places:

Where	What
src/ossia/protocols/joystick/{joystick,game_controller}_protocol.cpp, joystick_manager.hpp	SDL2 spellings throughout — SDL_JoystickOpen, SDL_NumJoysticks, SDL_JoystickGetDeviceInstanceID, the whole SDL_GameController* family, SDL_CONTROLLER* event enums. All renamed or restructured in SDL3.
src/ossia/audio/sdl_protocol.hpp	SDL_OpenAudioDevice's callback form + SDL_GetAudioDeviceStatus, replaced by audio streams in SDL3.
cmake/deps/sdl.cmake, cmake/OssiaOptions.cmake (and score's CMakeLists.txt)	find_package(SDL2 CONFIG) → ossia::sdl2, and prefix paths pointing at $OSSIA_SDK/SDL2.

Swapping SDL2 out from under that would silently flip OSSIA_ENABLE_SDL to FALSE, and score's score_assert_feature(sdl) turns that into a hard failure on any deployment build. Side-by-side keeps every sdkNN tag consumable by today's score while the port lands in libossia; dropping SDL2 afterwards is then a mechanical delete of SDL_VERSION and the four sdl.sh scripts.

Happy to switch this to a hard replace if you'd rather sequence it the other way — it's a one-line change to each CMAKE_INSTALL_PREFIX.

Flag translation

The SDL2 flag sets carried over to SDL3, with the differences that matter:

• Gone as options (SDL3 always builds them): SDL_EVENTS, SDL_FILE, SDL_ATOMIC, SDL_THREADS, SDL_TIMERS, SDL_LOADSO, SDL_CPUINFO, SDL_FILESYSTEM, SDL_LIBSAMPLERATE, SDL_DLOPEN, SDL_SYSTEM.
• SDL_STATIC_PIC → CMAKE_POSITION_INDEPENDENT_CODE.
• SDL_UNIX_CONSOLE_BUILD is required on Linux. Since we build with both SDL_X11=0 and SDL_WAYLAND=0, SDL3 otherwise hard-stops at configure: SDL could not find X11 or Wayland development libraries on your system.
• SDL_HIDAPI / SDL_HIDAPI_JOYSTICK set explicitly — these are what make the extra gamepad surface (PS4/PS5 rumble, gyro/accel, touchpad fingers) reachable at all.
• SDL_TESTS defaults ON for a top-level SDL3 project, so it plus SDL_TEST_LIBRARY / SDL_EXAMPLES / SDL_INSTALL_CPACK are turned off.
• macOS drops the framework Resources → cmake symlink: SDL_FRAMEWORK defaults OFF in SDL3 and the install lands a normal lib/cmake/SDL3 tree.
• The IBUS_FOUND -> 0 sed isn't carried over — SDL3 guards that block behind SDL_IBUS, already 0.
• SDL_DYNAMIC_API=0 moved from -DCMAKE_C_FLAGS into $CFLAGS/$CXXFLAGS. Passing CMAKE_C_FLAGS on the command line makes cmake ignore the environment, which dropped everything common.sh sets — including macOS's -arch, so the cross-built x86_64 leg was getting host-arch objects. Worth fixing in macOS/sdl.sh too, but I left SDL2 untouched here.

Core hash

SDL3_VERSION sits outside the allowlist in .github/actions/core-hash, so this rotates the media stage only — verified the hash is byte-identical to master:

branch: 3e7c834e268d4f74a66851465e71a42baccd5201d9587e0d33cfb9cb4dc0549b
master: 3e7c834e268d4f74a66851465e71a42baccd5201d9587e0d33cfb9cb4dc0549b

Testing

Ran Linux/sdl3.sh end to end on linux-x86_64 in a container-shaped harness (/image + bind-mounted common/, so the ./common/clone-sdl3.sh and ../common/versions.sh source paths are exercised as they are in CI):

• clone-sdl3.sh fetches and patches the tarball; the #error Nope deletion is load-bearing — without it the build fails on SDL_dynapi.c and the PCH.
• Static lib builds and installs; find_package(SDL3 REQUIRED CONFIG) resolves from the prefix, SDL3::SDL3-static links, and the binary runs SDL_Init(JOYSTICK|GAMEPAD|HAPTIC|SENSOR) successfully against a video-less, audio-less build → SDL 3.4.14, joysticks: 0.
• Joystick drivers reported by configure: hidapi linux virtual.
• dynapi indirection compiled out (no SDL_InitDynamicAPI), zero absolute 32-bit relocations, and SDL_RumbleGamepad / SDL_SetGamepadSensorEnabled / SDL_GetGamepadTouchpadFinger all present in the archive.
• bash -n clean on all ten touched scripts.

macOS and Windows are unverified locally — that's what this PR's CI run is for.

Not touched

• AArch64/ gets an sdl3.sh for consistency but isn't in CI (its common.sh is a dangling symlink into /home/jcelerier/...).
• MSVC/sdl.ps1 left alone — pins Visual Studio 2017 and SDL 2.0.9, not wired into any workflow.
• WASM has no SDL at all; libossia uses emscripten's -sUSE_SDL=2 port. Moving that to --use-port=sdl3 is a libossia-side change.

Follow-up

The libossia port is the other half of this. I can take it next: ~130 SDL references across 6 files, plus deps/sdl.cmake and the prefix paths in OssiaOptions.cmake / score's CMakeLists.txt. Mostly mechanical renames; the audio engine's callback → stream conversion is the only real rewrite.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TTUi76cnUWh7dGZC64LqbZ

[jcelerier]

one thing to check with SDL: that it doesn't break the SDL API shipped by emscripten, I don't know if they updated to SDL3 too

[edumeneses]

Checked. Short version: this PR can't touch the emscripten SDL, and emscripten did add SDL3 — but its port is marked experimental, which makes it a real question for the libossia half rather than this one.

This PR doesn't go near WASM

The WASM SDK never built SDL at all — there is no WASM/sdl.sh, WASM/all.sh doesn't call one, and grep -riI sdl WASM/ is empty. WASM's SDL comes entirely from emscripten's own bundled port, requested in two places on the consumer side:

• libossia/cmake/deps/sdl.cmake — the CMAKE_SYSTEM_NAME MATCHES Emscripten branch, -s USE_SDL=2 as compile + link options on ossia::sdl2
• score/src/app/CMakeLists.txt:20 — add_link_options("SHELL:-sUSE_SDL=2")

This PR only adds sdl3.sh to Linux / macOS / MSYS / AArch64 plus common/clone-sdl3.sh, and doesn't touch WASM/ or wasm.yml. The WASM leg is already green on this branch.

Emscripten has SDL3, flagged experimental

tools/ports/sdl3.py exists and is present at tag 5.0.5, which is exactly our EMSDK_VERSION pin — so the toolchain we ship can already do it. Selector is -sUSE_SDL=3 (needed() returns settings.USE_SDL == 3). Caveats:

	emscripten sdl2 port	emscripten sdl3 port
SDL version	2.32.10 — same as our SDL_VERSION	3.4.2 — behind the 3.4.14 this PR builds natively
status	no warning, not deprecated	diagnostics.warning('experimental', 'sdl3 port is still experimental')
joystick	emscripten driver	SDL_JOYSTICK_EMSCRIPTEN 1 + SDL_JOYSTICK_VIRTUAL 1
haptic / sensor	dummy	dummy
threads	—	SDL_THREADS_DISABLED 1, with a separate sdl3-mt variant for PTHREADS=1

So the capability is there and joystick specifically is fine. The friction is the experimental warning, the 3.4.2-vs-3.4.14 skew, and the threads variant.

Where it actually bites

OSSIA_PROTOCOL_JOYSTICK defaults ON and is not gated off for emscripten, so joystick_protocol.cpp / game_controller_protocol.cpp are compiled on the WASM leg today against emscripten's SDL2. Since that's one codebase, porting it to SDL3 forces a choice on the WASM leg:

1. move it to -sUSE_SDL=3 and accept the experimental port (+ pick sdl3-mt if the wasm build wants pthreads), or
2. gate OSSIA_PROTOCOL_JOYSTICK off for emscripten and drop gamepad support in the browser.

I'd lean on (1) — browser gamepads come from the Gamepad API either way and the emscripten joystick driver is enabled in the SDL3 port's build config — but that's your call and it belongs in the libossia PR, not here. Nothing about it changes this diff.

Worth noting the side-by-side layout helps here specifically: because the SDK keeps shipping SDL2 2.32.10 (matching emscripten's sdl2 port exactly), you can move native to SDL3 and leave the WASM leg on SDL2 for a while if the experimental port turns out to be a problem.

[edumeneses]

Opened #28 to track removing the transitional SDL2 build once libossia is ported, so the side-by-side layout doesn't quietly become permanent.

[edumeneses]

@jcelerier one decision needed from you before the libossia side starts — flagging it here rather than guessing, since it changes the shape of that PR.

Edu and I went through the options internally first; this is the one we couldn't settle without you.

OSSIA_PROTOCOL_JOYSTICK is ON by default and isn't gated off for emscripten, so joystick_protocol.cpp / game_controller_protocol.cpp compile on the WASM leg today against emscripten's SDL2 port. It's one codebase, so porting it to SDL3 forces a choice:

1. Move WASM to -sUSE_SDL=3. Works — the port exists at our EMSDK_VERSION=5.0.5 pin and has SDL_JOYSTICK_EMSCRIPTEN/SDL_JOYSTICK_VIRTUAL enabled. Costs: emscripten still prints sdl3 port is still experimental, the port ships SDL 3.4.2 against 3.4.14 natively, and its build config sets SDL_THREADS_DISABLED unless you take the sdl3-mt variant.
2. Gate OSSIA_PROTOCOL_JOYSTICK off for emscripten. No experimental dependency, but no gamepads in the browser.
3. Keep WASM on SDL2 for now. Possible only because sdl: ship SDL3 alongside SDL2 #27 keeps shipping SDL2 2.32.10, which matches emscripten's sdl2 port version exactly — native goes SDL3, WASM stays put. Costs an #if defined(__EMSCRIPTEN__) split through the joystick code, which is the ugliest of the three to maintain.

Our read is (1): browser gamepads come from the Gamepad API either way, the experimental warning looks like caution about API coverage we don't use (video/render/GPU) rather than about joystick, and (3)'s dual-API code is the thing we'd least like to live with. But you know what the wasm build actually needs from pthreads and how much you want to lean on an experimental emscripten port, so it's your call.

Happy to go with (2) if you'd rather keep the WASM leg conservative — score's browser build losing gamepad input is a much smaller loss than the native releases staying on SDL2.

---

Written by Claude (Anthropic), acting as Edu's assistant — Edu has reviewed the analysis above.

[jcelerier]

note that for SDL2 it's not part of the WASM sdk we build because it's already a built-in part of the emscripten SDK

[jcelerier]

in any case the best would be to do a complete WASM build with this sdk and enforce SDL3, and verify that it works

[edumeneses]

CI verdict from the first run, and a fix pushed for the two real failures.

Build SDK WASM: green. Build SDK: 3 of 13 jobs failed — all six cores green, media-linux-x86_64 / media-linux-aarch64 / media-windows-arm64 green.

media-macos-arm64 and media-macos-x86_64 — my fault, fixed in 900b4c0

Both trace to one decision in the first commit: I passed $CFLAGS through to SDL3 instead of overriding CMAKE_C_FLAGS the way sdl.sh does. I'd treated the override as a latent bug (it silently drops -arch, so the x86_64 leg builds host-arch objects) — turns out it was also load-bearing, because it hid the rest of macOS/common.sh's flags from SDL.

• arm64: -ffast-math reaches the compiler and SDL_audiotypecvt.c guards a #pragma STDC FENV_ACCESS ON behind __aarch64__ + clang ≥ 12 → error: '#pragma STDC FENV_ACCESS ON' is illegal when precise is disabled. Fixed with -fno-fast-math for this build only.
• x86_64: CPUFLAGS carries -arch x86_64 -arch x86_64h, and SDL3 (unlike SDL2) compiles through a PCH → clang: error: cannot use 'precompiled-header' output with multiple -arch options. Fixed with CMAKE_DISABLE_PRECOMPILE_HEADERS. Unavoidable for a fat build however the arch reaches clang — routing it via CMAKE_OSX_ARCHITECTURES still emits both -arch on one invocation.

I kept the passthrough rather than reverting, since fat objects are the point of that leg. Neither linux common.sh nor MSYS sets -ffast-math or a second -arch, which is why those legs were already green.

media-windows-x86_64 — infra flake, not this branch

curl: (28) Failed to connect to www.libsdl.org:443 after 21089 ms: Could not connect to server
tar (child): SDL2-2.32.10.tar.gz: Cannot open: No such file or directory
CMake Error: The source directory "D:/a/sdk/sdk/MSYS/SDL2-2.32.10" does not exist.

That's the existing common/clone-sdl.sh failing to reach libsdl.org for the SDL2 tarball — windows-arm64 pulled the same file fine in the same run. clone-sdl3.sh fetches from github.com and didn't flake. Incidentally an argument for your plan below: moving sdl.sh to SDL3 also moves it off libsdl.org.

[edumeneses]

The libossia + score halves are up as drafts, so the prerequisite for your plan on #28 is in place:

• sdl: port the joystick, gamepad and audio backends to SDL3 libossia#922 — the API port. Joystick/gamepad renames, the index-based enumeration rebuilt on SDL_GetJoysticks(), rumble caps moved to properties, and the audio engine rewritten onto SDL_OpenAudioDeviceStream + SDL_PutAudioStreamData. WASM moved to -sUSE_SDL=3.
• sdl: consume SDL3 from the SDK score#2176 — prefix paths, ossia::sdl3, -sUSE_SDL=3, submodule bump.

Two findings that matter for this PR:

The SDK's SDL_AUDIO=0 doesn't break the audio engine. A -DSDL_AUDIO=0 SDL3 build still exports SDL_OpenAudioDeviceStream, SDL_PutAudioStreamData, SDL_ResumeAudioStreamDevice, SDL_DestroyAudioStream and SDL_AudioStreamDevicePaused. So sdl_protocol.hpp no longer needs the SDL_config.h / SDL_AUDIO_DISABLED guard at all — which is just as well, since SDL3 doesn't install SDL_build_config.h.

avendish needs no PR. Its bare SDL2 link references are all behind the if(1) short-circuit or an if(TARGET ossia::ossia) score never enters — no link.txt in a configured build mentions SDL2.

Still open on your side: the full WASM build with SDL3 enforced. That's the one thing I can't verify from here, and it's your explicit gate. Once it passes I'll flip this PR to modify sdl.sh in place per #28 and drop the side-by-side SDL2.

---

Written by Claude (Anthropic), acting as Edu's assistant.

[edumeneses]

Correction to something I asserted earlier in this PR and in #28, since it was load-bearing for the side-by-side argument.

I said score's deployment builds hard-fail when the sdl feature goes missing. They don't. score_assert_feature is a no-op:

function(score_assert_feature name)
  if(NOT "${name}" IN_LIST "${SCORE_FEATURES_LIST}")
    list(APPEND SCORE_MISSING_FEATURES "${name}")   # no PARENT_SCOPE
  endif()
endfunction()

Two problems: list(APPEND) inside a function() without PARENT_SCOPE never reaches the variable the later FATAL_ERROR tests, and IN_LIST is handed a dereferenced "${SCORE_FEATURES_LIST}" when it wants the list's name. Confirmed with a minimal CMake repro: asserting a definitely-missing feature leaves SCORE_MISSING_FEATURES empty. Same applies to score_assert_plugin. That also explains how the Debian legs pass today with their libsdl2-dev lines commented out.

What this changes: dropping SDL2 before libossia is ported loses the joystick protocol and the SDL audio engine from the releases silently rather than failing the build. Still a reason not to swap it out from under un-ported consumers, but a weaker one than I gave. Pushed ee21443 to fix the comment in versions.sh that repeated the wrong claim.

I have not touched score_assert_feature itself — that's an unrelated latent bug, and fixing it would turn several legs red at once. Worth its own issue in ossia/score if you want it.

One more thing the port surfaced, in ossia/score#2176: the prefix-path change only covers $OSSIA_SDK consumers. The flatpak had no SDL module at all and was taking SDL2 from the org.kde.Platform runtime, so it needed SDL3 bundled like every other dep in that manifest. And of the distro legs, only Debian trixie/sid and Ubuntu plucky/questing actually ship libsdl3 — jammy, noble, lunar and oracular have none, so those lose the joystick protocol until someone decides whether to build SDL3 from source there.

---

Written by Claude (Anthropic), acting as Edu's assistant.