Debugging

Contribute: Coding, Debugging, Scripting, Packaging

General

Windows

Code::Blocks

Compile the game in debugging mode
- To add debugging symbols in Windows use in C::B the Build target, through the build menu:
```
windows_debug
```
  instead of
```
windows
```
The Code::Blocks-installation includes gdb.
Integrated debugging
- Use +set vid_fullscreen 0 +set vid_grabmouse 0 +set developer 1 as program arguments
- Just select the debugging option from the menu - you will get a backtrace and so on after the game crashed
Manual debugging
- You should add the Code::Blocks installation folder to your environment path variable (most likely C:\Code::Blocks\bin)
- To start UFO:AI in the debugger you need to enter the windows-console (Start->Execute->cmd.exe)
- Enter the UFO:AI folder and type
```
gdb ufo.exe
```
- Now you are in the debug console of gdb
- Run the game with
  - ```
  run +set vid_fullscreen 0 +set vid_grabmouse 0
```
- or with
```
  run +set vid_fullscreen 0 +set vid_grabmouse 0 +set developer 1
```
  if you need the debug-messages from within the code.
- After a crash you can toggle via Alt Tab to gdb console.
- To locate the problem, type
```
bt full
```
  which generates a backtrace and displays the values of local variables.
Submit this information to the bugtracker.

Dr.MinGW

Dr.MinGW is a JIT debugger (Just-In-Time-Debugger) - see the homepage for more information about it.

gdb on Windows

Yes, gdb also works under Windows. The usage is the same as shown in the #Linux and #Useful gdb stuff section below.

Add instructions here on how to make gdb work. It seems to be incldued in Dev-Cpp, but not in others - and even in Dev-Cpp you need to set paths.

Linux

Disable ingame backtrace

./configure --disable-execinfo

gdb

You have to have gdb installed (included in the Codeblocks package).
Add the gdb.exe to your path.
Compile the game in debugging mode (standard).
Go to directory where ufo binary is located (see directory tree).
Run
```
gdb ufo
```
from the commandline.
Now you are in the debug console of gdb

Run the game with

run +set vid_fullscreen 0 +set vid_grabmouse 0

or with

run +set vid_fullscreen 0 +set vid_grabmouse 0 +set developer 1

if you need the debug-messages from within the code.

After a crash you can toggle via 'Alt Tab to gdb console.
Type
```
bt full
```
to generate a backtrace and locate the problem.
Copy the output in the console and submit to the bugtracker.

Visit this site for a more in-depth gdb tutorial.

Generate core dumps

You can also generate core dumps from a running process - attach gdb to the process, type generate-core-file and detach again. Now you have the core file for later debugging.

Breakpoints

There are several commands to set breakpoints via gdb:

break function
break filename:line

To remove them type:

clear function
clear filename:line
delete

Remove all breakpoints

delete n

Remove the ith breakpoint

Type info breakpoints to get a list of all breakpoints

Inspect variables

You can use print i or the abbrevation p i to print the content of the variable i. You can also print structures by typing ptype structureName_t.

print accepts some format parameters:

o = octal
x = hex
d = decimal
u = unsigned decimal
t = binary
f = float
a = address
c = char

Use them via print /x i

Other useful commands

To find out where you currently are type the command: where
To print some source around the current location type: list
step Execute a single line in the program. If the current statement calls a function, the function is single stepped.
next Execute a single line in the program but treat function calls as a single line. This command is used to skip over function calls.
To log output to a file, start by entering

set logging file <filename>

when ready to start logging, enter

set logging on

usually you will want to enter bt full to generate & log the backtrace.

valgrind

Use valgrind to detect and fix memory bugs. There is a script that might help you in contrib/scripts/ named valgrind.sh. It will create a logfile in trunk of the output.

bugle

bugle can be used to trace OpenGL calls, hunt for unchecked OpenGL errors, take video shots, and do plenty of other OpenGL-related debugging.

e.g. to get a full trace of OpenGL calls:

BUGLE_CHAIN=trace LD_PRELOAD=/path/to/libbugle.so ufo +set gl_driver /path/to/libbugle.so

glibc backtrace

The glibc feature for producing stacktraces is used in UFO, too - to get meaningful output from the printed stackstrace you can use the addr2line command from the binutils package.

Useful gdb stuff

Hints

Use tab for command and variable completion
Ctrl C stops the program (use c or continue to continue the execution

Commands

help [command]: Prints information about the gdb command
list: Prints code from current active position (useful to set breakpoints)
break: Handle breakpoints. Type help breakpoints to gdb console to get information. Example: break 184 if (status == 0); b CL_ParticleRun2 will e.g. set a breakpoint to the function CL_ParticleRun2
watch: Sets a watchpoint. The main difference between watch and breakpoints is that a breakpoint was set for a specific line - and a watchpoint can get active on every line - it only needs it's condition to get true. Example: watch (varname > 1024)
inspect: Prints the value of a variable to gdb console (see print)
print: Prints a value of a variable to gdb console (see inspect). If variable is a pointer you can dereferencing it by typing print *[varname] - like in C. You can even assign a value to a var by typing print [varname] = [value]
ptype: Prints the type (typedef or struct) of the given variable name
bt: Prints the backtrace
c: Continue the game execution

Links

GDB documentation