Debugging the game under Windows using gdb.exe

Getting the GNU debugger

You will need the GNU debugger for Windows, so a program gdb.exe is what you need. Information concerning the GDB is available from the GNU site

http://www.gnu.org/software/gdb/gdb.html

but this site centered more around GNU/Linux. You can get the Windows version from the MinGW (Minimalist GNU for Windows) project here:

http://www.mingw.org/download.shtml

The gdb.exe you want maybe looks somewhat like gdb-5.2.1.exe. Taking the one from the current section of the download list should do the trick. You will be asked for the mirror. Select any. After download is complete you can start with the next section.

Running the game inside the debugger

Now that you have downloaded the debugger, you can use it to run FreedroidRPG inside the debugger. This will have the advantage that in case of fatal signals like Segmentation Fault or also Floating Point Exception, you will be able to retrieve data on the exact position of code execution at the time the signal occured. This information is vital to finding bugs inside the game.

First thing you need to do is locate the FreedroidRPG executable on your hard drive. Presuming you've installed the game, it should be somewhere (either in your installation directory, or if you grabbed the cvs repository, there should be a more recent FreedroidRPG.exe inside that repository). So we locate it. In my case it's the FreedroidRPG.exe from the release 0.9.11 as shown below:

Figure 10: Locating FreedroidRPG.exe

So the executable is in the directory C:\FreeDroid\freedroidrpg-0.9.11. Wonderful. Now we can start the debugger. After starting up, it looks like this:

Figure 11: GDB has successfully started up

As you can see, I'm using version 5.2.1 here, but any other version should also do. Good. Now we need to go the the directory where our FreedroidRPG.exe is located. To do this, we can use the cd command. We enter the directory we wish to go to and that should be it. In my case, the executable resides in the directory C:\FreeDroid\freedroidrpg-0.9.11, so I type cd C:\FreeDroid\freedroidrpg-0.9.11, as shown here: (well, first I made a small typo, but then I got it right):

Figure 12: I made a small typo, but in the second attempt, I spelled everything right

Good. Now we're where we're supposed to be. Time to specify the executable we wish to debug. This can be done via the file command. We specify file freedroidRPG.exe. Like this:

Figure 13: This should inform the debugger which program we want to debug

Ok. Now we can run the game. We might want to give some extra paramters, like running inside a window (-w) or running without sound (-q) but these options are up to you. In any case they should be given right after the run command. In my case it looks like this:

Figure 14: Basically we're ready to run

After hitting enter now, the game should be running inside a window now:

Figure 15: Running! Excellent!

No we can run the game until a Segmentation Fault or a Floating Point Exception occors. In that case, the game will stop (the window might stay open and maybe it will turn black). But of course we can cancel our operation and quit the game ourselves too...

Since there isn't any Segmentation Fault happening on my machine, I had to quit the program. Anyway, after the game has quit, we should be back inside the debugger. Now too bad, I didn't get any Segmentation Fault. But here is what we'd have to do if there was one: We'd need to generate a stack backtrace. That's a list of function calls that happend shortly before the crash. We can do this by typing info stack. Like here:

Figure 16: Trying to get the stack backtrace. Too bad, since I don't have any real Segmentation faults, there's also no stack or anything to debug. But if you get Segmentation Faults regularly, there should be more to view in your case

Of course in our case, the program has safely terminated, so there is no stack backtrace here. But if he would have received a Segmentation Fault signal, we would get some stack backtrace here and this stack backtrace is the vital information that the developers need to track the bug. If you got some stack backtrace from a Segmentation Fault or from a Floating Point Exception, please mail the stack backtrace (the text from inside the debugger) to us. You can also make a screenshot from the debugger if that is more convenient for you. But please send the backtrace to our mailing list. The address is freedroid-discussion@lists.sourceforge.net. Thanks a huge lot for your efforts.