Setting up SDL2 in macOS (Xcode or CMake)

In this lesson, we’ll get SDL installed, along with two extensions which we’ll need later in this chapter.

• SDL is a cross-platform library that allows us to create windows, access input devices, and create graphics.
• SDL_image is an extension that allows us to work with images in all the common formats (jpeg, png, etc)
• SDL_ttf is an extension that we can use to render text at run-time

This setup guide downloads the libraries that have been precompiled for use on a Mac, and then demonstrates how to add them to projects that use either Xcode or CMake

Downloading the Libraries

The libraries can be downloaded from the official GitHub release pages, here:

• SDL: https://github.com/libsdl-org/SDL/releases
• SDL_Image: https://github.com/libsdl-org/SDL_image/releases
• SDL_TTF: https://github.com/libsdl-org/SDL_ttf/releases

Important Note: these release pages may include preview versions of SDL3. This course is using SDL2, so ensure the releases you download starts with 2 (for example, 2.30.2)

Once we’ve found the latest version 2 release, Mac users should download the .dmg package of each library:

Installing the Libraries

Once we have our three .dmg files, each one will contain a folder we need:

• SDL2.framework
• SDL2_image.framework
• SDL2_ttf.framework

We need to copy all of these folders to the /Library/Frameworks location on our hard drive:

From here, we need to add SDL to our project. How we do that varies depending on our choice of IDE. Below, I’ve included guides for Xcode or, alternatively, any editor that supports CMake.

Option 1: Project Setup in Xcode

Let’s walk through how we’d add these libraries to an Xcode project. Within the general settings of our project, under the "Frameworks and Libraries" section, we need to click the + icon to add each new framework.

Within that window, under Add Other… click Add Files

Navigate to our frameworks directory under /Library/Frameworks/SDL.framework, and open the SDL2 alias.

This should add it to our Frameworks and Libraries section. Repeat these steps for SDL2_image and SDL2_ttf

Our settings should look like this:

Next, within the Build Settings tab, we need to update our search paths to ensure Xcode and our compiled program can find all of our dependencies. These paths are split across four different configuration options:

• Framework Search Paths
• Runpath Search Paths
• Header Search Paths
• Library Search Paths

The search bar on the top right may help us find each one.

Note that some of these paths may have been prepopulated when we added the libraries, so we may not need to add all of these paths. Either way, we want our final configuration to include the following values:

Framework Search Paths

• /Library/Frameworks

Runpath Search Paths

• /Library/Frameworks

Header Search Paths

• /Library/Frameworks/SDL2.framework/Headers
• /Library/Frameworks/SDL2_image.framework/Headers
• /Library/Frameworks/SDL2_ttf.framework/Headers

Library Search Paths

• /Library/Frameworks/SDL2.framework/Versions/A
• /Library/Frameworks/SDL2_ttf.framework/Versions/A
• /Library/Frameworks/SDL2_image.framework/Versions/A

With that, everything should be set up and we’re ready to get building!

We’ve included some test code at the bottom of this lesson which will let us verify everything was installed correctly.

Option 2: Project Setup using CMake

CMake is a cross-platform configuration management standard where we define what we want in plain text files. The CMake application can then use these text files to generate project files for a wide variety of IDEs, such as the .xcodeproj files used by Xcode, or the .vcxproj files used by Visual Studio.

Some IDEs directly use CMake files as their primary way of managing our project’s configuration. An example that works on macOS is CLion.

If our IDE is compatible with CMake for configuration management, our setup is much simpler. CMake configurations use a CMakeLists.txt file. A minimalist example might look something like the following example:

1# CMake uses # to denote comments, similar to how
2# C++ uses //
3
4# What is the minimum cmake version that is
5# required to understand this file?
6cmake_minimum_required(VERSION 3.16)
7
8# What language are we using?
9set(CMAKE_CXX_STANDARD 20) # C++20
10
11# What is the name and version of our project
12project(Sandbox VERSION 1.0.0)
13
14# Our project has an executable that is generated
15# from a single source file called main.cpp
16add_executable(Sandbox main.cpp)

This CMakeLists.txt file indicates we’re making a C++23 project called "Sandbox", and it currently only has one source file - main.cpp

The most important line here is the call to project(). In my case, I called the project "Sandbox", but yours can be different.

Somewhere in our CMakeLists.txt, after the call to project(), we need to add the SDL libraries and include directories to the project we defined.

The completed file will look something like this:

1cmake_minimum_required(VERSION 3.16)
2
3set(CMAKE_CXX_STANDARD 23)
4
5project(Sandbox VERSION 1.0.0)
6
7add_executable(Sandbox main.cpp)
8
9# Variables storing SDL framework locations
10set(SDL2
11  /Library/Frameworks/SDL2.framework)
12set(SDL2_image
13  /Library/Frameworks/SDL2_image.framework)
14set(SDL2_ttf
15  /Library/Frameworks/SDL2_ttf.framework)
16
17target_link_libraries(
18  Sandbox PRIVATE
19  ${SDL2}/Versions/A/SDL2
20  ${SDL2_image}/Versions/A/SDL2_image
21  ${SDL2_ttf}/Versions/A/SDL2_ttf
22)
23
24target_include_directories(
25  Sandbox PRIVATE
26  ${SDL2}/Versions/A/Headers
27  ${SDL2_image}/Versions/A/Headers
28  ${SDL2_ttf}/Versions/A/Headers
29)

Note that you will need to replace "Sandbox" with your project name. The name in project(), add_executable(), target_link_libraries(), and target_include_directories() must be identical in all 4 locations.

Verifying it Worked

If everything is installed correctly, the following simple program should compile and execute successfully:

1#include <SDL.h>
2#include <SDL_image.h>
3#include <SDL_ttf.h>
4
5int main() {
6  SDL_Init(SDL_INIT_VIDEO);
7  IMG_Init(IMG_INIT_PNG);
8  TTF_Init();
9}

Our program will just run and immediately close, but that’s good enough. As long as it was compiled successfully, everything has been set up correctly, and we’re ready to get started!

Summary

Setting up SDL2 on macOS involves downloading the precompiled framework files and integrating them into your C++ project.

Whether you use Xcode or CMake, a few configuration steps will get you ready to start building cross-platform applications with SDL2:

• Download the latest SDL2, SDL2_image and SDL2_ttf .dmg releases
• Copy the framework bundles to /Library/Frameworks
• Add the frameworks and set the search paths in your Xcode project
• Or use the find_package() and target_link_libraries() commands in CMake
• Verify your setup with a small program that initializes the SDL2 modules

Next Lesson

Building SDL2 from Source on macOS (Xcode)

Guide for building SDL2 from source on MacOS. Including support for Apple Silicon - M1/M2, and setting up a C++ project using Xcode.

ContinueView Course