How to set up a SDL 2 project for OS X in Xcode 4

SDL 2 doesn’t come with a proper project template for Xcode, so if you’re developing on a Mac for OS X or iOS you need to create one from scratch or you have to reuse an example project provided with the SDL code package.

The whole process is not rocket science, but as it takes few minutes you probably want to create an empty project to use as template for all your future ones, in this post I’m going to show you how to do that.

Before even starting

It’s probably worth to mention that this howto is based on XCode 4.6.3 and SDL 2.0.0 running on OS X 10.8.4, your configuration could be different and things could change a bit in the next few months, but for now this should do the trick.

Obviously you need to download SDL 2 and eventually any other sub-library (SDL2_image, SDL2_ttf, etc…) your project will need and install it/them on your system.

The official SDL documentation 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.

So for this tutorial I’m assuming the SDL framework has been installed in /Library/Frameworks even if you could install it in your project directory or in some other place according to your needs.

Creating the project

Open Xcode and create a new project (File > New > Project) and when you’re asked what kind of project you want to create select “Cocoa Application”:

After that enter the details for your project like Product Name and Company Identifier, these bits are up to you, just be sure to uncheck all the checkboxes in the dialog as you won’t need any of the features used by regular Cocoa projects.

Now you have a basic Cocoa project and it’s time to remove most of the files from it.

You can delete AppDelegate.h, AppDelegate.m, MainMenu.xib and SDL2_template-Prefix.pch, then remove all the default frameworks and finally rename main.m to main.cpp. Once you’ve done that you should get something like this:

I also created a group for the source files called “Code”, not very useful here considering we will only have one source file, but old habits die hard.

Once you sorted out your files structure it’s time to remove the Prefix Header SDL2_template-Prefix.pch from the Build Settings  so the compiler won’t complain because the file is missing.

Now it’s time to add the SDL2 framework to our project, you can do that from the “Linked Frameworks and Libraries” section of the project Summary:

Just click on “Add Other…” and select the SDL2 framework in your system.

Finally you will probably need to add “/Library/Frameworks” to the Build Settings of your project, so you won’t have complains from the compiler not finding the SDL2 framework:

After all of these you will probably need to close and re-open Xcode to get auto-completion of header files (this may be needed or not, XCode is just a bit random sometimes, but a quick restart is recommended as it won’t hurt).

A simple SDL program

Now the project is ready to go, all we need is some very simple code to test that everything is working fine.

The following code creates and opens a 640×480 window centered in the middle of the screen, then it exits after 5 seconds.

#include <iostream>

#include <SDL2/SDL.h>

