Installing SDL2 Libraries on macOS

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 installs the libraries on a Mac, and then demonstrates how to add them to projects in Xcode or CMake

Acquiring 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

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, CMake.

CMake is a cross-platform configuration management standard where we define what we want in plain text files. It is compatible with many IDEs, and is even the primary method of configuring our project in a few of them, such as CLion.

Project Setup: 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 scroll down to the Search Paths section.

The search paths we care about are Framework Search Paths, Header Search Paths, and Library Search Paths

It’s possible the Framework Search Paths and Library Search Paths have been automatically populated for us. But, either way, we want the following settings:

Framework 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.

Project Setup: CMake

If our IDE is compatible with CMake for configuration management, our lives are slightly easier. CMake projects are managed by a CMakeLists.txt file. This was likely created for us alongside our project.

A minimalist example might look something like this:

1cmake_minimum_required(VERSION 3.16)
2
3set(CMAKE_CXX_STANDARD 20)
4set(CMAKE_CXX_STANDARD_REQUIRED YES)
5set(CMAKE_CXX_EXTENSIONS OFF)
6
7project(Sandbox VERSION 1.0.0)
8
9add_executable(Sandbox main.cpp)
10

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

The most important line here is the call to project - that is where we specify what our project is called. In my case, I went with “Sandbox”, but yours is likely different.

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

The completed file will look something like this:

1cmake_minimum_required(VERSION 3.16)
2
3set(CMAKE_CXX_STANDARD 20)
4set(CMAKE_CXX_STANDARD_REQUIRED YES)
5set(CMAKE_CXX_EXTENSIONS OFF)
6
7project(Sandbox VERSION 1.0.0)
8
9add_executable(Sandbox main.cpp)
10
11target_link_libraries(
12  Sandbox PRIVATE
13  /Library/Frameworks/SDL2.framework/Versions/A/SDL2
14  /Library/Frameworks/SDL2_image.framework/Versions/A/SDL2_image
15  /Library/Frameworks/SDL2_ttf.framework/Versions/A/SDL2_ttf
16)
17
18target_include_directories(
19  Sandbox PRIVATE
20  /Library/Frameworks/SDL2.framework/Versions/A/Headers
21  /Library/Frameworks/SDL2_image.framework/Versions/A/Headers
22  /Library/Frameworks/SDL2_ttf.framework/Versions/A/Headers
23)
24

Note, 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}
10

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!