SDL Tips for Mac OS X

December 29th, 2009

Filed under: Game Development, SDL | 12 comments

SDL’s most compelling feature is its cross-platform compatibility. You can use the same source code to write a game for Linux, Mac OS X, Windows, and any other system SDL supports. When people write a game with SDL on Linux or Windows and try to build a Mac version of your game, they learn that Mac OS X has some subtle differences from Linux and Windows. The three tips in this post should help people create Mac versions of their SDL games.

Use the Xcode Project Templates

If you haven’t done so already, go to the SDL website and download it. At the SDL download site, you will see both runtime and development libraries for Mac OS X. Download both libraries. The runtime libraries contain the SDL framework. The development libraries contain documentation and Xcode project templates.

The Xcode project templates do two nice things for you when you build the project. First, the templates create a proper Mac application bundle for you. Second, the templates copy the SDL framework to the application bundle. Including the SDL framework with your game lets people play your game without having to install SDL.

Adding Files to the Game

Games contain many external files, such as graphics, sound, and data files. Mac games store these files in the Resources folder inside the game’s application bundle. If you add graphics, sound, and data files to your project’s Resources folder, they will be copied to the application bundle’s Resources folder when you build your project.

Go to the Groups and Files list on the left side of Xcode’s project window. The top entry should be the name of your project. Click the disclosure triangle next to the project name to see a series of folders. Right-click the Resources folder and choose Add > Existing Files. Select the files you want to add and click the Add button.

A second sheet will open. If you are adding individual files, click the Add button. If you’re adding a folder of files, click the Create Folder References for any added folders radio button before clicking the Add button. Creating a folder reference copies the folder to the Resources folder inside the application bundle when Xcode builds your project.

Changing the Working Directory

The Mac OS X version of SDL sets the working directory to the directory containing the application bundle. This default behavior makes loading images and sounds more difficult because the images and sounds usually reside in the application bundle’s Resources folder. You can make file loading simpler by changing the working directory to the Resources folder.

Open the file SDLMain.m and modify the setupWorkingDirectory: method. The following code changes the working directory to the application bundle’s Resources folder:

NSString *resourcePath = [[NSBundle mainBundle] resourcePath];
[[NSFileManager defaultManager] changeCurrentDirectoryPath:resourcePath];

By changing the working directory to the application’s Resources folder, you should be able to use the same code to load files on Linux, Mac OS X, and Windows.


12 thoughts on “SDL Tips for Mac OS X

  1. Phil Howlett says:

    Thanks for the tips – they have helped me alot in learning on how to port to the Mac OSX. I have managed to get my files copied into the ‘resources’ part of the app bundle, but it throws them all into a singe directory instead of the directory structure for my data. Any hints on how to do this?

  2. Mark Szymczyk says:


    As a test I tried adding two folders, one named Images and one named Sounds, to an SDL project. After building the project I checked the application package. Both folders were in the Resources directory.

    The first thing I did was move the Images and Sounds folders inside the Xcode project’s folder. Next, I added the folders to the project. After clicking the Add button, a sheet opened. I clicked the Create Folder References for any added folders radio button and clicked the Add button. In the Groups and Files list on the left side of Xcode’s project window were two blue folders: Images and Sounds. That’s how I got the folders to be added to the Resources folder inside the application bundle.

    Examine your project’s Copy Bundles Resources build phase to see how the files are being copied to the Resources folder. In the Groups and Files list, there should be a Targets entry with a disclosure triangle. Click it and you will see the name of your target with another disclosure triangle. Click that disclosure triangle. Now you will see a collection of build phases. There should be one named Copy Bundle Resources. Click the disclosure triangle next to Copy Bundle Resources. Make sure there is a blue folder for each folder you’ve added to the project.

    I hope this helps.

  3. Phil Howlett says:

    Hi Mark,
    Found my problem. I didn’t click the “Create Folder References” option so my data folders were displaying as yellow folders (groups) instead of real folders (blue).
    Thanks so much for the speedy response, your post lead me in the right direction.

  4. Click170 says:

    Good god, batman! I’ve spent the last few days trying to figure out why the hell building my project in Xcode gave a different result than building it on my linux box from the command line.

    A black window would come up for 2 seconds, then disappear.
    On linux, it works fine, it shows the images and quits instead if just displaying black.

    I had an idea it had to do with the path, but trying to figure out all the little nuances of using Xcode as well as trying to figure this out was a little overwhelming.
    But your post laid out my problem and told me exactly how to fix it. Again, thank you!

    Xcode is really overwhelming for new users. Almost too much so, I’d say. When the command line looks like a more better alternative, something is wrong.
    Should you really have to pick up a textbook to figure out how to get it to just work? I thought that was the mac mantra, “it just works”. It certainly doesn’t “just work” in this case lol

  5. Click170 says:

    “more better” was the result of a bad edit, not bad grammar.

  6. Shawn Dowler says:

    @Click170 The Mac mantra of “It just Works” does not apply to developers. Apple expects developers to put in more effort on the front end so users, in theory, have to put in less effort to use the applications. I think you just experienced what this means for developers.

  7. Wolfos says:

    Thanks, this was just what I was looking for.

  8. Mark Vaughn says:

    Sorry about posting in the wrong place (is this good?). I have a follow up question: does anyone know if Apple will accept Mac apps that don’t allow you to use the Hide Window shortcut (command + h)? If they don’t, does anyone know how to code this with c++?


    Mark Vaughn

  9. Mark Szymczyk says:


    This is a good place to ask. I don’t know what Apple’s Mac App Store policy for apps that don’t support the Commmand-H shortcut. Apple does have a forum for paid developers where developers can ask questions about the Mac App Store. The forum is at the following URL:

    Carbon would allow you to hide windows and applications using C++, but you can’t write 64-bit Carbon apps, which means you have to use Objective-C if your game is going to be a 64-bit application. The following Stack Overflow question may be of interest to you:

    Is there a way to programmatically hide an carbon application on osx?

  10. Mark Vaughn says:

    Thanks for the tips Mark. I found that is a good place to go too. My one final question would be what frameworks am I supposed to include? I have SDL_image, SDL_mixer, SDL_ttf, SDL, and the Cocoa framework all linked together, but I get a Mach-O Linker error for some reason (see error message below). Is there another framework that I am missing?
    What I am doing is calling a function in SDLmain.m that hides my application from my main.cpp.

    // Code in SDLMain.m
    void HideMySDLApp(void)
    [NSApp hide:nil];

    // Code in main.cpp
    if (keypressed[LCOMMAND] && keypressed[Hh])
    extern void HideMySDLApp(void);


    Undefined symbols for architecture x86_64:
    “HideMySDLApp()”, referenced from:
    unknown() in main.o
    ld: symbol(s) not found for architecture x86_64
    clang: error: linker command failed with exit code 1 (use -v to see invocation)

    “unknown() is the name of my function.”

  11. Mark Vaughn says:

    No need to reply I figured it out.

    Thanks Anyway,

    Mark Vaughn

Leave a Reply

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