Building SDL2 from Source (GCC and Make)

Note that this guide is more advanced than our earlier options. If we just want to get up and running with SDL on Windows, most will find it easier to use a package manager:

If we're using Windows or Mac, we do not need to compile the SDL libraries ourselves. Precompiled packages are available for those operating systems, which we can just download:

If we want or need to build the libraries from source, and our environment supports CMake, this guide is recommended:

Compiling SDL following this guide relies on using a suite of command line tools that can build C++ projects. This is sometimes referred to as a toolchain.

• On most Linux-based systems, the tools we need are installed by default
• On macOS, the tools are available if we've installed Xcode. Alternatively, we can install them from the official Apple Developer site. A dedicated guide for installing them is available on freecodecamp.org
• We don't cover Windows in this guide, but those interested in setting up a similar environment should consider the Windows Subsystem for Linux or follow the using MinGW guide on Microsoft's site.

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.

Once we have our compilation toolchain set up, we need to download the SDL source code from GitHub. The latest version of SDL will be available on the releases page on GitHub.

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

Once we've found the latest version 2 release, we want to download the source code - either as a zip or tar.gz file:

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

Next, 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, we should navigate to that build folder within a terminal window:

• In MacOS, we can right-click on the folder and select New Terminal at Folder
• On Windows, we can right-click on the folder and select Open in Terminal

Step 1: configure

Once our terminal is open at the correct location, we can run the command:

1../configure

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

Step 2: make

When it is complete, run the command make in the same build location.

1make

This command will take a little longer, as it is compiling SDL2.

Step 3: make install

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

Again, we run this from the same build folder we've used for all the previous commands:

1sudo make install

Step 4: sdl2-config

Finally, when our make install completes, we need to find out where the SDL libraries were installed, so we can use them in our projects.

To do this, we can run the following command, again from the build folder:

1sdl2-config --libs --cflags

This script will report where our SDL libraries were installed, and where the header files are that we will #include in our source files.

The output may look something like below:

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

We should make a note of this output, as we'll need it when we want to add SDL to one of our projects.

Summary

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, we have successfully compiled and installed SDL2 in our system, and we're ready to use it in our projects!

Now that SDL is installed on our system, we can add it to our C++ projects. The way we do this depends on what tool we're using, but the basic idea involves updating our project settings based on the output from the sdl2-config command we ran earlier.

The command outputs two directories:

• The directory where the SDL libraries were installed
• The directory where the SDL header files are, so the compiler can find them when we use the #include directive

In my case, the output of sdl2-config --cflags --libs was:

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

The exact formatting of this output is intended to be used in a command-line environment. But, if we're using an IDE to configure our project, we can extract the output we need.

For my example output, we can infer that:

• the libraries are available in /usr/local/lib
• the header files are available in /usr/local/include/SDL2

Your output may have been different, and therefore the paths you need to use may also be different.

Let's see an example of using these directories to add SDL to an Xcode project. The process for other IDEs is likely to be quite similar

Step 1: Adding the Library as a Dependency

Within the General tab, under the Frameworks and Libraries section, we can add a 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

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 may need to show hidden files (Command + Shift + . on macOS) to see the required path.

Once we're in the location, we want to select the .dylib file:

Note that when configuring a project on Windows, the library will have a .dll extension instead.

After selecting our library, the Framework and Libraries section of the project settings should be updated:

Step 2: Adding the Library and Header Search Paths

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!

Imagine we have the following cmake project:

1cmake_minimum_required(VERSION 3.16)
2
3set(CMAKE_CXX_STANDARD 20)
4
5project(Sandbox VERSION 1.0.0)
6add_executable(Sandbox main.cpp)

We need to add the SDL library and include directory to this file. Our earlier call to sdl2-config --libs --cflags should have given us two directories we need. For example, my output was:

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

This means:

• The SDL library is located in /usr/local/lib
• The SDL header files are located in /usr/local/include/SDL2

Adding the Libraries

To add the library as a project dependency, we need to find it within the library directory provided above. The library will have a .dylib extension in macOS or Linux-based operating systems, and .dll in Windows.

Once we've found it, we add it to our CMakeLists.txt. This should come after our project() call, and we should replace Sandbox with the name of our project:

1target_link_libraries(
2  Sandbox PRIVATE /usr/local/lib/libSDL2.dylib
3)

Adding the Include Directories

Finally, we need to add the include directories to our CMakeLists.txt. Again, this should come after our project() call, and we replace Sandbox with the name of our project:

1target_include_directories(
2  Sandbox PRIVATE /usr/local/include/SDL2
3)

My complete CMakeLists.txt file looks like this:

1cmake_minimum_required(VERSION 3.16)
2
3set(CMAKE_CXX_STANDARD 20)
4
5project(Sandbox VERSION 1.0.0)
6add_executable(Sandbox main.cpp)
7
8target_include_directories(
9  Sandbox PRIVATE
10  /usr/local/include/SDL2
11)
12
13target_link_libraries(
14  Sandbox PRIVATE
15  /usr/local/lib/libSDL2.dylib
16)

The following is a minimalist main.cpp file that will test our setup. We'll explain every line of this program in the next chapter but, for now, let's just confirm it compiles and runs:

1#include <SDL.h>
2
3int main(int argc, char** argv) {
4  SDL_Init(SDL_INIT_VIDEO);
5
6  SDL_CreateWindow(
7    "Hello Window",
8    100, 100, 800, 300, 0
9  );
10  
11  while(true) {
12    SDL_PumpEvents();
13  }
14  
15  return 0;
16}

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

Note that this example program does not allow itself to be closed. We'll add that capability later in the course. For now, we can close it using our IDE if possible, or force it to close through our operating system (Ctrl + Alt + Del on Windows or Cmd + Option + Esc on macOS).

We'll update our program to support quitting early in the next chapter.

SDL2 has a collection of official extensions, that can add further capabilities to our project. In this course, we'll use SDL_image for handling images, and SDL_ttf for rendering text.

Step 1: Download the Source Code

To add them to our project, we first retrieve the source code for the latest 2.x releases. These are available from GitHub:

• The SDL_image releases are available here: https://github.com/libsdl-org/SDL_image/releases
• The SDL_ttf releases are available here: https://github.com/libsdl-org/SDL_ttf/releases

Step 2: Download External Dependencies

Building the SDL extensions from source involves an additional step that didn't apply to the base SDL library. The extensions have external dependencies, that we also have to download.

After we unzip the SDL_image and SDL_ttf releases, we'll see they contain an /external directory. This is where their dependencies need to be inserted. There are some scripts in that directory that can automate this for us.

Linux / macOS users can open a terminal in the external folder, and run the download.sh script:

1download.sh

Windows users can run the Get-GitModules.ps1 script in PowerShell instead:

1Get-GitModules.ps1

Step 3: Build the Library

Once the /external folder is populated with our dependencies, the remaining steps are the same as we covered when building the main SDL library:

1. Create a build folder within the downloaded source code, then navigate to that build folder within a terminal
2. Run ../configure
3. Run make
4. Run sudo make install
5. Run sdl2-config --cflags --libs and make a note of the output

Step 4: Add the Library as a Dependency

Once we've built the library, we need to add it as a dependency to our project. How we do that depends on the tools we're using, but it broadly involves following the same steps we performed when setting up the base SDL2 library.

In an IDE such as Xcode, this involves repeating the steps we covered earlier to add a new entry under the Frameworks and Libraries section

After adding SDL2, SDL_image, and SDL_ttf to my Xcode project, the libraries and framework section looks like this:

In a CMake project, this involves adding new entries to our target_link_libraries() call:

1target_link_libraries(Sandbox PRIVATE
2  /usr/local/lib/libSDL2.dylib
3  /usr/local/lib/SDL2_image.dylib 
4  /usr/local/lib/SDL2_ttf.dylib 
5)

Step 5: Update the Search Paths

Finally, we need to update our search paths so our project can find the header files we #include to access the library functions.

Note that the header files may be installed in the same location as the base SDL2 header files, so we may not need to make any further changes in this step.

In my case, make install placed the SDL_image and SDL_ttf libraries and headers into the same folders as the base SDL2 library and headers, so no additional search paths were required:

In a CMake project, the target_include_directories call of our CMakeLists.txt could also remain the same:

1target_include_directories(
2  Sandbox PRIVATE
3  /usr/local/include/SDL2
4)

If our new header files were located elsewhere, we'd simply need to expand the search list in our IDE, or add additional include directories in our CMakeLists.txt:

1target_include_directories(
2  Sandbox PRIVATE
3  /usr/local/include/SDL2
4  /usr/local/include/SDL2-image 
5  /user/local/include/SDL2-ttf 
6)

Step 6: Compiling and Running The Program

After completing these 5 steps for the SDL2, SDL_image, and SDL_ttf, we can test that everything is working correctly by adding and initializing SDL_image and SDL_ttf to our previous program, and ensure everything still runs as before:

1#include <SDL.h>
2#include <SDL_image.h>
3#include <SDL_ttf.h>
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  IMG_Init(IMG_INIT_PNG);
8  TTF_Init();
9    
10  SDL_CreateWindow(
11    "Hello Window",
12    100, 100, 800, 300, 0
13  );
14    
15  while(true) {
16    SDL_PumpEvents();
17  }
18  
19  return 0;
20}

If the previous program fails to compile, it's generally going to be one of two problems - either the compiler can't find the files we're trying to #include, or the linker can't find the symbols we're attempting to use, such as SDL_Init().

We can generally infer which problem we're dealing with based on the error messages. The inability to find an include file usually generates a descriptive error message, whilst linker errors will typically use terminology like "undefined symbol".

The key steps in building SDL2 from source involve downloading the code from GitHub, running the configuration and build scripts, and linking the compiled libraries to your project. With SDL2 and its extensions set up, you'll be ready to start developing! Key takeaways:

• SDL2 can be built from source on Linux and macOS using the provided configuration and build scripts
• SDL_image and SDL_ttf extensions add support for images and fonts
• Linking the compiled SDL2 libraries to your project requires specifying the library and include paths
• Troubleshooting common compilation, linking, and runtime errors is essential for a smooth development experience