Debugger

When a program crashes, you will typically get a crude and unhelpful message such as "Segmentation Fault" or "This program has performed an illegal operation". Reproducing a crash may be very difficult, and posting a bug related to such a crash is largely a waste of time. If a developer can't reproduce a crash, it cannot be fixed.

To catch each and every crash, it is recommended that developers and testers always run odamex with a debugger. This is a piece of software that can 'catch' crashes and provide very useful developer information.

A debugger is a vital piece of software used in our software development process. It can be used to hunt down the how's and why's of crashes and odd behaviors in Odamex. Please note that if you are not running a release version of Odamex, it's a good idea to ALWAYS have a debugger attached to Odamex, just in case something breaks.

Debuggers

gdb

gdb is the gnu debugger, available on just about all of the platforms for which odamex is supported. To start odamex with gdb, for example:

gdb odamex

You will be presented with a command line interface. From here, there are several things you can do:

• set args <arguments> will set the program's arguments
• run will execute the program
• continue will resume the program in the event it is paused either automatically through the use of a breakpoint or by manually pausing with Ctrl+C
• bt will get the stack trace (callstack) of the program in the event of a crash. This is important, as it shows where exactly the program crashed.

A knowledge of shell scripting or batch files might be useful to maintain a debugging environment.

Microsoft Visual C++ 6.0

Visual C++ has a built-in debugger. You must use the debug build for debugging to work. Use the debug menu to launch odamex in debug mode. If you have ran odamex from outside the debugger and it crashed, you can still attach the to the crashed process if you do not dismiss the crash dialog. To get the callstack, use the menus (View->Debug Windows->Call Stack).

Code::blocks

Code::blocks makes use of gdb as its default debugger. See the article about gdb for more information.

valgrind

Valgrind isn't strictly a debugger, but it deserves a mention nontheless for its uncanny ability to sniff out memory management and threading bugs that would normally be rather difficult to pinpoint.

Start valgrind with:

valgrind --leak-check=yes odamex

The console will be flooded with data, and Odamex should start up and run...very slowly. Do your testing as best you can, and when you quit, valgrind should summerize what suspicious activity it found. Refer to the [valgrind manual] for information on how to interpert the errors it spits out.

What to report

When odamex crashes, the first thing a developer wants to know from a debugger is where exactly it crashed. This is referred to as the "call stack" or "back trace". In gdb, you can type "bt" to get it. When you post a bug about a crash, be sure to include this!