SDL2 Mac OS Xcode 11 #includes

I’m trying to #include several SDL2 frameworks for the first time. I can’t seem to get it to work.

In the past, I have always been using a single framework (e.g., the SDL2.framework), which I would copy to the same directory as my Xcode project file (as suggested by sjr), and then add the SDL2.framework manually to my Xcode project. This has consistently worked for me in the past, however I have not had to deal with any header issues.

To solve my header situation, since I only had a single set of header files that needed to be added, I would cd to the directory where my source files are, and:

ln -s …/SDL2.framework/Headers/

which will place a simlink to the proper headers at the same directory as my c/c++ source files, and then I just:

#include “Headers/SDL.h”

That has been a very reliable way to solve my header problems in the past.

As mentioned, this technique doesn’t work all that well now that I am trying to use SDL_image and SDL_ttf too. Is there a way to set things up so that:

#include <SDL2/SDL.h>
#include <SDL2/SDL_image.h>
#include <STD2/SDL_ttf.h>


I looked at SDL2 on Xcode 12 - #6 by sjr

I seem to be having the same (or a very similar problem).

So far, I have edited:

  • Framework Search Paths
  • Header Search Paths
  • System Header Search Paths
  • User Header Search Paths
    I’ve tried including all 3 header locations in these 4 search paths, and I’ve also tried adding the text “$(PROJECT_DIR)” to the bottom of the list of Framework Search Paths. I’ve also tried changing all of these to “recursive” and “non-recursive” mode.

Nothing seems to work. Currently, the error I am seeing is:

#include <SDL2/SDL.h> <-----Error! SDL2/SDL.h not found

So it can’t even find the first SDL2 header (that I already fixed a long time ago by making a simlink in the same directory as my source code as mentioned above).

Is there a simple tutorial somewhere that shows how to solve the issue of #including multiple SDL2-related headers for Xcode?

Thank you!

Hi, kaleida-

I’m tinkering with updating the Xcode project to properly build an iOS .xcframework for all combinations of devices, simulators, and processors. I ran in to a similar problem with headers.

You mentioned trying various combinations of the search paths, as well as trying recursive vs. non-recursive. Can you also look at “Sub-Directories to Exclude in Recursive Searches”? The default includes *.framework, so even if you turn on recursion, it won’t recurse. If it’s there, try removing *.framework from that build setting.

If that works, then a bug needs to be filed with Apple (I’ll do it) because just including a framework ought to be enough for Xcode to see the headers, you shouldn’t need to do the song-and-dance.

After changing “Sub-Directories to Exclude in Recursive Searches”, where I removed the *.framework entry, the compile goes further, and it looks like it is now finding the headers.

Now it’s stuck because some of SDL2.framework, SDL2_image.framework, or SDL2_ttf.framework are not signed.

Ok, so I typed the following (from my previous posting regarding code signing for SDL2, Install problem - Catalina):

codesign -f -s - SDL2.framework
codesign -f -s - SDL2_image.framework
codesign -f -s - SDL2_ttf.framework

That caused the complaints about SDL2.framework and SDL2_image.framework not being signed to disappear.

Now I have one error left:

/Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDL2_ttf.framework/Versions/A: code object is not signed at all

In subcomponent: /Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDL2_ttf.framework/Versions/A/Frameworks/FreeType.framework

Command CodeSign failed with a nonzero exit code

Seems like SDL2_ttf.framework might need more than I accomplished by trying a basic codesign.

I don’t know what to do now.

Glad to hear that the headers work now. As for the signing, you shouldn’t have to do that by hand. Check this: In your target ==> General ==> Frameworks, Libraries, and Embedded Content, see if your framework has Embed set to “Embed and Sign”. If not, try that.

When I look at my Xcode target, click on the “General” tab, and under the section heading “Frameworks and Libraries”, I see my 3 SDL2 frameworks that I manually added to my project:


