Installing SDL2 Libraries Manually on Windows

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Visual Studio on Windows. 
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

aSDL1_b.jpg
Ryan McCombe
Ryan McCombe
Posted

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:

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

Screenshot showing the SDL releases page on GitHub

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:

Screenshot showing the SDL libraries unzipped in Windows

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:

Screenshot showing the Include Directories configuration in Visual Studio

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

Screenshot showing the include diretories we need to set

2 - Add the SDL library directories

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

Screenshot showing the Library Directories in Visual Studio Project Settings

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:

Screenshot showing the Library Directories we need to set

3 - Add the SDL libraries as dependencies

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

Screenshot showing the Additional Dependencies in Visual Studio project settings

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

SDL2.lib
SDL2main.lib
SDL2_ttf.lib
SDL2_image.lib

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

Screenshot showing the additional dependencies we need to set

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:

#include <SDL.h>
#include <SDL_image.h>
#include <SDL_ttf.h>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  IMG_Init(IMG_INIT_PNG);
  TTF_Init();

  return 0;
}

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:

int main() {
  // ...
}
int main(void) {
  // ...
}

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:

int main(int argc, char** argv) {
  // ...

  return 0;
}

Troubleshooting: 'SDL_main': must return a value

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

int main(int argc, char** argv) {
  // ...
}

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:

int main(int argc, char** argv) {
  // ...

  return 0;
}

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:

SDL2.dll
SDL2_image.dll
SDL2_ttf.dll

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.

Screenshot showing the DLL files colocated with our executable file

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

Where is our .exe file?

The location where visual studio places your executable is called the Output Directory, and is configured from project properties, under Configuration Properties > General > Output Directory

By default, it will be within your project directory, under x64/debug

The location will also be listed within your output window when you build the project. For example, line 2 in the following output shows the location wherre my executables are being created:

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

Was this lesson useful?

Ryan McCombe
Ryan McCombe
Posted
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
DreamShaper_v7_cyberpunk_woman_playing_video_games_modest_clot_0.jpg
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

Installing SDL2 Libraries on macOS

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Xcode or CMake.
aSDL2.jpg
Contact|Privacy Policy|Terms of Use
Copyright © 2023 - All Rights Reserved