Using SDL with Xcode 4
January 9th, 2012
Filed under: SDL, Xcode | 25 comments
Apple changed the format for project templates in Xcode 4. The format change means the Xcode templates that ship with the Mac version of SDL don’t work in Xcode 4. If you have both Xcode 3 and 4 installed on your Mac, you can create a project that uses SDL in Xcode 3 and open it in Xcode 4. But if you’re running Xcode 10.7 and don’t have Xcode 3 installed, you’re stuck with Xcode 4 and can’t use the SDL project templates. But you can use Xcode 4 to create SDL applications without too much hassle.
While I wrote this article for Xcode 4 and SDL 1.2, most of the material in the article still applies to Xcode 5 and SDL 2. Some of the screenshots will look slightly different in Xcode 5, and any reference to SDL.framework should refer to SDL2.framework in SDL 2.
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.
SDL 2 Note
SDL 2 has no SDLMain files to add. You can skip the Add SDLMain to the Project step if you’re using SDL 2.
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.
- Select the project file from the project navigator to open the project editor.
- Select the target from the left side of the project editor.
- Click the Build Phases button at the top of the editor.
- Click the Add Build Phase button at the bottom of the editor. If you’re using Xcode 5, choose Editor > Add Build Phase > Add Copy Files Build Phase and skip Step 5.
- Choose Add Copy Files from the menu.
- Drag the SDL framework from the project navigator to the table in the Copy Files build phase.
- 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.
If you find the SDL framework isn’t being copied into your application bundle, take a look at Adam’s comment, comment #5.
Tags: xcode 4
Awesome ! Thanks for this. I’ve been wanting this for a while. Resorted to hacking with Emacs and Makefiles … Great to be back in the XCode Debugger …
thanks a lot, following this – where to get proper SDLmain.m/h? (I found it there SDL12-lion-compatible.zip\SDL12-lion-compatible\src\main\macosx\)
and got errors in SDLMain.m
Apple Mach-O Linker (id) Error
Command /Developer/usr/bin/clang failed with exit code 1
ld: duplicate symbol _main in /Users/Apple/Library/Developer/Xcode/DerivedData/…
exy,
SDLMain.m and .h come with the Mac version of SDL. They are in the devel-lite folder.
SDL is very picky in how you define the main() function in your game. If you don’t define it properly, you get the link error you described. The start of your main() function should look like the following:
int main(int argc, char *argv[])Thank you very much!
Now, time to make a template so I don’t have to do this over and over again.
This works for me on my own machine, but the resulting executable fails on a machine without SDL installed on it.
A little searching showed that I needed to add one line to the project settings:
* Select your project in the left hand pane
* Select your target
* Select the “Build Settings” tab
* Find the “Runtime Search Paths” setting and add the following value: `@loader_path/../Frameworks`
Hope this helps!
Hello,
First, thank you for the tutorial. I have a question that seems to be a linker problem. I receive this error when building from Xcode 4 after following your tutorial:
Undefined symbols for architecture x86_64:
“_SDL_main”, referenced from:
-[SDLMain applicationDidFinishLaunching:] in SDLMain.o
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
I’ve found that it relates to this code in SDLmain.m source file in the function – (void) applicationDidFinishLaunching: (NSNotification *) note:
line 300: status = SDL_main (gArgc, gArgv);
If I comment that line out, the program builds just fine and the program exits with status afterwards anyways. I’ve looked at 3 or 4 other tutorials on getting SDL started with Xcode4 in the last 3 hours and I seem to be the only one having this issue. Can someone explain to me why I get this compile error? Or at least point me in some direction? Thanks for your time.
-Erik
Nevermind, I think I solved my problem. I am trying to start learning SDL and I did not realize that an SDL_main function was required, so I defined it in SDLMain.m
I’m getting an “issue” using sdl 1.2.15. “Category is implementing a method which will also be implemented by its primary class”… The test code i’m using will compile and run fine, it just bothers me.
@Jordan, to disable this warning, open up the SDLMain.m file and add the following two lines before the definition of the terminate function (around line 70)
#pragma clang diagnostic push
#pragma clang diagnostic ignored “-Wobjc-protocol-method-implementation”
after the @end, add the following line:
#pragma clang diagnostic pop
This is a pre-processor pragma that disables the type of error checking that reports that warning for the definition of only that function. A fresh compile should now complete without warnings.
Hopefully this thread isn’t too dead… Anyway, I’m having the same problem as exy, except doing what mark said didn’t fix anything 🙁
Puzzle,
The error message exy has says that main is declared more than once. The only thing I can add to the advice I gave earlier is to make sure you have only one main() function in your program.
If you click the Articles link on the sidebar, you can find my article on using SDL with OpenGL. That article has an Xcode 4 project you can download, which may help you discover the cause of your duplicate symbol link error.
How do you make an IOS template with SDL?
Gregory,
I have not used SDL with iOS, but creating an iOS application project and removing the unwanted files from the project should work.
If you are asking how to create a custom project template for making iOS apps with SDL, you can take a look at the following article on this blog:
Creating Custom Xcode 4 Project Templates
I followed all the instructions and I just get this:
Undefined symbols for architecture x86_64:
“_SDL_main”, referenced from:
-[SDLMain applicationDidFinishLaunching:] in SDLMain.o
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
any ideas?
im in xCode 4 on Mountain Lion…
Dylan,
I have no new ideas besides the ones I mentioned in previous comments. Make sure you define the main() function properly. Take a look at the Xcode 4 project for my SDL/OpenGL article.
Hello
I followed instructions above but i get an error
ld: framework not found SDL
clang: error: linker command failed with exit code 1 (use -v to see invocation)
I have SDL.frameword folder in /Library/frameworks/ but xcode doesn’t see it. To add this framework I need to drag the folder into the project tree.
I am using xcode 4.5.1 on osx 10.8.2
Furthermore I have project that was working well on osx 10.7, but now it doesn’t compile either. It produces the same error (also for SDL_image and ttf)
Slawek,
Make sure the SDL framework is in the Link Binary with Libraries build phase. You may also need to add a search path to the SDL framework using the Framework Search Paths build setting.
Mark,
Thank you for your answer but it didn’t work. I downloaded all frameworks once again and installed them. Now Xcode can find them. It seems that upgrade to mountain lion might have messed up a little bit with custom frameworks. I don’t know why I wasted so much time finding a solution.
after hours and hours, this guy’s tutorial worked for me. http://www.youtube.com/watch?v=F27BUDX_RSg
I made XCode4 Templates for SDL2 🙂 I have not prepared them yet for public release but it is on its way!
Ok I am hosting the SDL2 Xcode4 Templates @ https://github.com/bazzinotti/SDL2-Xcode-Template
I am able to compile when the SDL.framework is copied into the project folder. If I just reference it, the project doesn’t compile and can’t find SDL/SDL.h. I added /Library/Framework/SDL.framework to the Framework folder path, and even added /Library/Framework/SDL.framework to the Header folder path. Anyone have any clue why you can’t reference?
furtivefox,
I can see two possible problems. First, when you added search paths, you added /Library/Framework as the start of the paths. The actual path is /Library/Frameworks. Adding the missing s could solve the problem.
Second, you’re including SDL.h by calling SDL/SDL.h. In my SDL code, I include SDL.h in the following way:
#include "SDL.h"I am having the troubles as furtivefox. Any new suggestions ?
TJ,
The only other suggestion I can add is to add a header search path to the SDL framework’s Headers folder. Furtivefox was only adding a path to the framework in the header search path.
/Library/Frameworks/SDL.framework/Headers
Also make sure the SDL framework is in /Library/Frameworks, not /Users/YourUsername/Library/Frameworks