= Debug Tools =

Most times debugging without a debugger is really hard. In complex projects printing text and values of variables to the console is not very feasible for debugging anymore. Being able to handle a debugger like GDB or DDD makes (a coder's) life much easier.

== GDB ==
GDB is the standard (console based) unix debugger.
=== Basic usage ===
To simply run the program and wait for a segfault follow the instructions below.
 1. Go to the binary directory (bin) and run '''gdb orxonox'''
 2. Type '''run'''
 3. Wait for the segfault to occur ...
 * If you want to display the back trace ( list of function calls ) just type '''bt'''.
 * You can change the context (function to debug) by typing '''up''' and '''down'''.
 * If you want to display the value of a variable make sure you are in the right context (by using up and down) and type '''print varname'''
 * If you have an object pointer and you don't know the exact type of the class (e.g. pointer to WorldEntity which is actually a !SpaceShip) you can type '''x/wa addressOfObject''' and gdb will tell you what class type the object located in ''addressOfObject'' has by considering the vtables

=== Disabling mouse grabbing for in-game breakpoints ===
One problem with the method outlined above is that the game grabs the mouse 
when in-game, and does not release it when a breakpoint is reached, trapping you
in the locked game. One solution to this is to disable mouse grabbing in the
code. In the file src/libraries/core/input/InputManager.c, there is a function
LoadDevices. The part shown below grabs the mouse and keyboard:
{{{
if (CommandLineParser::getValue("keyboard_no_grab").get<bool>())
    paramList.insert(StringPair("x11_keyboard_grab", "false"));
else
    paramList.insert(StringPair("x11_keyboard_grab", "true"));
    paramList.insert(StringPair("x11_mouse_grab",  "true"));
    paramList.insert(StringPair("x11_mouse_hide", "true"));
}}}
Change all the values from "true" to "false" here to disable mouse/keyboard grabbing
altogether. This makes the game awkward to play, but when it runs into a breakpoint,
you can freely move your mouse focus out of the game and into the GDB window.

=== Setting Breakpoints ===
You can set breakpoints for
 - functions: '''break namespace::ClassName::functionName''' (e.g. ''break orxonox::SpaceShip::fire'')
 - codelines: '''break fileName.cc::''lineNr''''' (e.g. ''break !SpaceShip.cc:367'')
If the program hasn't yet been run in gdb, it will not have loaded all our libraries (e.g. libcore.so, libnetwork.so) and thus will not be able to set the breakpoint immediately, but ask you whether it should set it at run time. Make sure you entered the address/function correctly and type ''yes''.
 * To delete a breakpoint you can either use '''delete''' or '''clear'''. Type '''help''' / '''help ''gdb-function''''' for more information.
=== Setting Watchpoints ===
Sometimes it's useful to know when the value of a variable changes. 
 1. To make use of this feature set a breakpoint somewhere you can access the variable from (watchpoints for static variables can be set without doing this). 
 2. Run the program and wait for the breakpoint to get triggered
 3. Type '''watch ''varname'''''

=== Useful Commands ===
Below is a list of useful commands (type ''help command'' for more information)
|| x/wa || examine the memory at a certain address (e.g. determine class of an object) ||
|| print || print the value of a variable or function return value ||
|| break || set a breakpoint ||
|| watch || set a watchpoint ||
|| clear || delete all/specific breakpoints ||
|| delete || delete a breakpoint/watchpoint ||

== DDD ==
DDD is a simple graphical debugger based on GDB.

== Microsoft Visual Studio Debugger ==
Yet to come.