Installing SDL2 Libraries on macOS

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Xcode or CMake. 
This lesson is part of the course:

Making Games with SDL

Learn C++ and SDL development by creating hands on, practical projects inspired by classic retro games

aSDL2.jpg
Ryan McCombe
Ryan McCombe
Posted

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:

Mac users should download the .dmg package of each library:

Screenshot of the SDL release page on GitHub

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:

Screenshot showing all the SDL libraries installed

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.

Xcode Settings Menu - General Tab

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:

Screenshot showing all 3 libraries added to the Xcode project

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:

cmake_minimum_required(VERSION 3.16)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED YES)
set(CMAKE_CXX_EXTENSIONS OFF)

project(Sandbox VERSION 1.0.0)

add_executable(Sandbox main.cpp)

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:

cmake_minimum_required(VERSION 3.16)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED YES)
set(CMAKE_CXX_EXTENSIONS OFF)

project(Sandbox VERSION 1.0.0)

add_executable(Sandbox main.cpp)

target_link_libraries(
  Sandbox PRIVATE
  /Library/Frameworks/SDL2.framework/Versions/A/SDL2
  /Library/Frameworks/SDL2_image.framework/Versions/A/SDL2_image
  /Library/Frameworks/SDL2_ttf.framework/Versions/A/SDL2_ttf
)

target_include_directories(
  Sandbox PRIVATE
  /Library/Frameworks/SDL2.framework/Versions/A/Headers
  /Library/Frameworks/SDL2_image.framework/Versions/A/Headers
  /Library/Frameworks/SDL2_ttf.framework/Versions/A/Headers
)

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:

#include <SDL.h>
#include <SDL_image.h>
#include <SDL_ttf.h>

int main() {
  SDL_Init(SDL_INIT_VIDEO);
  IMG_Init(IMG_INIT_PNG);
  TTF_Init();
}

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!

Was this lesson useful?

Ryan McCombe
Ryan McCombe
Posted
This lesson is part of the course:

Making Games with SDL

Learn C++ and SDL development by creating hands on, practical projects inspired by classic retro games

Setting up an SDL2 Development Environment
  • 25.Making Minesweeper with C++ and SDL2
  • 26.Project Setup
  • 27.GPUs and Rasterization
  • 28.SDL Renderers
DreamShaper_v7_cyberpunk_woman_playing_video_games_modest_clot_0.jpg
This lesson is part of the course:

Making Games with SDL

Learn C++ and SDL development by creating hands on, practical projects inspired by classic retro games

Free, unlimited access!

This course includes:

  • 24 Lessons
  • 100+ Code Samples
  • 91% Positive Reviews
  • Regularly Updated
  • Help and FAQ
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.
aSDL3.jpg
Contact|Privacy Policy|Terms of Use
Copyright © 2023 - All Rights Reserved