Difference between revisions of "Using SDL with Code::Blocks"

From Code::Blocks
 
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
(Contributed by [http://www.ubergeekultd.com Ubergeek, ultd]. Copied by Thomas)
+
[[Category:User Documentation]]
 +
 
 +
Written by Thomas.
 +
Original idea by [http://www.ubergeekultd.com Ubergeek, ultd].
  
 
=="The Good, the Bad, and the Ugly" - Setting up SDL==
 
=="The Good, the Bad, and the Ugly" - Setting up SDL==
  
This article deals with [[SDL]] using [[CodeBlocks:About|Code::Blocks]] with the [http://www.mingw.org MinGW compiler], however the same steps will likely work with a different compiler (such as MSVC2003 toolkit) or under Linux, too (Linux users will of course not worry about DirectX).
+
This article deals with [http://www.libsdl.org/ SDL] using [[CodeBlocks:About|Code::Blocks]] with the [http://www.mingw.org MinGW compiler], however the same steps will likely work with a different compiler (such as MSVC2003 toolkit) or under Linux, too (Linux users will of course not worry about DirectX).
  
 
There are many ways to get the necessary libraries and include files to set up SDL to be used with Code::Blocks, each of them having its own advantages and disadvantages. In  memory of Sergio Leone's best movie, I will call these "the Good", "the Bad", and "the Ugly".<br />
 
There are many ways to get the necessary libraries and include files to set up SDL to be used with Code::Blocks, each of them having its own advantages and disadvantages. In  memory of Sergio Leone's best movie, I will call these "the Good", "the Bad", and "the Ugly".<br />
Line 19: Line 22:
 
#Some archiving program (tar, 7z, WinZip, PowerArchiver, ...)<br />
 
#Some archiving program (tar, 7z, WinZip, PowerArchiver, ...)<br />
 
===The Process===
 
===The Process===
#Download [http://www.libsdl.org/release/SDL-devel-1.2.8-mingw32.tar.gz SDL-devel-1.2.8-mingw32.tar.gz] from the [http://www.libsdl.org/download-1.2.php SDL version 1.2.8 download page]. There are binary packages for several Linux distributions, too (<tt>rpm</tt> may have problems downloading directly from libsdl.org, use <tt>wget</tt> to get the packages in that case).
+
#Download [http://www.libsdl.org/release/SDL-devel-1.2.9-mingw32.tar.gz SDL-devel-1.2.9-mingw32.tar.gz] from the [http://www.libsdl.org/download-1.2.php SDL version 1.2.9 download page]. There are binary packages for several Linux distributions, too (<tt>rpm</tt> may have problems downloading directly from libsdl.org, use <tt>wget</tt> to get the packages in that case).
 
#Decompress the archive
 
#Decompress the archive
#Copy <tt>SDL.dll</tt> from inside the <tt>bin</tt> folder to where you keep your dll files (could be <tt>C:\MinGW\dll</tt> or <tt>C:\MinGW\lib</tt>, whatever).
+
#Copy <tt>SDL.dll</tt> from inside the <tt>bin</tt> folder to the your compilers bin directory (ie <tt>C:\Mingw\bin</tt>) This allows the compiler to find the dll at runtime time without having to put it in the same folder as your program or in the windows folder.
 
#Copy the contents of <tt>lib</tt> to your compiler's lib folder. If MinGW is installed under <tt>C:\MinGW</tt>, then this will be <tt>C:\MinGW\lib</tt>.
 
#Copy the contents of <tt>lib</tt> to your compiler's lib folder. If MinGW is installed under <tt>C:\MinGW</tt>, then this will be <tt>C:\MinGW\lib</tt>.
 
#Copy the complete folder <tt>SDL</tt> from inside the folder <tt>include</tt> to your compiler's include directory (for example <tt>C:\MinGW\include</tt>). Be sure to copy the ''folder'', not the individual files.
 
#Copy the complete folder <tt>SDL</tt> from inside the folder <tt>include</tt> to your compiler's include directory (for example <tt>C:\MinGW\include</tt>). Be sure to copy the ''folder'', not the individual files.
 
#Optionally, copy <tt>SDL.dll</tt> to <tt>C:\Windows</tt>, too. This will save you from copying the dll to each and every project directory while developing. Be cautious, however, not to find yourself in [http://en.wikipedia.org/wiki/DLL_hell DLL hell] afterwards.
 
#Optionally, copy <tt>SDL.dll</tt> to <tt>C:\Windows</tt>, too. This will save you from copying the dll to each and every project directory while developing. Be cautious, however, not to find yourself in [http://en.wikipedia.org/wiki/DLL_hell DLL hell] afterwards.
#Screw the rest
+
#Screw the rest (in particular, forget about sdlconfig - it will not work)
 
It is of course possible to keep the library and include files in different locations than the ones stated above. In that case, you will have to add those locations to the compiler options. However, be sure ''not'' to add the <tt>SDL</tt> folder to include paths, but its ''parent folder'', as all SDL programs expect the headers to be inside a separate <tt>SDL</tt> folder.
 
It is of course possible to keep the library and include files in different locations than the ones stated above. In that case, you will have to add those locations to the compiler options. However, be sure ''not'' to add the <tt>SDL</tt> folder to include paths, but its ''parent folder'', as all SDL programs expect the headers to be inside a separate <tt>SDL</tt> folder.
 +
 
===Alternative===
 
===Alternative===
Code::Blocks comes with support for reading '''.DevPak''' files of late. This allows for an even more comfortable setup. Recent DevPaks (1.2.8) for SDL, SDL-mixer, and SDL-ttf can be found at [http://www.devpaks.org/category.php?category=SDL http://www.devpaks.org/category.php?category=SDL].<br />
+
Code::Blocks comes with support for reading '''.DevPak''' files of late. This allows for an even more comfortable setup. DevPaks (1.2.8) for SDL, SDL-mixer, and SDL-ttf can be found at [http://www.devpaks.org/category.php?category=SDL http://www.devpaks.org/category.php?category=SDL].<br />
 
'''Important:''' Please do note that the packages at devpaks.org are not original packages created by the SDL team. Be aware that devpaks.org theoretically allows anyone to upload anything under the name SDL. Although I know of no case of malware being distributed over this channel, this is a potential risk you have to be aware of.
 
'''Important:''' Please do note that the packages at devpaks.org are not original packages created by the SDL team. Be aware that devpaks.org theoretically allows anyone to upload anything under the name SDL. Although I know of no case of malware being distributed over this channel, this is a potential risk you have to be aware of.
  
Line 49: Line 53:
  
 
===The Process===
 
===The Process===
#Download [http://www.libsdl.org/release/SDL-1.2.8.tar.gz SDL-1.2.8.tar.gz] from the [http://www.libsdl.org/download-1.2.php SDL version 1.2.8 download page]
+
#Download [http://www.libsdl.org/release/SDL-1.2.9.tar.gz SDL-1.2.9.tar.gz] from the [http://www.libsdl.org/download-1.2.php SDL version 1.2.9 download page]
#Decompress the archive somewhere (I will assume <tt>C:\SDL-1.2.8</tt> from now on)
+
#Decompress the archive somewhere (I will assume <tt>C:\SDL-1.2.9</tt> from now on)
#Inside <tt>C:\SDL-1.2.8</tt>, locate the file <tt>VisualC.zip</tt>, decompress it, and open the workspace <tt>C:\SDL-1.2.8\VisualC\SDL.dsw</tt>
+
#Inside <tt>C:\SDL-1.2.9</tt>, locate the file <tt>VisualC.zip</tt>, decompress it, and open the workspace <tt>C:\SDL-1.2.9\VisualC\SDL.dsw</tt>
 
#As of RC1-1, Code::Blocks does not parse Visual-C projects 100% correctly, so you have to check that link libraries and include path are specified correctly.<br />
 
#As of RC1-1, Code::Blocks does not parse Visual-C projects 100% correctly, so you have to check that link libraries and include path are specified correctly.<br />
#*SDL needs <tt>winmm</tt>, <tt>gdi32</tt>, and <tt>dxguid</tt> ([http://img243.imageshack.us/my.php?image=libs2be.png Screenshot])
+
#*SDL needs <tt>winmm</tt>, <tt>gdi32</tt>, and <tt>dxguid</tt>.
#*Also, you have to add the <tt>include</tt> directory inside the SDL source directory to compiler paths ([http://img385.imageshack.us/img385/2069/inc0ke.png Screenshot]).
+
#*Also, you have to add the <tt>include</tt> directory inside the SDL source directory to compiler paths.
 
#Rebuild all (~3 minutes)
 
#Rebuild all (~3 minutes)
#Inside <tt>C:\SDL-1.2.8\VisualC\SDL</tt> and <tt>C:\SDL-1.2.8\VisualC\SDLmain</tt>, copy <tt>SDL.dll</tt> from either Debug or Release (or both) to where you keep your dlls. Also copy all of the static libraries to your compiler's <tt>lib</tt> folder.
+
#Inside <tt>C:\SDL-1.2.9\VisualC\SDL</tt> and <tt>C:\SDL-1.2.9\VisualC\SDLmain</tt>, you will find the DLLs inside the <tt>Debug</tt> and <tt>Release</tt> folders. Copy the DLLs to where you want to keep them and the static libraries to your compiler's <tt>lib</tt> folder.
#Make a folder <tt>SDL</tt> inside your compiler's include directory. Copy all files from <tt>C:\SDL-1.2.8\include</tt> into that directory
+
#Make a folder <tt>SDL</tt> inside your compiler's include directory. Copy all files from <tt>C:\SDL-1.2.9\include</tt> into that directory
 +
 
 +
[[Image:Compile sdl include libraries.png|Include directory and link libraries for building SDL in Code::Blocks]]
  
 
=="The Ugly"==
 
=="The Ugly"==
Line 71: Line 77:
 
*Some of the files in the archive may be read-only for some obscure reason. <tt>make</tt> will choke when trying to overwrite these.
 
*Some of the files in the archive may be read-only for some obscure reason. <tt>make</tt> will choke when trying to overwrite these.
 
===The Process===
 
===The Process===
#Download [http://www.libsdl.org/release/SDL-1.2.8.tar.gz SDL-1.2.8.tar.gz] from the [http://www.libsdl.org/download-1.2.php SDL version 1.2.8 download page]
+
#Download [http://www.libsdl.org/release/SDL-1.2.9.tar.gz SDL-1.2.9.tar.gz] from the [http://www.libsdl.org/download-1.2.php SDL version 1.2.9 download page]
#Decompress the archive somewhere (I will assume <tt>C:\SDL-1.2.8</tt> from now on). The path may not contain any spaces.
+
#Decompress the archive somewhere (I will assume <tt>C:\SDL-1.2.9</tt> from now on). The path may not contain any spaces.
 
#Run <tt>./configure</tt> along with all options that you wish. (~5-6 minutes)
 
#Run <tt>./configure</tt> along with all options that you wish. (~5-6 minutes)
 
#*<tt>./configure --help</tt> shows all possible packages to include as well as all available options
 
#*<tt>./configure --help</tt> shows all possible packages to include as well as all available options
Line 88: Line 94:
 
#Code::Blocks comes with a template to create SDL projects. Use that template from "New Project...".
 
#Code::Blocks comes with a template to create SDL projects. Use that template from "New Project...".
 
#Open Build options and make sure the necessary libraries are included.
 
#Open Build options and make sure the necessary libraries are included.
#*You have to link with <tt>mingw32</tt>, <tt>SDL</tt>, and <tt>SDLmain</tt> to use SDL.
+
#*You have to link with <tt>mingw32</tt>, <tt>SDL</tt>, and <tt>SDLmain</tt> to use SDL. The template should already include these, but you may want to check.
#*Also, you may want to add <tt>-mwindows</tt> to "Other linker options" to prevent a DOS window from showing (actually this is controlled by the build target type: "console" or "GUI").
+
#*If you have built your libs from MSYS, you can always run <tt>bash sdl-config --libs</tt> from SDL's source directory when in doubt. This will output the correct libraries to link with (including <tt>-mwindows</tt>, which you can omit, see next point). However, do ''not'' get tempted to derive your include paths from <tt>sdl-config</tt>, too. Although this is technically the correct way to do it, at least on Windows, these are complete garbage.
#Compile and run, you should now see a small window showing the Code::Blocks logo.
+
#*As Yiannis correctly pointed out, to avoid a DOS prompt, you should set the application's type to "GUI" inside the "Targets" tab in the project's preferences (the template defaults to "console").
 +
#Compile and run
 +
 
 +
You should now (hopefully) see a small window showing the Code::Blocks logo:
 +
 
 +
[[Image:Sdl-app.png|center|This is what you should get.]]

Latest revision as of 13:53, 20 August 2006


Written by Thomas. Original idea by Ubergeek, ultd.

"The Good, the Bad, and the Ugly" - Setting up SDL

This article deals with SDL using Code::Blocks with the MinGW compiler, however the same steps will likely work with a different compiler (such as MSVC2003 toolkit) or under Linux, too (Linux users will of course not worry about DirectX).

There are many ways to get the necessary libraries and include files to set up SDL to be used with Code::Blocks, each of them having its own advantages and disadvantages. In memory of Sergio Leone's best movie, I will call these "the Good", "the Bad", and "the Ugly".
The uglier variants have the advantage of better configurability, but are more error-prone and may take significantly more time to set up.

"The Good"

The easiest of all possibilities is to just download the SDL binary distribution directly from libsdl.org.
If you are only interested in writing a SDL application and care little about esoteric compiler switches, then the pre-built libraries are probably good enough for all your needs, so there is little reason to waste your time compiling your own.

Pro/Con

  • pro: need to download one file, setup time ~20 seconds
  • pro: it works
  • con: not configurable

Prerequisites

  1. Internet Connection
  2. Some archiving program (tar, 7z, WinZip, PowerArchiver, ...)

The Process

  1. Download SDL-devel-1.2.9-mingw32.tar.gz from the SDL version 1.2.9 download page. There are binary packages for several Linux distributions, too (rpm may have problems downloading directly from libsdl.org, use wget to get the packages in that case).
  2. Decompress the archive
  3. Copy SDL.dll from inside the bin folder to the your compilers bin directory (ie C:\Mingw\bin) This allows the compiler to find the dll at runtime time without having to put it in the same folder as your program or in the windows folder.
  4. Copy the contents of lib to your compiler's lib folder. If MinGW is installed under C:\MinGW, then this will be C:\MinGW\lib.
  5. Copy the complete folder SDL from inside the folder include to your compiler's include directory (for example C:\MinGW\include). Be sure to copy the folder, not the individual files.
  6. Optionally, copy SDL.dll to C:\Windows, too. This will save you from copying the dll to each and every project directory while developing. Be cautious, however, not to find yourself in DLL hell afterwards.
  7. Screw the rest (in particular, forget about sdlconfig - it will not work)

It is of course possible to keep the library and include files in different locations than the ones stated above. In that case, you will have to add those locations to the compiler options. However, be sure not to add the SDL folder to include paths, but its parent folder, as all SDL programs expect the headers to be inside a separate SDL folder.

Alternative

Code::Blocks comes with support for reading .DevPak files of late. This allows for an even more comfortable setup. DevPaks (1.2.8) for SDL, SDL-mixer, and SDL-ttf can be found at http://www.devpaks.org/category.php?category=SDL.
Important: Please do note that the packages at devpaks.org are not original packages created by the SDL team. Be aware that devpaks.org theoretically allows anyone to upload anything under the name SDL. Although I know of no case of malware being distributed over this channel, this is a potential risk you have to be aware of.

"The Bad"

With a little more effort, you can build SDL from sources using Code::Blocks. While this may not be the desirable solution for Joe Everybody writing Hello World for his computer science class in week one, it has certainly its advantages.

Pro/Con

  • pro: still relatively easy, build time ~5-6 minutes, setup time ~30 seconds
  • pro: it's cool
  • pro: it works
  • pro: can tune optimization/target settings, release and debug libraries
  • con: does not compile out-of-the box (yet)

Prerequisites

  1. An installation of the Code::Blocks IDE
  2. A working MinGW installation
  3. Some archiving program (tar, 7z, WinZip, PowerArchiver, ...)
  4. DirectX development headers and libraries (version 5 or later)
    • in particular, the files d3dtypes.h, ddraw.h, dinput.h, directx.h, and dsound.h are needed. The libraries come with a standard MinGW install, but the headers were strangely found to be missing on my system.
    • these files are contained in directx-devel.tar.gz which is significantly less painful to download than the Microsoft DirectX SDK (300 MB!)
    • it is unlikely that your MinGW installation lacks the headers for OpenGL, but in any case, there is an OpenGL package too.

The Process

  1. Download SDL-1.2.9.tar.gz from the SDL version 1.2.9 download page
  2. Decompress the archive somewhere (I will assume C:\SDL-1.2.9 from now on)
  3. Inside C:\SDL-1.2.9, locate the file VisualC.zip, decompress it, and open the workspace C:\SDL-1.2.9\VisualC\SDL.dsw
  4. As of RC1-1, Code::Blocks does not parse Visual-C projects 100% correctly, so you have to check that link libraries and include path are specified correctly.
    • SDL needs winmm, gdi32, and dxguid.
    • Also, you have to add the include directory inside the SDL source directory to compiler paths.
  5. Rebuild all (~3 minutes)
  6. Inside C:\SDL-1.2.9\VisualC\SDL and C:\SDL-1.2.9\VisualC\SDLmain, you will find the DLLs inside the Debug and Release folders. Copy the DLLs to where you want to keep them and the static libraries to your compiler's lib folder.
  7. Make a folder SDL inside your compiler's include directory. Copy all files from C:\SDL-1.2.9\include into that directory

Include directory and link libraries for building SDL in Code::Blocks

"The Ugly"

SDL can be built from sources using MSYS. This is certainly the most lenghty and painful way, but it also allows the most flexible configuration options.

Pro/Con

  • pro: best tuning capabilities, can easily include or exclude individual parts of SDL
  • con: painful, build time ~10-15 minutes, setup time ~30 seconds
  • con: unreliable, build sometimes fails with strange errors
  • con: have to take care of several possible pitfalls

Caveats

  • SDL explicitely needs MSYS 1.0.8 - earlier versions will not work.
  • Path names may not contain spaces, or you will utterly fail compiling.
  • Some of the files in the archive may be read-only for some obscure reason. make will choke when trying to overwrite these.

The Process

  1. Download SDL-1.2.9.tar.gz from the SDL version 1.2.9 download page
  2. Decompress the archive somewhere (I will assume C:\SDL-1.2.9 from now on). The path may not contain any spaces.
  3. Run ./configure along with all options that you wish. (~5-6 minutes)
    • ./configure --help shows all possible packages to include as well as all available options
    • you can trim down your SDL library by excluding unwanted features using --without-PACKAGE.
  4. Run make (~5-8 minutes)
  5. Pray that the build succeeds
  6. Copy the libraries and header files to your preferred places as described above.

"Arch Stanton" - Using SDL

Now that we have the libraries built and headers installed, we want to build a SDL application.

Prerequisites

  1. The Code::Blocks IDE
  2. A working MinGW installation
  3. The Good, the Bad, or the Ugly

The Process

  1. Code::Blocks comes with a template to create SDL projects. Use that template from "New Project...".
  2. Open Build options and make sure the necessary libraries are included.
    • You have to link with mingw32, SDL, and SDLmain to use SDL. The template should already include these, but you may want to check.
    • If you have built your libs from MSYS, you can always run bash sdl-config --libs from SDL's source directory when in doubt. This will output the correct libraries to link with (including -mwindows, which you can omit, see next point). However, do not get tempted to derive your include paths from sdl-config, too. Although this is technically the correct way to do it, at least on Windows, these are complete garbage.
    • As Yiannis correctly pointed out, to avoid a DOS prompt, you should set the application's type to "GUI" inside the "Targets" tab in the project's preferences (the template defaults to "console").
  3. Compile and run

You should now (hopefully) see a small window showing the Code::Blocks logo:

This is what you should get.