Installing SDL2 Libraries Manually on Windows

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 Windows PC, for projects being created in Visual Studio

Acquiring the Libraries

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

Windows users should download the -VC package of the latest release of each library:

Installing the Libraries

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.

Project Setup: Visual Studio

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

Here, we need to do three things:

1 - Add the 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 from each of the three zips we extracted earlier:

2 - Add the 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 - Add the 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
5

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

Compiling the Project

If everything is installed correctly, the following simple program should now compile successfully. Note, the program may not yet run successfully, but at this point, we 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}
12

Troubleshooting: unresolved external symbol SDL_main referenced in function main_getcmdline

This error is generally going to be caused if we define our main function with one of the shorter signatures:

1int main() {
2  // ...
3}
4

1int main(void) {
2  // ...
3}
4

Normally, this would work, but when we’re using SDL for Windows, the library changes the entry point of our program to ensure we use the Windows API correctly.

SDL will call our main function when it’s ready, but we need to use the full signature:

1int main(int argc, char** argv) {
2  // ...
3
4  return 0;
5}
6

Troubleshooting: 'SDL_main': must return a value

This is generally going to be caused by our main function not explicitly setting a return value:

1int main(int argc, char** argv) {
2  // ...
3}
4

Normally, this would work - the C++ specification states if our entry function doesn’t return a value, it’s treated as if it returned 0.

But, because SDL uses a different entry point, our main function needs to behave like any other function, and return the correct value type:

1int main(int argc, char** argv) {
2  // ...
3
4  return 0;
5}
6

Installing SDL2 DLLs

With our program now being able to build successfully, it is likely that we are getting errors when we try to run it. The errors will be similar to the following:

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

To fix this, we need to ensure the DLLs are accessible to our executable file. We three DLL files we need are:

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

These are included within the zips we downloaded earlier, within the /lib/x64 directory of each zip file

There are many ways to make these DLLs findable. The most common options are:

• Update our system path to include the directories where the DLLs are (under System Properties > Advanced > Environment Variables > Path)
• Copy them to a shared location that is going to be searched (typically the windows/system32 directory)
• Copy them to the same location as the executable we’re creating

The third option - copying them to the same location as the executable we’re creating - is what I’d recommend.

It keeps our project dependencies in one location and ensures the DLL file our project is using matches the exact same version number that we’ve included in our project settings.

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

1--- Build started: Project: SDL, Config: Debug x64
2SDL.vcxproj -> C:\repos\SDL\x64\Debug\SDL2.exe
3=== Build: 1 succeeded, 0 failed, 0 skipped ===
4