Create SDL3 stub library (.tbd) for use by the xcode projects of SDL satellite libraries

[madebr]

The xcode projects of all SDL satellite libraries require SDL to be checked out as a submodule.
Example: SDL_Image/Xcode/SDL_image.xcodeproj.

I think it would be useful to create a tbd (text-based description) of the SDL3 framework and use that instead in the satellite projects.
Looks like tapi/tapi-stubify does this job

Advantages:

• When adding both SDL_ttf.xcodeproject and SDL_image.xcodeproject to a project, SDL.xcodeproject is not added twice
• Creating a binary SDL_image dmg release would become a lot easier

[madebr]

Can anyone try the attached tbd?
The installed name needs to be changed to whether you're using a SDL3 framework or dylib.

SDL3.tbd.zip

I used the tests of https://github.com/apple-oss-distributions/tapi as reference.

edit: updated the zip

[slouken]

How do we use it?

[madebr]

I don't know :)

I think you should just link to the stub instead of the dylib or framework.
Apple uses tbd files themselves for system libraries.
I don't know exactly how install-name should look like, so try removing the comment, try a single libSDL3.dylib.0, try SDL3.framework/Versions/A/SDL3, ...
And look for inspiration in your system tbds.

[slouken]

Okay, I’ll do some research on it next week.

[sezero]

How do we use it?

In SDL3.framework/Versions/A should reside SDL3.tdb instead of binary SDL3: Apple's ld (if it's new enough which for most if not all users it will be and be linked to Apple's liptapi) will use it for linking programs to SDL3 framework. However, we are providing binaries, i.e. not just for linking to but for running against, therefore I don't know whether this is something we want in our releases.

BTW, using TAPI version 1300.6.5 (1300.6.5), running tapi stubify SDL3 an linux on the SDL3 fat binary of 3.1.3 preview, I get this tbd: SDL3.tbd.zip

[madebr]

However, we are providing binaries, i.e. not just for linking to but for running against, therefore I don't know whether this is something we want in our releases.

It's useful for faster ci, and also useful for the satellite xcode projects to not need a pre-built SDL framework.
We can drop SDL from external, and people can combine the SDL3, SDL3_image, and SDL3_mixer xcode projects without worrying about building SDL3 three times.

[sezero]

It's useful for faster ci, and also useful for the satellite xcode projects to not need a pre-built SDL framework. We can drop SDL from external, and people can combine the SDL3, SDL3_image, and SDL3_mixer xcode projects without worrying about building SDL3 three times.

Thinking about it though, how are we going to run test programs e.g. in SDL_image without real SDL3.framework present?

[madebr]

This is purely about building the application, and let the user worry about where to get binaries.

It would be useful to generate something similar to sezero's tbds, but minus the magic numbers and also supporting all platforms (ios/tvos/macos/xros/..) on all archs.

[sezero]

This is purely about building the application, and let the user worry about where to get binaries.

I meant in CI

[madebr]

I meant in CI

This will not be useful for the SDL_image project (though, it will speed up creating SDL release artifacts a little bit), but only for those workflows that only build and don't test (or run the tests later).
See this related setup-sdl issue.

It would also allow to reduce the size of the SDL2_image source archive.
More then 66% of filesize is used by frameworks.

[FtZPetruska]

I have looked into how to use/generate TBDs. Here is what a minimal SDL3 tbd would look like for the current pre-release:

---
archs:           [ x86_64, arm64 ]
platform:        macosx
install-name:    '@rpath/SDL3.framework/SDL3'
current-version: 3.1.3
exports:         
  - archs:           [ x86_64, arm64 ]
    symbols:         [ <SDL public functions here> ]
...

While this "hardcodes" an install-name, it seems that @rpath can still be used, so there would not be any "if you use the tbd, you have to install the framework to the /X/Y/Z".

As to how it can be shipped, it can either be provided as a framework by substituting the SDL3 binary/symlinks with a SDL3.tbd file, or in a unix-like tree by replacing the libSDL3.*.dylib with libSDL3.*.tbd.

Interestingly, replacing a libSDL3.dylib with a tbd that specifies @rpath/SDL3.framework/SDL3 in the install-name will make you use the framework at runtime.

Here are some examples I crafted:

• based on the pre-release framework: framework-tbd.zip
• using a typical include/lib structure: lib-tbd.zip

They can both be linked like their binary counterpart (-F... -framework SDL3 for the framework, -L... -lSDL3 for the other), and both will let you run against the binary SDL3.framework from the 3.1.3 pre-release (don't forget to set the rpath).