SFML and Xcode (Mac OS X)

Introduction

This is the first tutorial you should read if you're using SFML with Xcode -- and more generally if you are developing applications for Mac OS X. It will show you how to install SFML, setup your IDE and compile a basic SFML program. But also, and more importantly, how to make your applications ready "out of the box" for the end users.

Several links are given in this document. There are mostly here for the curious ones among the readers; you don't need to read them all to follow this tutorial.

System requirement

All you need to create an SFML-based application is:

Binaries: dylib vs framework

SFML is available in two formats on Mac OS X. You have the dylib libraries on one hand and the framework bundles on the other hand. Both of them are provided as universal binaries so they can be used on 32 bits or 64 bits Intel systems without any special consideration.

Dylib stands for dynamic library; this format is like .so libraries on Linux. You can find more details in this document. Frameworks are fundamentally the same as dylibs, except that they can encapsulate external resources. Here is the in-depth documentation.

There is only one slight difference between these two kinds of libraries that you should be aware of while developing SFML applications: if you build SFML yourself, you can get dylib in both release and debug formats. However, frameworks are only available in release format. In any case this won't be an issue when you release your application because you would rather use the release version of SFML. That's why the binaries for OS X available on the download page are only in release format.

Xcode templates

SFML is provided with two templates for Xcode 4 which allow you to create very quickly and easily new application projects. These templates can create custom projects: you can select which modules your application requires, if you want to use SFML as dylib or as frameworks, which compiler you want to use and you can choose between creating an application bundle containing all its resources (making the installation process of your applications as easy as a simple drag-and-drop) or a classic binary. See below for more details.

Be aware that these templates are not compatible with Xcode 3. If you are still using this version of the IDE and you are not considering updating your tool, then you can still, of course, create SFML-based applications, however, we will not discuss here how you can do that. Please refer to Apple's documentation about Xcode 3 and how to add a library to your project.

C++ 11

Apple ships a custom version of clang and libc++ with Xcode 4 that support part of the C++11 standard (i.e. new features are not yet all implemented). If you plan to use C++11's new functionalities you need to configure your project (see below) to use clang and libc++.

Moreover, you will need to compile SFML yourself with these tools. Follow the tutorial (especially the C++11 and Mac OS X section) and then, after running make install, jump to the Create your first SFML program part below.

Installing SFML

First of all you will need to download the SFML SDK which is available on the download page.

In order to start developing SFML applications, you have to install the following items:

Create your first SFML program

We provide two templates for Xcode. SFML CLT generates a project for a classic terminal app whereas SFML App creates a project for an application bundle. We will use the latter here but they both work relatively similarly.

First select File > New Project... then choose SFML in the left column and double-click on SFML App.

Xcode template selection

Now you can fill in the required fields like in this screenshot; then press next.

Xcode template form

Your new project is now set to create an application bundle ".app".

A few words about the templates settings: if you downloaded the binaries from the download page, you should select C++98 with GCC and libstdc++ and target 10.5. If you choose another value for the compiler and standard library, you will end up with linker errors. If you want/need clang's features (like C++11) you must recompile SFML yourself; see the C++11 section above.

Now that your project is ready, let's see what is inside:

Content of the new project

As you can see, there are already a few files in the project. There are three important kinds:

  1. Header & source files: the project comes with a basic example in main.cpp and a helper function: std::string ResourcePath(void); in ResourcePath.hpp and ResourcePath.mm. The usefulness of this function, as illustrated in the provided example, is to get in a convenient way access to the Resources folder of your application bundle.
    Please note that this function works only on Mac OS X. If you are planning to make your application work on another OS, you should make another implementation of this function for this OS.
  2. Resource files: the resources of the basic example are put in this folder and are automatically copied to your application bundle when you compile it.
    To add new resources to your project, simply drag'n'drop them to this folder and make sure that they are member of your application target; i.e. the box under Target Membership in the utility area (cmd+alt+1) should be checked.
  3. Product: here is your application. Simply press the Run button to test it.

The other files of the project are not very relevant for us here. However, please note that the SFML dependencies of your project are added to your application bundle, in a similar way than the resources are copied, so that it will run out of the box on another Mac without any prior installation of SFML or its dependencies.