All 3 are set to “Embed & Sign”. I also tried removing them and re-adding them to my project since I have made some changes to the originals (executing “codesign -f -s - SDL2*.framework” for each of them).

It is only complaining that SDL2_ttf.framework is “not signed at all”.

I set the mode for SDL2_ttf.framework to “Embed Without Signing” and now the whole project builds!

However it doesn’t run.

When executing, Xcode says:

dyld: Library not loaded: @rpath/SDL2_ttf.framework/Versions/A/SDL2_ttf

Referenced from: /Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDLTextDemo

Reason: image not found

Actually, this is looking virtually identical to what I was seeing over at Install problem - Catalina - #2 by sjr

The full code signing error for SDL2_ttf.framework looks like this:

CodeSign /Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDL2_ttf.framework/Versions/A (in target ‘SDLTextDemo’ from project ‘SDLTextDemo’)
cd /Users/(me)/XCodeApps/SDLTextFinal/SDLTextDemo
export CODESIGN_ALLOCATE=/Applications/

Signing Identity: “-”

/usr/bin/codesign --force --sign - --timestamp=none --preserve-metadata=identifier,entitlements,flags /Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDL2_ttf.framework/Versions/A

/Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDL2_ttf.framework/Versions/A: code object is not signed at all
In subcomponent: /Users/(me)/Library/Developer/Xcode/DerivedData/SDLTextDemo-dtteyamlzkcexqfubjbkpquqwllu/Build/Products/Debug/SDL2_ttf.framework/Versions/A/Frameworks/FreeType.framework
Command CodeSign failed with a nonzero exit code

Ok, so it looks like the core of the problem is signing SDL2_tff.framework. I see that yours has a Frameworks directory in it, with a FreeType.framework in it. When I downloaded SDL2_tff.framework version 2.20.1, there is no FreeType.framework in it.

So I take it you built your own SDL2_tff? (I haven’t done that.) The code signing seems to be stumbling over FreeType, which is embedded within SDL2_tff. Codesign doesn’t sign recursively by default, so since you’re signing on the command line, use the --deep option to the codesign command for SDL2_tff.

OTOH, if you’re codesigning from Xcode, it doesn’t use the --deep option, so you might try the suggestions from here:

Ok, got the whole thing working.

Here’s my recipe (including shocking lameness at the end). This is obviously specific to MacOS, I’m on macOS Big Sur (11.6.2), Xcode 11.4.1.

  1. Use the following versions of the SDL libraries:

    • SDL2-2.0.14.dmg
    • SDL2_ttf-2.20.1.dmg
    • SDL2_image-2.0.5.dmg
      SDL_ttf is here: Index of /projects/SDL_ttf/release
      Copy these frameworks into the same directory as your Xcode project.
  2. Click on your project in the “Project Navigator” panel. Make sure, in the next panel to the right, that, under the “PROJECT” heading, your Xcode project is selected (not under the “TARGETS” heading). Click on “Build Settings”, which is to the right of “Info”. Navigate to the “Search Paths” section of the build settings.

  3. Edit “Sub-Directories to Exclude in Recursive Searches” and remove “*.framework”.
    To “System Header Search Paths”, add: /Users/me/XCodeApps/SDLTest/SDLTest/SDL2.framework/Headers/
    Change the setting for this path to “recursive”
    To “System Header Search Paths”, add:
    Change the setting for this path to “recursive”
    To “System Header Search Paths”, add:
    Change the setting for this path to “recursive”

  4. Under the “TARGETS” heading, click on your executable. Now click on “General”, and add the following frameworks to your project by locating the “Frameworks and Libraries” panel, and clicking on the “+” button. Click on the “Add Other” button at the bottom left of the pop-up window, and choose “Add Files”. Add each of the following files:

  5. Now you can use the following to include the SDL headers for your project:
    #include <SDL.h>
    #include <SDL_ttf.h>
    #include <SDL_image.h>

  6. Now hit “Build”. Xcode 11.4.1 says build error, can’t figure anything out.
    Go to the “Product” menu in Xcode, and hit “Clean Build Folder”.
    Now hit “Build”. Everything builds and runs successfully.

