This answer deals with MinGW / GCC, and not Visual Studio.
This answer deals primarily with Windows. Things are easier on other OSes, see the bottom of the answer for a summary.
I tried to keep this answer dead simple, so that even a newbie can use it.
Common errors
The common errors you can get are:
SDL.h: No such file or directory (when compiling)undefined reference to various functions (when linking)- Mysterious
.dll-related errors (when running your program).
This list is sorted from bad to good. If you change something and get a different error, use this list to tell if you made things better or worse.
See the answer below for how to fix all of those.
The preamble
Here's some things I want to tell you before we get to fixing the errors.
0. Don't follow bad advice.
Some resources will suggest you to do #define SDL_MAIN_HANDLED or #undef main. Don't do that. Those solutions deviate from how SDL2 is intended to be used, and with the right setup they are NEVER necessary.
Some argue that those are better than the intended way, but I suggest to learn the intended way first, then learn what the difference is, and then make an educated decision.
1. Figure out how to compile directly from the console, you can start using an IDE later.
If you're using an IDE, I suggest to first make sure you're able to compile your program directly from the console, to rule out any IDE configuration problems. After you figure that out, you can use the same compiler options in your IDE.
I also suggest avoiding CMake if you just started, to rule out any CMake-related problems. You can start using it later.
2. Download the right SDL2 files. Make sure you have the right files. You need the archive called SDL2-devel-2.0.x-mingw.tar.gz from here.
Unpack it in any directory, preferably somewhere near your source code. Unpacking directly into the compiler directory is often considered a bad practice.
3. Know the difference between compiler flags and linker flags. A "flag" is an option you specify in the command line when building your program. When you use a single command, like g++ foo.cpp -o foo.exe, all your flags are added to the same place (to this single command).
But when you build your program in two steps, e.g.:
g++ foo.cpp -c -o foo.o (compiling)g++ foo.o -o foo.exe (linking)
you have to know which of the two commands to add a flag to. The flags that need to be added to the first command are "compiler flags" and the flags that need to be added to the second are "linker flags". In the answer below, when telling you to add a flag, I'll specify if it's a compiler flag or a linker flag.
Most IDEs will require you to specify compiler and linker flags separately, so even if you use a single command now, it's good to know which flag goes where.
Unless specified otherwise, the order of the flags doesn't matter.
SDL.h: No such file or directory
Or any similar errors related to including SDL.h or SDL2/SDL.h.
You need to tell your compiler in which directory SDL.h is located. It's in the SDL files you've downloaded (see preamble).
Add following to your compiler flags: -I, followed by a directory.
Example: -IC:/Users/HolyBlackCat/Downloads/SDL2-2.0.12/x86_64-w64-mingw32/include/SDL2. (Relative paths work too, e.g. -ISDL2-2.0.12/x86_64-w64-mingw32/include/SDL2.)
Note that the flag can be different depending on how you write the #include:
- If you do
#include <SDL.h>, then the path should end with .../include/SDL2 (like above). This is the recommended way.
- If you do
#include <SDL2/SDL.h>, then the path should end with .../include.
undefined reference to various functions
The error message will mention various SDL_... functions (often the ones you use in your program), and/or WinMain. If it mentions SDL_main, consult the section "undefined reference to SDL_main only" below.
You need to add following linker flags: -lmingw32 -lSDL2main -lSDL2. The order matters. The flags must appear AFTER any .c/.cpp/.o files.
Writing -lSDL2main -lSDL2 tells the linker to use files called libSDL2main.a, libSDL2.a (or libSDL2.dll.a) that are included in the SDL files you downloaded. You need one more flag to tell the linker where to look for those .a files. Add following to your linker flags: -L, followed by the directory.
Example: -LC:/Users/HolyBlackCat/Desktop/SDL2-2.0.12/x86_64-w64-mingw32/lib. (Relative paths work too, e.g. -LSDL2-2.0.12/x86_64-w64-mingw32/lib.)
I added all those flags and nothing changed:
If you did that and still get the same undefined reference errors, you probably use the wrong SDL .a files. The archive you downloaded contains two sets of files: i686-w64-mingw32 (32-bit) and x86_64-w64-mingw32 (64-bit). You must use the files matching your compiler, which can also be either 32-bit or 64-bit. Print (8*sizeof(void*)) to see if your compiler is 32-bit or 64-bit. Even if you think you use the right files, try the other ones to be sure.
A few of the MinGW versions can be switched between 32-bit and 64-bit modes using -m32 and -m64 flags (those probably have to be added to both compiler and linker flags). You can try those too.
I get undefined reference to a specific function:
? undefined reference to WinMain only
There are three possibilities, all of which were covered in the previous section:
- You forgot the
-lSDL2main flag.
- The
libSDL2main.a file you use doesn't match your compiler (32-bit file with a 64-bit compiler, or vice versa).
- You put the
-lSDL2main flag to the left of some .c/.cpp/.o files. It must always be to the right.
Try to avoid #define SDL_MAIN_HANDLED or #undef main when solving this issue, see preamble for explanation.
? undefined reference to SDL_main only
You need to have a main function. Your main function must look like int main(int, char **). NOT int main() and NOT void main(). This is one of the SDL2 quirks.
Adding any parameter names is allowed, e.g. int main(int argc, char **argv). Also the second parameter can be written as char *[] or with a name: char *argv[]. No other changes are allowed.
If your project has multiple source files, make sure to include SDL.h in the file that defines the main function, even if it doesn't otherwise use SDL directly.
Try to avoid #define SDL_MAIN_HANDLED or #undef main when solving this issue, see preamble for explanation.
.dll-related errors
You've successfully built an .exe, but can't run it because of mysterious errors mentioning some .dlls. You're almost there!
The .exe you made needs some .dlls to run. If it doesn't find them, it will tell you and refuse to run. This is easy. It can also find wrong versions of them left over from some other programs you've installed, then you'll get some very cryptic errors.
Your program will look for the .dlls in different locations, but the most reliable solution is to put them in the same directory as the .exe. This directory is searched first, so other versions of the .dlls you might have elsewhere won't interfere.
You need to figure out which .dlls your program needs and put them in the directory where your .exe is (except for the system .dlls, which you don't need to copy).
There are two types of errors you can get:
An error that just tells you what .dll is missing.
SDL2.dll is missing. — It's in the SDL files you've downloaded.
Be aware that the files contain two different SDL2.dlls: a 32-bit one (in i686-w64-mingw32 directory), and a 64-bit one (in x86_64-w64-mingw32). Get the right one, if necessary try both.
Some other .dll is missing. — It's shipped with your compiler. Look in the directory where your gcc.exe is.
If you copy one .dll and it asks for more, that's normal, you might need to repeat this ~3 times.
A cryptic .dll-related error. — Your program found a wrong version of a .dll somewhere in your system.
You need to copy all non-system .dlls it needs to the directory where your .exe is.
First, copy SDL2.dll (see the section "SDL2.dll is missing" above for where to find it).
Then, copy following .dlls from your compiler directory (the directory where gcc.exe is located):
libgcc_s_seh-1.dll (the name can vary depending on your MinGW version, but will always start with libgcc)libstdc++-6.dll (for C++ only, skip if you're writing in C)libwinpthread-1.dll (the name can vary depending on your MinGW version, but will always mention thread; some versions don't use this at all)
For some MinGW distributions, those may not be the right .dlls. If you don't see those or copying them doesn't help, continue reading.
That should fix all your errors. If you want to know more or it didn't help:
More information about the .dlls
It's possible to make an .exe that doesn't depend on any (non-system) .dlls by using the -static linker flag, this is called "static linking". This is rarely done, and you shouldn't need to do this if you did the above steps correctly. This requires different linker flags than usual (around 20 of them), see sdl2.pc file shipped with SDL for the exact flags (they are in the Libs.private section).
In the previous section I tried to guess what .dlls your program depends on. How did I know? There are several ways to figure it out for yourself:
