Building SDL2 from Source on macOS (Xcode)

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: https://github.com/libsdl-org/SDL/releases

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

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

1/Users/your-name/Downloads/SDL-main/build
2

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:

1-L/usr/local/lib -lSDL2
2-I/usr/local/include/SDL2 -D_THREAD_SAFE
3

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.

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:

1-L/usr/local/lib -lSDL2
2-I/usr/local/include/SDL2 -D_THREAD_SAFE
3

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:

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

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:

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:

1#include <SDL.h>
2
3int main() {
4  SDL_Init(SDL_INIT_VIDEO);
5
6  SDL_Window* Window { SDL_CreateWindow(
7    "Hello Window", 0, 0, 800, 300, 0
8  ) };
9
10  SDL_Surface* WindowSurface {
11    SDL_GetWindowSurface(Window)
12  };
13
14  SDL_FillRect(
15    WindowSurface,
16    nullptr,
17    SDL_MapRGB(WindowSurface->format, 40, 40, 40)
18  );
19
20  SDL_UpdateWindowSurface(Window);
21  
22  SDL_Event event;
23  while(true) {
24    SDL_PollEvent(&event);
25  }
26}
27

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