So this gets it all working for me. In fact, probably some of my earlier questions about trying to get this working was due to Xcode lameness. If I had simply cleaned the build folder, I probably would have had everything working two days ago… Apple at it’s best.

Feel free to comment or add questions. Obviously I’m using specific versions of the SDL2 libraries, that’s just so that all the different components can talk to each other properly. I have no idea which versions work with what and I have never been able to find a list of those…

Pointing the system header search path to look inside the frameworks feels… unclean.

Ok, instead of the original approach at step 3:

  1. Edit “Sub-Directories to Exclude in Recursive Searches” and remove “*.framework”.
    To “System Header Search Paths”, add: /Users/me/XCodeApps/SDLTest/SDLTest/SDL2.framework/Headers/
    Change the setting for this path to “recursive”
    To “System Header Search Paths”, add:
    Change the setting for this path to “recursive”
    To “System Header Search Paths”, add:
    Change the setting for this path to “recursive”

I now have done the following:

  1. Edit “Sub-Directories to Exclude in Recursive Searches” and remove “*.framework”.
    To “System Header Search Paths”, add: $(PROJECT_DIR)
    Change the setting for this path to “recursive”

Keep in mind that, IIRC, setting the “System Header Search Paths” field is nothing more than informing Xcode about where to look (in addition to the usual system header paths) for any include that uses the angle brackets as delimiters (< and >). I could just edit “User Header Search Paths” and set it to $(PROJECT_DIR) and then switch the headers to use the format:

#include “SDL.h”
#include “SDL_ttf.h”
#include “SDL_image.h”

Confirmed, I switched my source code as described and using quotes as delimiters with the update to “User Header Search Paths” works just as well.

Which way, sjr? Btw, thanks for mentioning the $(PROJECT_DIR) mechanism, it sure clarifies this immensely!

Might I pop another question here? I am playing with the SDL_ttf framework for text rendering. One issue I have run into is that I need to copy my font over to my executable directory, which of course lives over at /Users/(me)/Library/Developer/Xcode/DerivedData/(my_project)/Build/Products/Debug/.

Is there a way to get Xcode to copy my font?

I tried the following:

In “Project Navigator”, click on the Xcode project. In the next panel to the right, select under the header “TARGETS” the executable. Click on “Build Phases”, click the “+” button to add a new build phase. Choose “New Run Script Phase”. Add the following script to be run:

cp -r $SRCROOT/myfont.ttf $INSTALL_PATH

I scraped this approach from the web. At the moment, it doesn’t work.

Are you building a regular macOS app? In other words, an app bundle? If so, just add it to your project and make sure to select your app’s target (right click on the project, choose Add Files, select your font file) and Xcode should copy it to the app bundle for you.

If not (if you chose Command Line App when creating the project) well, there are many ways to skin this particular cat. You could also edit the Run scheme to have an environment variable that holds the path to your app’s data, and have the app check it at runtime and look for it at that location if it exists.

As to the headers, I’m not at my computer but will look at it when I get home later today

Ok, so back at my computer. I never add anything to System Header Search Paths, nor do I add anything to User Header Search Paths. There’s just the plain old Header Search Paths.

Honestly, there isn’t really a “clean” solution here. If you want to use the same #include statements on all platforms, it seems the only way to go is pointing the header search path inside the various SDL frameworks. Otherwise, you can do something like

#ifdef __APPLE__
#include <SDL2/SDL.h>
#include <SDL_ttf/SDL_ttf.h>
#include <SDL2/SDL.h>
#include <SDL2/SDL_ttf.h>
#endif /* __APPLE__ */

or something along those lines.

Personally I never need to deal with this because I don’t use SDL’s adjacent libraries (no SDL_image, no SDL_ttf) but instead use stb_image and stb_truetype.