======================
sdl2-compat for Debian
======================

sdl2-compat is a compatible reimplementation of the SDL 2 interface
using SDL 3. In some non-Debian distributions like Arch and Fedora, it has
completely replaced "classic" SDL2.

In Debian, we hope to do the same before the Debian 14 freeze, but more
testing is needed first!

sdl2-compat can even be combined with sdl12-compat (the `libsdl1.2debian`
package) to run SDL 1.2 games on SDL 3, but if possible please port those
games to SDL 2 or SDL 3 instead.

Installation and use
====================

There are two configurations you can use for testing sdl2-compat.

1. "classic" SDL2 is the default, sdl2-compat available as opt-in

    This is how it worked in Debian 13. Install with:

        $ sudo apt install libsdl2-2.0-0 libsdl2-compat

    To test a game with "classic" SDL2, just run it as normal.

    To test a game with sdl2-compat, use a command like:

        $ SDL2COMPAT_DEBUG_LOGGING=1 \
          SDL_DYNAMIC_API='/usr/$LIB/sdl2-compat/libSDL2-2.0.so.0' \
          openarena

    You should see output like:

        sdl2-compat 2.32.57, built on Sep 10 2025 at 12:31:43, talking to SDL3 3.3.0
        sdl2-compat: This app appears to be named: ioquake3
        SDL_DYNAMIC_API: Not overridden

2. sdl2-compat is the default, "classic" SDL2 available as opt-in

    This is a preview of how we hope SDL2 will work in Debian 14
    (if all goes well, "classic" SDL2 might be removed completely).
    Install with:

        $ sudo apt install libsdl2-compat-shim libsdl2-classic

    If you need SDL2 development files available, you will also need to
    remove libsdl2-dev and replace it with libsdl2-compat-dev.
    They should be compatible, but are not identical.
    Please use libsdl2-dev for build-dependencies and uploads to Debian.

    To test a game with "classic" SDL2, use a command like:

        $ SDL2COMPAT_DEBUG_LOGGING=1 \
          SDL_DYNAMIC_API='/usr/$LIB/sdl2-classic/libSDL2-2.0.so.0' \
          openarena

    You should see output like:

        sdl2-compat 2.32.57, built on Sep 10 2025 at 12:31:43, talking to SDL3 3.3.0
        sdl2-compat: This app appears to be named: ioquake3
        SDL_DYNAMIC_API: Library replaced by SDL 2.32.10 (SDL-release-2.32.10-0-g5d2495703 (Debian 2.32.10+dfsg-3))

    To test a game with sdl2-compat just run it as normal, but before
    reporting bugs, double-check it with debug logging enabled:

        $ SDL2COMPAT_DEBUG_LOGGING=1 \
          openarena

    This time you should see output like:

        sdl2-compat 2.32.57, built on Sep 10 2025 at 12:31:43, talking to SDL3 3.3.0
        sdl2-compat: This app appears to be named: ioquake3
        SDL_DYNAMIC_API: Not overridden

Wayland
=======

On Wayland, some SDL 2 games don't work correctly with the native Wayland
video driver, which became the default in SDL 3.
For such games, you might need to set environment variable
SDL_VIDEODRIVER=x11, which forces all SDL 2 games to use X11 (possibly
via Xwayland).

sdl2-compat has a table of "quirks" for games and apps that cannot
easily be fixed, which can be applied automatically based on the name of
the executable. One of the most common quirks is to do the equivalent of
`SDL_VIDEODRIVER=x11` automatically.

Testing
=======

Before reporting bugs with sdl2-compat, please check whether the game works
as intended with "classic" SDL2. If not, report it as a game bug, or as a
`libsdl2-2.0-0` bug with "affects" on the game.

Then test with sdl2-compat, and report bugs for any regressions when
compared with "classic" SDL2:

* upstream: https://github.com/libsdl-org/sdl2-compat/issues/new
* and/or in Debian: as bugs in `libsdl2-compat`, or as bugs in the game
    with an "affects" on `libsdl2-compat` if it appears to be a game bug

Please provide details of the game version, the sdl2-compat version,
and the SDL3 version. SDL2COMPAT_DEBUG_LOGGING=1 will tell you everything
except the game version.

If you are using a Wayland environment, please specify which one.
"Wayland" is not enough information: we'll need something more like
"GNOME Shell 48.4" or "sway 1.11".

If a game doesn't work in native Wayland, please try it with
`SDL_VIDEODRIVER=x11` as a workaround, and mention in your bug report
whether that workaround helped or not.

There will often be a newer version of SDL3 and/or sdl2-compat available
in experimental, which might have additional bug fixes. If you can,
trying that version is also helpful. Versions in experimental are often
upstream snapshots that have only been lightly tested, so there might be
regressions - please report those too!

See `HOW_TO_TEST_GAMES.md` in the source package for more details.