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

Ryan McCombe
Ryan McCombe

SDL2 is a cross-platform library that gives us the ability to create windows, access input devices and create graphics.

In this guide, we’ll walk through the process of adding it to a C++ project using Xcode on a mac. This includes Macs that use Apple Silicon - M1 and M2 processors.

We’ll be building SDL2 from the source code. This may seem daunting, but the SDL2 code comes with some very helpful scripts that make things much easier.

First things first, we need to download the source code from GitHub.

Download SDL2 Source

The latest version of SDL will be available on the releases page on GitHub:

We want to download the source code version - either as a zip or tar.gz file.

Screenshot of the github releases page

Once downloaded, we can decompress that into any location on our hard drive.

Build SDL2 From Source

Within finder, we should navigate to the folder that was decompressed - typically it will be called SDL-main. Within that folder, we should create a new folder, called build.

Then, right click on the new build folder and select New Terminal at Folder.

Within the new terminal window, run the command ../configure

Command not found: configure

The main cause of this error is that the terminal window is not in the correct location. We want the build folder to be inside the folder that was decompressed from the GitHub download. Then, we want the terminal to be open inside that folder.

You can check for this using the command pwd - the output is likely to be something like:


Specifically, we want the ending of this output to be SDL-main/build. If that is not the case, ensure you’re creating the correct folder hierarchy and try again

The configure command will scan your system to better understand how SDL2 should be compiled. It should complete within a few seconds.

When it is complete, run the command make in the same build location. This command will take a little longer, as it is compiling SDL2.

When that process completes, we next need to install the software onto our machine. That can be done with the command: sudo make install

Finally, when that completes, we should run the following command, again from the build folder: sdl2-config --libs --cflags

This command will show exactly where SDL2 was installed. Copy that output somewhere - we will need it later. The output will look something like this:

-L/usr/local/lib -lSDL2
-I/usr/local/include/SDL2 -D_THREAD_SAFE

In summary, the 4 commands we need to run, in order, from the build folder are:

  1. ../configure
  2. make
  3. sudo make install
  4. sdl2-config --cflags --libs

With this step complete, it’s time to move over to our XCode project and add SDL2 to it

Add SDL2 to the Xcode Project

Next, we need to add SDL2 to the Xcode project, or create a new one if needed.

Once the project is open, we need to open the settings for it. Within the General tab, under the Frameworks and Libraries section, we need to add a new library using the + icon.

Xcode Settings Menu - General Tab

At the bottom of the popup menu, select Add Other, followed by Add Files.

Next, we need to navigate to the location suggested when we ran sdl2-config --libs --cflags earlier.

My output was the following:

-L/usr/local/lib -lSDL2
-I/usr/local/include/SDL2 -D_THREAD_SAFE

We’re interested in the lib folder, so in my case, the location we want is /usr/local/lib. Your location may have been different.

Either way, we need to navigate to the folder listed. The path may be hidden, so you will need to press Command + Shift + . (period) to show hidden files.

Once we’re in the location, we want to select the .dylib file that is a UNIX executable:

Xcode Settings Menu - Find Library

After selecting that file, the Framework and Libraries section of the project settings should be updated:

Xcode Settings Menu - Frameworks and Libraries

Finally, within the Build Settings tab of our project settings, we need to scroll down to the Search Paths section. There, we need to add the respective SDL locations to the Header Search Paths and Library Search Paths.

Again, these were the paths given by the sdl2-config --libs --cflags command. We need to put the lib path in the Library Search Paths section, and the include path in the Header Search Paths section.

In my case, it looks like this, but your paths may have been different:

XCode settings menu - Build Settings

With everything set up, we should now be able to #include SDL files in our code, and start using it!

Creating a Window

The following is a minimalist main.cpp file that will test our setup:

#include <SDL.h>

int main() {

  SDL_Window* Window { SDL_CreateWindow(
    "Hello Window", 0, 0, 800, 300, 0
  ) };

  SDL_Surface* WindowSurface {

    SDL_MapRGB(WindowSurface->format, 40, 40, 40)

  SDL_Event event;
  while(true) {

If everything is working correctly, we’ll see a window pop up when our program runs:

Screenshot showing a blank window

Was this lesson useful?

Ryan McCombe
Ryan McCombe
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
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 using CMake

Guide for building SDL2 from source and setting up a development environment on any system that supports CMake
Contact|Privacy Policy|Terms of Use
Copyright © 2023 - All Rights Reserved