Install problem - Catalina


I’ve been using SDL2 successfully for a couple of months on a Catalina MacOS X laptop. I then wanted to set up a second Mac OS X Catalina machine, this time around using SDL2.0.14.

Normally I would copy the SDL2.frameworks directory into /Library/Frameworks/. Usually also I’ll set the owner to root and the group to wheel.

That’s what I’ve done in this case, however, whenever I click on the Xcode project, then click on the target, and look at the “Build Phases” tab, under the category “Link Binary With Libraries”, no matter what I do, the SDL2.framework does not appear in the drop-down list of frameworks that can be added after clicking the “+” button.

I’ve tried re-signing the sdl2 frameworks after copying them into /Library/Frameworks/

codesign -f -s - SDL2

Is there anything else I can try?

Thank you!


Copying frameworks into the system frameworks folder is a bad idea. Just put SDL2.framework in the same folder as your .xcodeproj, link to it in Xcode (hit the + and then hit Add Other..., then navigate to SDL2.framework), and Xcode will automatically set it to be copied to your application bundle when your application is built. If Xcode can’t find it when building your app, go into your project’s build settings and add the folder where SDL2.framework is located to Framework Search Path (if it’s in the same folder as your .xcodeproj it should find it, but :man_shrugging:)

Or put SDL2.framework somewhere in your user folder, link to it the same way mentioned above, and make sure your project’s build settings have that folder in the Framework Search Path.

Also, use the Finder to copy/move frameworks, since they’re special folders with symlinks inside pointing to other files/folders inside the framework that need to be preserved. In the past I’ve used the command line to copy them and they break.

If I follow the instructions above, my application builds, but when I run, I see:

0 __abort_with_payload
6 _dyld_start

Execution trace:
0x10009523c <+0>: movl $0x2000209, %eax
0x100095241 <+5>: movq %rcx, %r10
0x100095244 <+8>: syscall
-> 0x100095246 <+10>: jae 0x100095250 Thread 1: signal SIGABRT

dyld: Library not loaded:
Referenced from:
Reason: image not found
Message from debugger: Terminated due to signal 6
Program ended with exit code: 0

Not sure what to do.
Xcode 11.4.1 (11E503a), SDL2-2.0.12.dmg, macOS Catalina (Version 10.15.3)
MacBook Air, 13-inch, 2020

When macOS launches your app, it expects to find SDL2.framework and the actual framework binary inside the application bundle, but it can’t.

If you open your application bundle, is it in there? (in Xcode, in the Products group on the left, right click on, pick Show in Finder, right click on YourApp in the Finder window that comes up, pick Show Package Contents). What is in ? Did you copy SDL2.framework out of the .dmg using Finder, or the command line?

Does going to the Signing & Capabilities tab of your project’s build settings and checking Disable Library Validation work?

In the Build Phases tab of the project build settings, what does it say under Embed Frameworks?

Have you changed @rpath in your project’s build settings at all?

Does it work if you download the SDL source code, build it yourself, and use your own SDL2.framework ?

1 Like

Nothing. My project is a command-line executable project. It’s not a .app. Just a “Unix executable”.

I used the finder as suggested above.

There is no “Disable Library Validation” option for my command-line executable.

Under “Build Phases” I have just “Link Binary With Libraries” and I have manually added “SDL2.framework” and “OpenGL.framework”. Also there is a tab for “Compile Sources” and my 4 source files are there.

Not intentionally. I’ve also tried this whole process from the very start using a fresh project so presumably rpath would be whatever the default is.

I haven’t tried this yet. In the past I’ve always just used the prebuilt framework and it “just worked”. Is building from source now the only working option?

Just commenting to say I am having the same issue… getting the same error on XCode. I am on an Intel macbook pro (running Big Sur).

dyld: Library not loaded:
Referenced from:
Reason: image not found
Message from debugger: Terminated due to signal 6
Program ended with exit code: 0

I am able to get SDL2-2.0.12 working using the following procedure:

