SDL3, macOS: Installation is not Mac-like

[andreasgrabher]

With SDL2 installation of SDL from the provided .dmg was as simple as copying SDL2.framework to ~/Library/Frameworks or /Library/Frameworks. Now there is SDL3.xcframework and a folder called "share". I think non-experienced users won't know what to do with that folder. It is also not mentioned in the included INSTALL.md.

I'd like to suggest to include that "share" folder into the framework package if possible. If not, there should be a short instruction on how to properly install the framework.

[slouken]

I'm not sure what to do with the share folder either. @madebr, can you update INSTALL.md with the correct installation procedure?

Using the xcframework is just a matter of dragging it into your project. Maybe the share folder isn't needed in this case?

[maia-s]

The share folder in /Library/Frameworks/share is picked up automatically by cmake

Also, dragging the xcframework into your project only works if you have an Xcode project, which you won't have if you're using a language or build system not supported by Xcode

[andreasgrabher]

The folder contains files that seem to be required for CMake. To make CMake find SDL3, I have to copy the folder into the same location as SDL3.xcframework.

[andreasgrabher]

It is important to mention that SDL2 does not require that folder. CMake detects SDL2 without any problems. Therefore installation of SDL2 is much more straightforward.

[madebr]

The share folder is for CMake support indeed.

CMake does not search into xcframework folders.
Putting the CMake files in a parallel share folder was the only logical place to put the files.

I created an issue about this on CMake's tracker, but it looks like it has low priority. (Reply or upvote the issue to give it extra visibility)

[andreasgrabher]

Last question before closing this: What is the benefit from distributing SDL3 as an xcframework? Is this only relevant for developers or also for users?

[slime73]

The xcframework has libraries for all supported Apple platforms (tvOS, iOS, macOS) bundled within the single xcframework. The build system pulls the relevant one during the build process. It's a more modern way to do things on Apple platforms than having a single .framework bundle or separate loose frameworks.

[madebr]

@slouken
Would this be ok?

--- a/Xcode/SDL/pkg-support/resources/INSTALL.md
+++ b/Xcode/SDL/pkg-support/resources/INSTALL.md
@@ -3,7 +3,9 @@
 
 This package contains SDL built for Xcode, and includes support for macOS, iOS and tvOS.
 
-To use this package, drag SDL3.xcframework into your project.
+To use this package in Xcode, drag `SDL3.xcframework` into your project.
+
+To use this package in a CMake project, copy both `SDL3.xcframework` and `share` somewhere. Add the path of the parent folder to `-DCMAKE_PREFIX_PATH=` during configuration. 
 
 # Documentation
 

[slouken]

Yes, that would be fine. Did you test and verify that works?

[andreasgrabher]

I copy it to ~/Library/Frameworks or /Library/Frameworks. Then I don‘t have to set CMAKE_PREFIX_PATH.

[madebr]

Yes, that would be fine. Did you test and verify that works?

It's tested in release.yml, so yes :)

[madebr]

I copy it to ~/Library/Frameworks or /Library/Frameworks. Then I don‘t have to set CMAKE_PREFIX_PATH.

Isn't ~/Library/Frameworks for host frameworks? Not for cross-platform xcframeworks.
If you copy SDL3.xcframework/macOS-arm64_x64_64/SDL3.framework to ~/Library/Frameworks (remove the xcframework and share folder), then you don't have to copy the share folder.

[madebr]

See #12010

[andreasgrabher]

If you copy SDL3.xcframework/macOS-arm64_x64_64/SDL3.framework to ~/Library/Frameworks (remove the xcframework and share folder), then you don't have to copy the share folder.

If I do that, it won't copy the framework into my application bundle anymore. I am using this command to copy the framework to *.app/Contents/Frameworks:
cp -R $<TARGET_FILE:SDL3::SDL3-shared> ${BUNDLE_CONTENTS}/Frameworks/

It seems to copy SDL3 from inside the framework bundle (SDL3.framework/SDL3) instead of the whole bundle.

[madebr]

If you copy SDL3.xcframework/macOS-arm64_x64_64/SDL3.framework to ~/Library/Frameworks (remove the xcframework and share folder), then you don't have to copy the share folder.

If I do that, it won't copy the framework into my application bundle anymore. I am using this command to copy the framework to *.app/Contents/Frameworks: cp -R $<TARGET_FILE:SDL3::SDL3-shared> ${BUNDLE_CONTENTS}/Frameworks/

I meant to manually recursively copy the SDL3.framework folder into ~/Library/Frameworks.
After doing that, CMake should pick it up with find_package(SDL3 CONFIG).

I wouldn't bother with cp -R for frameworks on macOS: there is too much diversity on how you can get SDL3: build it manually, brew, framework, and now xcframeworks

[andreasgrabher]

I wouldn't bother with cp -R for frameworks on macOS: there is too much diversity on how you can get SDL3: build it manually, brew, framework, and now xcframeworks

There was the same problem before when using the xcframework: #11394. That problem was fixed. Maybe that fix was not done on all relevant files?

[madebr]

The file was not modified after the change done in #11394 (=removing /SDL3).
Configure with --trace-expand to confirm IMPORTED_LOCATION of SDL3::SDL3-shared is set to a path that ends with SDL3.framework and does not end with /SDL3.

[andreasgrabher]

I think I found the problem. It seems that it was forgotten to apply this patch c56a3f6 also to the file that is stored inside the framework bundle. It was only applied to the file that is stored inside the "share" folder. The appended patch fixes the problem.

cmake_sdl3.txt

[slouken]

Good catch! patch added, thanks!

[slouken]

I think with @andreasgrabher's fix and @madebr's documentation we're all set here, right?

[andreasgrabher]

Yes, problems are gone. Thank you!

[slouken]

Great, thanks for the feedback!