fix(macos): bundle SDL3 for sdl2-compat at install time - #1226
Merged
Conversation
Homebrew replaced its `sdl2` formula with `sdl2-compat`, a compatibility layer that provides the SDL2 API by `dlopen`-ing the real SDL3 library at runtime. The macOS CI build (`build-macos.yml`) pulls this via `brew install mpv`, so the app now links `libSDL2-2.0.0.dylib` which is actually `sdl2-compat`, and every nightly ships it in `Contents/Frameworks`. SDL3 is not a linker dependency, so it never shows up in `otool -L` output and the `CompleteBundleMac` fixup loop never copies it into the app bundle. At runtime `sdl2-compat` looks for `libSDL3.dylib` relative to its own loader path, cannot find it, prints "Failed loading SDL3 library." and aborts during dyld initialization, since the library is missing. This regression appeared once Homebrew's SDL2 became the `sdl2-compat` shim, so older nightly builds (built against genuine SDL2) are unaffected. This detects `sdl2-compat` inside the bundle (it is the only `libSDL2-2.0.0.dylib` containing the `libSDL3.dylib` loader string) and explicitly copies libSDL3 from the Homebrew prefix into `Contents/Frameworks/libSDL3.dylib`, using the same `install-id` convention as the other bundled dylibs so `codesign` and the existing fixup steps keep working. If SDL3 cannot be found at install time a warning is printed instead of failing silently. Fixes jellyfin#1225
Test Coverage |
nielsvanvelzen
approved these changes
Aug 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Homebrew replaced its
sdl2formula withsdl2-compat, a compatibility layer that provides the SDL2 API bydlopen-ing the real SDL3 library at runtime. The macOS CI build (build-macos.yml) pulls this viabrew install mpv, so the app now linkslibSDL2-2.0.0.dylibwhich is actuallysdl2-compat, and every nightly ships it inContents/Frameworks.SDL3 is not a linker dependency, so it never shows up in
otool -Loutput and theCompleteBundleMacfixup loop never copies it into the app bundle. At runtimesdl2-compatlooks forlibSDL3.dylibrelative to its own loader path, cannot find it, prints "Failed loading SDL3 library." and aborts during dyld initialization, since the library is missing. This regression appeared once Homebrew's SDL2 became thesdl2-compatshim, so older nightly builds (built against genuine SDL2) are unaffected.This detects
sdl2-compatinside the bundle (it is the onlylibSDL2-2.0.0.dylibcontaining thelibSDL3.dylibloader string) and explicitly copies libSDL3 from the Homebrew prefix intoContents/Frameworks/libSDL3.dylib, using the sameinstall-idconvention as the other bundled dylibs socodesignand the existing fixup steps keep working. If SDL3 cannot be found at install time a warning is printed instead of failing silently.Fixes #1225