Bug#1130484: transition: src:sdl2-compat taking over libsdl2-2.0-0, libsdl2-dev

[Simon McVittie]

Package: release.debian.org
Severity: normal
X-Debbugs-Cc: sdl2-compat at packages.debian.org, debian-devel-games at lists.debian.org
Control: affects -1 + src:sdl2-compat
User: release.debian.org at packages.debian.org
Usertags: transition

SDL upstream is in the process of phasing out "classic" src:libsdl2 (an 
independent library), replacing it with src:sdl2-compat (a compatibility 
shim which dlopens libsdl3 and uses it to implement the SDL 2 API/ABI).  
This is very similar to the transition from src:libsdl1.2 to 
src:sdl12-compat that we did in trixie 
(https://bugs.debian.org/1039911). Faster-moving distributions like Arch 
and Fedora have already made this switch, and I think it's time for 
Debian to do the same.

This is a "soft" transition with no SONAME bump: the new library is 
intended to be fully API- and ABI-compatible with the old (same SONAME, 
same pkg-config module name, same CLI interface to the legacy 
sdl2-config script, different implementation internally), so it's more 
like an unusually intrusive minor-version release. After approving the 
transition, the release team will hopefully not need to take any further 
action.

src:sdl2-compat in experimental already implements the proposed design.

I intend to keep src:libsdl2 in the archive, at least initially: that 
way, users who encounter a regression can install the libsdl2-classic 
package and force its use via environment variables as documented in 
<https://salsa.debian.org/sdl-team/sdl2-compat/-/blob/debian/snapshots/debian/README.Debian?ref_type=heads>.  
It should probably be removed before forky+1, or perhaps before forky if 
the transition goes particularly well.

Risks
=====

I did a mass-rebuild, partly on debusine and partly locally or on 
porterboxes. All 3 FTBFS bugs found (test failures) have been fixed by 
improvements to the affected packages. I've also tested an assortment of 
SDL 2 games (and SDL 1.2 games via sdl12-compat), and asked -devel and 
the games team to help with testing (back in September 2025) with no 
regressions reported as a result.

As with the SDL 1.2 transition, it isn't really feasible for me to test 
every SDL 2 game myself, and I generally haven't been testing non-game 
applications that use SDL (many of which are emulators requiring ROMs 
that I don't have, or specialized music apps that I don't know how to 
use).

Known regressions are listed here, and at the time of writing have all 
been fixed: 
<https://bugs.debian.org/cgi-bin/pkgreport.cgi?users=sdl2-compat@packages.debian.org;tag=regression>

The API/ABI is the same, but there are various subtle behaviour changes 
between libsdl2 and sdl2-compat that could break games' expectations 
(especially if they are relying on behaviours that were never intended 
to be guaranteed), either as a result of intentional changes or as a 
result of SDL bugs. The ones I know about are:

* "Classic" SDL 2 defaults to X11, via Xwayland if necessary.
  sdl2-compat defaults to native Wayland if a sufficiently capable
  compositor is detected. This will break games that blindly assume
  that Unix implies X11, and could also expose Wayland-related bugs that
  were previously hidden, such as <https://bugs.debian.org/1124335>. The
  correct fix for a game that assumes X11 is to make the game tell SDL
  "use only X11", but for proprietary games or games that are otherwise
  hard to modify, sdl2-compat has a "quirks" table that can automatically
  force X11 based on the name of the executable.

* libsdl3 has a Vulkan backend for the rendering API, which sdl2-compat
  will use if appropriate. It is unlikely to be perfectly bug-for-bug
  compatible with the OpenGL or software backends. If necessary,
  sdl2-compat's quirks table can be used to work around this.

* sdl2-compat has slightly different behaviour around paletted
  (256-colour) windows and textures, which caused a regression for the
  autopkgtest and build-time tests of the SDL 1.2 Perl binding. I worked
  around this in sdl12-compat for now, but when we switch to sdl2-compat
  we'll want to do a coordinated upload of sdl12-compat reverting that
  workaround.

The only autopkgtest regression listed in 
https://qa.debian.org/excuses.php?experimental=1&package=sdl2-compat is 
for yuzu on arm64, but yuzu isn't in testing (*because* it's broken on 
arm64, in fact) so this shouldn't prevent transition.

    smcv