int main(int argc, char * arg[])
    // init SDL
    if(SDL_Init(SDL_INIT_EVERYTHING) != 0)
        std::cout << "ERROR SDL_Init" << std::endl;

        return -1;

    // create a window
    SDL_Window * window = SDL_CreateWindow(
                                            "SDL 2 window",             // window title
                                            SDL_WINDOWPOS_CENTERED,     // x position, centered
                                            SDL_WINDOWPOS_CENTERED,     // y position, centered
                                            640,                        // width, in pixels
                                            480,                        // height, in pixels
                                            SDL_WINDOW_OPENGL           // flags

    // wait 5 secs

    // clean up

    return 0;

You can copy and paste it in your main.cpp file, then run the project to get the following result:

a nice black window, the starting point of every single game! 🙂

Running your app on other systems

I’m not going to explain you how to distribute your app on the Apple App Store or on any other online store, but it’s probably worth to mention that if you wanted to run your app on a system where the SDL 2 framework is not installed in a default directory (like /Library/Frameworks) you’d end up with a crash.

In order to avoid that you have two options:

  • Install the SDL 2 framework on the other system.
  • Include the framework in you app bundle.

Obviously the first option doesn’t require any explanation, so I’ll show you how to do the second.

First thing, you need to add a new build phase in the Build Phases section of your project, the build phase to add is an “Add Copy Files” one.

Once you created the new phase, select “Frameworks” as Destination and drag the SDL 2 framework from your project navigator to the empty rows of the Copy Files block (alternatively you can add the framework pressing the button +).

Unfortunately copying the SDL 2 framework into your app bundle is not enough, as the executable doesn’t know where to find it, so you need to set “Runpath Search Paths”  to “@executable_path/../Frameworks” in the Build Settings of your project.

Now you can send your app to someone which doesn’t have the SDL 2 framework installed and it will run without a crash (hopefully…)!


  1. Apateona

    Very clean explained.
    Thank you very much !

  2. Diogo Muller

    Thanks! That helped a lot!

  3. kouky

    Thank you for the tutorial,
    I can compile the test code unfortunately no black window appear, the app icon just bounces for 5 seconds and then app closes.
    Any Hints?

    1. r00t (Post author)

      I’d start checking the debug panel, if there’s any problem with SDL you should be able to get a better description using SDL_GetError()

    2. Nico Cvitak

      Hey I’ve got a similar problem with the window not opening, and the app icon just bouncing. I was just wondering if you figured out the problem yet.

  4. tor

    Wow, I’m completely new to OS X and XCode, but with this tutorial I got the example program to work!
    Thanks Dave!

  5. Yevgeni Zolotko

    Thank you, extremely helpful!

  6. M787

    I’ve a problem… I deleted the file named SDL2_template-Prefix.pch, and when I try to start the template, Xcode give me an error about this… How can I solve?

    1. M787

      Ok, sorry, I didn’t saw that part of the tutorial 🙁

  7. Dez

    I’m followed all the steps and i got it to compile without error, but it won’t stop crashing. I’m using Xcode 5.. do you think that could be the problem?

    1. Dez

      I followed not I’m followed haha

    2. Will

      I have the same problem. Running it actually crashes Xcode. Might be a problem with SDL? Here is the Xcode crash report:

      Process: Xcode [53654]
      Path: /Applications/
      Version: 5.1.1 (5085)
      Build Info: IDEFrameworks-5085000000000000~10
      App Item ID: 497799835
      App External ID: 520942841
      Code Type: X86-64 (Native)
      Parent Process: launchd [180]
      Responsible: Xcode [53654]
      User ID: 501

      PlugIn Path: /Library/Frameworks/SDL2.framework/Versions/A/SDL2
      PlugIn Identifier: org.libsdl.SDL2
      PlugIn Version: 2.0.3 (2.0.3)

      Date/Time: 2014-06-18 10:03:51.951 -0400
      OS Version: Mac OS X 10.9.3 (13D65)
      Report Version: 11
      Anonymous UUID: 83AF7DBE-870D-B7DA-8E18-14C283B528E3

      Sleep/Wake UUID: 85193FBC-2B9F-4454-9FA4-8BF6A2474208

      Crashed Thread: 25

      Exception Type: EXC_BAD_ACCESS (Code Signature Invalid)
      Exception Codes: 0x0000000000000032, 0x00000001135f9000

      kernel messages:
      -2 sec CODE SIGNING: cs_invalid_page(0x1135f9000): p=53654[Xcode] final status 0x1000200, denying page sending SIGKILL
      -2 sec CODE SIGNING: process 53654[Xcode]: rejecting invalid page at address 0x1135f9000 from offset 0x1000 in file “/Library/Frameworks/SDL2.framework/Versions/A/SDL2” (cs_mtime:1394937310.0 == mtime:1394937310.0) (signed:1 validated:1 tainted:1 wpmapped:0 slid:0)

      1. Davide Coppola (Post author)

        it seems you’re having some problem with the code signing.
        Try to not code sign your app and rebuild.

    3. Davide Coppola (Post author)

      Just tried in Xcode 5 and it worked just fine.

  8. Fabio

    Thanks for the explanation Davide.

    I have it working on Xcode 6 without any issues. I was having the same issue as Will mentioned above. The only fix for me was to build the Framework from scratch, just simply

    1. hg clone
    2. Compile the “Framework” target in Xcode/SDL/SDL.xcodeproj
    3. Copy framework to /Library/Frameworks



Leave a Comment

Your email address will not be published. Required fields are marked *