How to set up a SDL 2 project for iOS in Xcode 5

SDL 2, a cross-platform library for multimedia applications, now offers projects and templates for many platforms, including a XCode project template for iOS which, in theory, should allow you to start to work on your app without wasting any time creating a project from scratch.

The sour reality

Unfortunately reality is not that bright and the template iOS project included in the latest sources release (2.0.3) doesn’t even build.

The two main issues are the missing SDL files (highlighted in red in the picture above) and the missing headers search path(s) which allow our program to find SDL.

The good news is that those problems are quite easy to solve and in this post I’m going to show you how.

Before starting

I’m assuming you’re trying to build the iOS template project included in the SDL 2 stable sources (version 2.0.3).

Things will be slightly different if you’re building a project from scratch or if you’re trying to build the template project after copying it outside the original directory. Obviously the key concepts will remain the same, but you’ll need to change paths and some details according to your needs and configuration.

Fixing the template project

The first step is deleting the whole SDL group from your project, then add the SDL project you can find in the Xcode-iOS/SDL/ directory included in the SDL sources.

This project includes all the files needed to build SDL 2, but to avoid errors during the linking stage and to automate the build you also need to add libSDL2.a to the libraries to link with your binary.

You can do that in the “Build Phases” section of the build settings you get when clicking on the main project.

Now that we’ve included SDL to our project we need to tell Xcode where to find the library’s headers.

Assuming your template project is in Xcode-iOS/Template/ and the SDL2 project is in Xcode-iOS/SDL/ you need to add ../../../include as search path in your project’s Build Settings, as shown in the picture above.

Now everything should build fine and you should be able to run the test app in the iOS simulator.

As you may have noticed from last picture, Xcode will show you some warnings while and after building the template project and SDL 2, but don’t worry, they won’t really affect your app during the development and Xcode will help you to fix most of them, something you probably will need to do before releasing on the App Store anyway.


I’m not publishing the fixed template project as it’s probably easier and more flexible to fix the “official” project according to your needs following the steps described here, but I also hope someone working on SDL will fix the template project for the next release making these instructions useless.

In the meanwhile I hope this will be helpful to someone.

Leave a Comment

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