Create a Cocoa Application Project

When you create a project in Xcode, select the Cocoa Application project, as you can see in the following screenshot:

The Mac OS X version of SDL is written with Cocoa so a Cocoa application project is the closest template to the old SDL project templates. Click the Next button to move to the next step where you name the project.

Deselect the Create Document-Based Application, Use Core Data, and Use Automatic Reference Counting checkboxes. SDL games don’t use Core Data or Apple’s NSDocument class. Automatic Reference Counting is for Objective-C code, which most of you won’t use if you’re using SDL. If you want to unit test your game with OCUnit, select the Include Unit Tests checkbox. My Using Xcode to Unit Test SDL Games Written in C++ post has detailed information on using OCUnit to unit test C++ code.

Click the Next button to move on to the final step of creating a project. Pick a location to save the project and click the Create button. If you want to place your project in a local git repository, select the checkbox to create the repository.

Remove Unwanted Files from the Project

Apple’s Cocoa application project template contains files that are not needed for SDL games. You can remove the xib file and source code files from the project: any files ending in .xib, .m, and .h. In Xcode 4.2 you would delete the following files: main.m, MainMenu.xib, AppDelegate.h, and AppDelegate.m. Select a file and choose Edit > Delete to delete the file from the project. An alert opens. If you click the Delete button, Xcode deletes the file instead of moving it to the Trash. Clicking the Remove Reference button is the safer option. My Xcode 4: Removing Files from a Project post has additional information on removing files from a project.

Add the SDL Framework to the Project

Now it’s time to add the SDL framework to the project. Select the project file from the project navigator to open the project editor. Select your target from the left side of the project editor. Click the Summary button at the top of the editor to see a list of linked frameworks. Click the + button to add a framework. More information on adding frameworks is in my Xcode 4: Adding a Framework to Your Project post. Click the + button to add any additional frameworks, such as OpenGL, SDL_image, and SDL_mixer.

Add SDLMain to the Project

The Mac version of SDL uses two files, SDLMain.m and SDLMain.h, that contain glue code for running SDL code on Mac OS X. The SDL project templates include these files, but in Xcode 4 you must add them to your project. Choose File > Add Files to ProjectName to add the files. After adding the SDLMain files to the project, you can start coding.

Add Search Paths

When I tried to build a SDL project with Xcode 4, I got a build error saying that the file SDL.h was not found. The solution was to add the following search path to the Header Search Paths build setting:

/Library/Frameworks/SDL.framework/Headers

You may also need to add a search path to the Framework Search Paths build setting, but I didn’t need to add a path. You may also need to specify additional search paths if you use additional frameworks, such as SDL_image and SDL_mixer. My Xcode 4: Accessing Build Settings post has detailed information on accessing build settings in Xcode 4.

Copy the SDL Framework to Your Application Bundle

The SDL Xcode project templates copy the SDL framework to your application bundle. Copying the framework to the application bundle allows someone to play your SDL game without having SDL installed. If you want the SDL framework added to your application bundle, add a Copy Files build phase to your target and add the SDL framework to the build phase.

1. Select the project file from the project navigator to open the project editor.
2. Select the target from the left side of the project editor.
3. Click the Build Phases button at the top of the editor.
4. Click the Add Build Phase button at the bottom of the editor.
5. Choose Add Copy Files from the menu.
6. Drag the SDL framework from the project navigator to the table in the Copy Files build phase.
7. Choose Frameworks from the Destination menu.

If you have additional frameworks to copy to the application bundle, repeat Step 6 for those frameworks. Don’t copy Apple’s frameworks to the application bundle; every Mac has Apple’s frameworks installed. Only copy third-party frameworks, such as SDL_image and SDL_mixer.

typedef redefinition with different types ('unsigned int' vs 'void *')

The SDL header file SDL_opengl.h and the OpenGL header file glext.h both define a data type GLhandleARB. SDL_opengl.h defines it as an unsigned integer. The Mac OS X 10.7 version of glext.h defines it as a void pointer. Defining GLhandleARB as different data types in different header files causes problems.

The SDL team fixed the problem in their Mercurial repository. The fix is not too difficult to apply. In your SDL_opengl.h file, change the following line of code:

typedef unsigned int GLhandleARB;

To the following:

