I don't know about you guys, but I had a dandy of a time trying to get SDL to work with VS.NET 2003. Even more frustrating was the half-formed answers I found on the GameDev forums, all which went something like:
Quote:
Noob: I'm getting Error A when trying to compile an SDL program in VS.NET.
Guru: Change X, fiddle with Y, and copy-and-paste Z.
Noob: OK, now I have error B...
Guru: Did you fiddle with Y?
Noob: Wait, I mysteriously fixed it. Thanks!
Helpful, right? Anyway, in this thread, I plan to methodically go through how to set up SDL properly for VS.NET and go over solutions to the multitude of linker errors that pop up. Hopefully, with a lot of edits, linkage, and feedback, this can be become a stable resource for this prevalent and (I think) not-well-covered problem.
Definitions
First off, I will be setting up SDL 1.0.8 - Development Runtime with my copy of Visual Studio .NET 2003 - Academic Edition. I will be attempting to get the following piece of code to compile and run, which should display an empty window:
#include "SDL.h"
const int WINDOW_WIDTH = 640;
const int WINDOW_HEIGHT = 480;
const char* WINDOW_TITLE = "SDL Start";
int main(int argc, char **argv)
{
SDL_Init( SDL_INIT_VIDEO );
SDL_Surface* screen = SDL_SetVideoMode( WINDOW_WIDTH, WINDOW_HEIGHT, 0,
SDL_HWSURFACE | SDL_DOUBLEBUF );
SDL_WM_SetCaption( WINDOW_TITLE, 0 );
SDL_Event event;
bool gameRunning = true;
while (gameRunning)
{
if (SDL_PollEvent(&event))
{
if (event.type == SDL_QUIT)
{
gameRunning = false;
}
}
}
SDL_Quit();
return 0;
}
This code is from
Aaron's SDL Tutorial page, which has a lot of helpful SDL info, including a VS.NET setup walkthrough.
VS.NET setup
Before we delve into any linker errors, let's go over how a simple setup should go:
- Open up a new Empty Project (.NET). This should give you (surprise!) an empty project with three folders.
- Right-click on the Source Files folder and select Add New Item. Add a .cpp file called main.cpp. Copy-and-paste the above code (or use your own) into main.cpp.
- Choose Tools->Options->Projects->VC++ Directories. Under Show Directories For:, choose Include Files, then click the New Line button. Use the Browse (...) button to find your <yourpath>/SDL-1.0.8/include folder. Do the same for your library files by choosing Library Files and <yourpath>/SDL-1.0.8/lib. This ensures that VS.NET can find your SDL files.
- Choose Project-><ProjectName> Properties->C/C++ ->Code Generation. For Runtime Library, choose Multi-Threaded Debug DLL (/MDd) if you're running in Debug mode, Multi-Threaded DLL if you're running in Release. This ensures that SDL's dynamic libraries are being loaded correctly.
- Choose Project-><ProjectName> Properties->Linker->Input. For Additional Dependencies, type in "sdl.lib sdlmain.lib" (w/o the quotes). This actually links the SDL libraries to your project.
- Choose Project-><ProjectName> Properties->Linker->System. For SubSystem, choose Console if your program uses int main(), Windows if it uses WinMain. This ensures that the SDL libraries know which program entry point you'll be using (main vs. WinMain).
- Copy SDL.dll from your SDL-1.0.8/lib directory into your project directory.
- Build your project. It should compile with perhaps a few warnings, but no errors. Easy, right?
At this point, you probably have more than a few linker errors. The next section goes over these and various home remedies.
Linker Errors
Fatal error LNK1561: entry point must be defined
Causes
- Properties->Linker->Input->Ignore All Default Libraries is set to Yes
- Properties->C/C++->Code Generation->Runtime Library is set incorrectly
- Properties->Linker->System->SubSystem is not set
- Your main.cpp doesn't contain a main() or WinMain() function.
Explanation
Basically, VS.NET is looking to SDL for an entry point, a place to start running the program, and SDL can't find one. This can mean one of two things. There could not
be a main()/WinMain() method, in the which case, you should get working on that. Or VS.NET could be reading in the DLL incorrectly. In this case, check that the Runtime Library setting is set for a multi-threaded DLL and matches your build mode (Debug/Release). The linker subsystem can be set to either CONSOLE or WINDOWS. The choice determines whether main() or WinMain() is searched for, so make sure it's set correctly. The whole "Ignore Default Libraries" deal I'm still not sure on, so I won't try to explain it (see LNK4098). Needless to say, setting it to Yes caused a linker error for me, setting it to No did not.
Error LNK2019: unresolved external symbol _SDL_main referenced in function _main
Causes
- Your main function signature isn't written exactly like this: "int main(int argc, char **argv)"
Explanation
SDL uses type matching to convert the system function call to main() to a call to SDL_main(). Unfortunately, this matcher is very picky, so your main method signature has to be written just so. Using "int main()" or even "int main (int argc, char *argv)" will throw this error.
Multiple errors LNK2005: <SomeFunction> already defined in <SomeLibrary>.lib
Causes
- Properties->C/C++->Code Generation->Runtime Library is set incorrectly
Explanation
If you don't make sure to specify to VS.NET that SDL is a multi-threaded DLL, it will do some weird things, including redefining a lot of code, causing this particular error. If you're running in Debug, make sure to classify SDL as a Multi-Threaded Debug DLL, and as a Multi-Threaded DLL if you're running in Release.
error LNK2019: unresolved external symbol _main referenced in function _mainCRTStartup
Causes
- SDLmain.lib not properly included
Explanation
This error is a result of VS.NET not properly finding the SDLmain library file. Either it was never typed into the Linker->Input->Add'l Dependencies field (if not, do that now) or SDLmain.lib isn't where VS.NET is looking for it. Check both that the SDL lib directory is in the VS Library Files directory list and that SDLmain.lib is in that folder.
warning LNK4098: defaultlib 'msvcrt.lib' conflicts with use of other libs; use /NODEFAULTLIB:library
Causes
- Properties->Linker->Input->Ignore All Default Libraries is set to No.
Explanation
An astute observer will notice that the cause of this warning directly conflicts with the solution to LNK1561. I'm aware of this discrepancy, and am not quite sure how to solve it. Fixing one undoes the other as far my experiments find. The warning doesn't prevent SDL programs from functioning, so I advise leaving it be for now.
Links to SDL - VS.NET resources
Main SDL page
Aaron's SDL Tutorial page
Links to other SDL - VS.NET linker error threads
SDL error : undefined reference to _alloca_probe
more SDL help (trouble with LNK1561, LNK2019, LNK4098)
SDL Linker errors (trouble with LNK2019)
Linker Error =( (trouble with LNK2019, LNK2005)
Got Linker Error (trouble with LNK2019)
I'm well aware that this guide is far from complete. I definitely welcome any feedback or clarification on things I missed. As I said, hopefully this will become a resource that will turn an otherwise chipper SDL session into a bitter tug-of-war with the VS.NET linker.
