Setting up SDL2 in Windows (Visual Studio)

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

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

Once we've found the latest version 2 release, Windows users should download the -VC package of each library:

Once we have our three zip files, we should extract them to a location on our hard drive. It can be helpful to add them to our project directory so that everything our project needs is in one place. However, for the sake of this demo, I have extracted them to c:\sdl:

Each of the folders includes 3 things we are interested in:

• Header files (.h) within an include directory
• Object Library files (.lib) within the lib directory
• Dynamic Library files (.dll) within the lib directory

The lib directory includes both 32-bit (x86) and 64-bit (x64) versions of the libraries. In this guide we'll only be setting up the x64 version but, if your project needs 32-bit as well, the steps can be repeated for that configuration.

Let's walk through how we'd add these libraries to our Visual Studio project. We can add the libraries to an existing project, or create a new project if needed.

Once we have our project open, we need to open the project properties window, available from the top menu under Project > Properties

Within our project properties, we need to change three things:

1. Include Directories: This tells the preprocessor where the SDL header files are, so we can #include them in our own files.
2. Library Directories: This tells the linker where to find SDL libraries, once we declare that our project depends upon them.
3. Dependencies: This tells the linker that our project depends on SDL. Specifically, it means some of the variables we'll be accessing and functions we'll be calling are defined in the SDL libraries, so it needs to link them into our project

1. Adding SDL Include Directories

Under Configuration Properties > VC++ Directories, ensure we're configuring the x64 version of our project by looking at the Platform dropdown at the top. Then, open the Include Directories list, and click Edit:

Here, we need to add the include directory of each of the three zips we extracted earlier:

2. Adding SDL Library Directories

Under Configuration Properties > VC++ Directories, open the Library Directories list, and click Edit

Here, we need to add the library directory from each of the three zips we extracted earlier. Because we're configuring the 64-bit version of our project (x64) we use the x64 directories:

3. Adding SDL Libraries as Dependencies

Under Configuration Properties > Linker > Input, open the Additional Dependencies list, and click Edit:

Here, we need to add a list of .lib files:

1SDL2.lib
2SDL2main.lib
3SDL2_ttf.lib
4SDL2_image.lib

These are file names that should exist within the lib directories we added to our project in step 2

If everything is set up correctly, the following simple program should now compile successfully. Note that the program may not yet run successfully, but at this point, we just want to ensure it compiles:

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  return 0;
11}

Even though our program now compiles successfully, we may be getting errors when we try to run it. Our program may crash and report an error like:

1The code execution cannot proceed because SDL2.dll was not found

To fix this, we need to ensure our system can find the SDL libraries our program is using. The three DLL files we need are:

1SDL2.dll
2SDL2_image.dll
3SDL2_ttf.dll

These are included within the zips we downloaded earlier, within the /lib/x64 directory of each zip file. The easiest way we can help our system find these DLLs is to copy them to the same location as the executable that runs our program.

Note that in this image, my project is called SDL2, so the executable is called SDL2.exe. Yours will likely be different:

It's important to remember our compiled project is no longer a single .exe file - it now includes these .dll files. When we ship our program, we need to include all of the required .dll files so our users can run it.

We can validate everything is set up correctly by compiling and running the following program. We'll explain every line of this program soon but, for now, let's just confirm it compiles and runs:

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

In this lesson, we covered how to set up the SDL2 library for Windows development using Visual Studio. The key steps are:

• Download the SDL, SDL_image and SDL_ttf libraries
• Add the include and library directories to your project settings
• Add the .lib files as additional dependencies
• Copy the .dll files to the same directory as your executable

With SDL2 set up, you're now ready to start using it in the next chapter!