Open the SDL2-2.0.12.dmg.
Copy the folder SDL2.framework into /Library/Frameworks/ using the Finder.
In Xcode, click on the project, click on the executable under “Targets”, click on “Build Phases”, under the tab “Link Binary With Libraries”, click on the “+” button. Under “Add Other…”, click “Add Files”. Navigate to /Library/Frameworks/ and click on “SDL2.framework”. Click the “Open” button.
SDL2.framework is added to the list of application libraries.

Now click “Build” and “Run”.

Everything works.


Might you please try the procedure I mentioned for SDL2-2.0.12.dmg, but copy the frameworks from SDL2-2.0.14.dmg?

When I use the same procedure for SDL2-2.0.14.dmg, it now works for me.

I could have sworn I tried the exact same procedure for SDL2-2.0.14.dmg at some point and it didn’t work.

For me, it’s working now.

I wonder what changed.

Putting user frameworks in system directories is a bad idea.

If you’re building command line utilities that only you will use, just install SDL via Homebrew.

And if you absolutely must, copy it to /Users/yourname/Library/Frameworks instead.

When I read “ReadMe.txt” after opening the disk image, it says:

 To Install:
 Copy the SDL2.framework to /Library/Frameworks
 You may alternatively install it in <Your home directory>/Library/Frameworks 
 if your access privileges are not high enough. 

If it’s a bad, bad idea to copy the SDL2.framework folder to /Library/Frameworks, could someone update the Readme.txt? I would imagine most users, after reading Readme.txt, will try to install to /Library/Frameworks…

I wouldn’t class SDL2 as a “user framework”, and as has been pointed out the instructions explicitly state to put it in /Library/Frameworks. Some Linux distros come with SDL2 pre-installed.

I would guess the installation instructions are old, then. You can manually copy a framework to /Library/Frameworks, but messing with system directories feels like asking for trouble.

As for Linux, in that case you’re using a package manager. For Mac, if you want to go that route then use Homebrew, which will install everything to /usr/local at least.

@kaleida @sjr

I’m still having the same issue, unfortunately. Here is what Xcode tells me:

dyld: Library not loaded: @rpath/SDL2.framework/Versions/A/SDL2
Referenced from: /Users/username/Library/Developer/Xcode/DerivedData/SDL_Tutorial-deuhagqccravzlhhfmcqpzqmsewe/Build/Products/Debug/SDL_Tutorial
Reason: no suitable image found. Did find:
/Library/Frameworks/SDL2.framework/Versions/A/SDL2: code signature in (/Library/Frameworks/SDL2.framework/Versions/A/SDL2) not valid for use in process using Library Validation: mapped file has no Team ID and is not a platform binary (signed with custom identity or adhoc?)

Did you try the SDL2-2.0.12.dmg image?

I don’t know why, but using the 2.0.12 image worked for me.

Did you follow the exact instructions above in my previous post?

Also, you should make a brand new project from scratch, not reuse an existing Xcode project. Also, go into /Library/Frameworks/ and delete any SDL2 frameworks there before trying the 2.0.12 disk image. Also be sure to delete anything in /User/youraccount/Library/Frameworks (if there are any SDL2 frameworks there) and make sure there is not any SDL frameworks in the same directory as your Xcode project file.

It’s because it’s signed with a different signing key than the one your app is being signed with.

In your project settings, go to the Signing & Capabilities tab. Scroll down to the Hardened Runtime section, and check the box for Disable Library Validation.

Alternately, if you don’t want to disable part of the hardened runtime, just download the SDL source code and build it yourself and use your own signing certificate.

Also, if you’re building an app that you want to distribute to other people, you’re gonna have to bundle SDL2.framework in your app, in which case there’s no point to installing SDL to /Library/Frameworks or /Users/you/Library/Frameworks. Put SDL2.framework in the same directory as YourProject.xcodeproj (so it’ll be versioned with your source code and you won’t have to worry about version incompatibility), tell Xcode to link to that one, put $(PROJECT_DIR) in your Framework Search Path in the build settings, and Xcode will do the rest.

This also makes it easier to ship different apps with different versions of SDL, in case in the future a breaking change happens. You won’t have to go around and fix all your apps at the same time, like you would if you kept the latest SDL in /Library/Frameworks or /Users/you/Library/Frameworks and all your apps were compiled and linked against that.

Sorry for the late response- thank you so much for the help @sjr !

1 Like