#if defined(__APPLE__)    

	typedef void *GLhandleARB;

#else    

	typedef unsigned int GLhandleARB;

#endif

The fix defines GLhandleARB as a void pointer on Mac OS X and an unsigned integer on other operating systems.

The original project is still there. I just added another version to make things easier for people using Xcode 4.1.

The culprit was the project’s InfoPlist.strings file. I noticed the keys CFBundleName, CFBundleShortVersionString, and CFBundleGetInfoString had the old project name. Changing these keys to the new project name, cleaning the project, and rebuilding the project fixed the problem. The menu bar now shows the new project name.

Use Xcode’s built-in support for Objective-C unit testing. Add a Cocoa unit testing bundle target to your project. Add an Objective-C test case class to your project, making sure to add the test case class to the unit testing target, not the target for your SDL game. Give the test case file the extension .mm instead of .m. Giving the file the extension .mm tells Xcode to treat the test case file as an Objective-C++ file, which allows you to unit test your C++ code with OCUnit, the Objective-C unit testing framework that comes with Xcode.

Make sure your game’s C++ source files are members of the unit testing target you created. If you don’t add your game’s C++ files to the unit testing target, you will get linker errors when your unit tests access your game’s classes. Read my googleTest Xcode Tip post for instructions on adding your C++ files to the unit testing target.

Apple’s Xcode Unit Testing Guide, which is part of Apple’s Mac developer documentation, contains additional information on setting up Xcode for unit testing. Also, thanks to Chris Hanson for his answer to a question 5 years ago on one of Apple’s mailing lists. Without his answer I would have never known you could unit test C++ code with OCUnit.

Cause 1: PNG Files Not Found

The most common cause of trouble of PNG file loading is the operating system being unable to find the file. Suppose you have the following SDL_image function call in your code to load an image:

SDL_Surface* image;
image = IMG_Load_RW("background.png", 1);

That code works only if the file background.png is in the current working directory. If the file isn’t in the current working directory, SDL_image won’t load it, and you have problems.

On Linux and Windows, the current working directory is the directory where the executable file is. Make sure your image files are in the same directory as the executable file.

On Mac OS X, SDL sets the working directory to the directory containing the application bundle. But your image files are in the Resources folder inside the application bundle. This means the code example to load background.png will not work on Mac OS X. The best solution is to change the working directory. My SDL Tips for Mac OS X post has instructions on changing the working directory.

Cause 2: DLLs Not Found

The second common cause of PNG loading problems affects only Windows programmers. For SDL code to run on Windows, Windows must be able to find the SDL DLLs. To find the DLLs, they must reside either in the same directory as the executable file or in the windows\system32 directory.

To use SDL_image on Windows, you must add the SDL_image DLL to the same location as the SDL DLL. Most people remember to add the SDL_image DLL, but they discover PNG files will not load.

The reason the PNG files will not load is that loading PNG files with SDL_image on Windows requires the zlib and libpng DLLs as well as the SDL_image DLL. It’s an easy mistake to make, and the error message SDL_image returns isn’t very clear. The solution is to move the zlib and libpng DLLs to the same location as the SDL and SDL_image DLLs.

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.

The reason was that Visual C++’s debugger uses a different working directory. Windows normally sets the working directory to the same directory as the executable file, which is where I had my image file. But Visual C++’s debugger sets the working directory to the directory containing the project file. Where is the project file? When you create a Visual C++ project, Visual C++ creates a folder that has the same name as the project name. Inside this folder is a second folder that has the same name as the project name. The project file resides in the second folder. The second folder is where the image file needed to be to debug my program. Moving my image file to the second folder fixed the crashing problem inside the Visual C++ debugger.

If you’re using Visual C++ to write a game and you want to run the game inside the debugger, make sure your game’s files are in the same directory as the project file.

You change the working directory by modifying the method -setupWorkingDirectory: in the file SDLMain.m. You’ll want to change the code in SDLMain.m in SDL’s Xcode templates so your changes take effect for any new SDL projects you create. Just to be safe, you should comment out the original code or save a copy of it so you can go back to the original if things go wrong. Enter the following code in the -setupWorkingDirectory: method:

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

Thanks to Keith Bauer, aka OneSadCookie, for the source code to change the working directory.