This document explains how to use gdb, a debugger for the unix environment. To use gdb, you first need compiled source code. If you have questions on how to do this in the unix environment, look at the quickstarts for compiling code or using make. Remember, when you use make you must use the -g flag for gdb to perform correctly.

1. Print out this document.
   This is so you can have the instructions next to you without trying to flip between the web page and the IDE.
   
   
2. Start gdb.
   Type "gdb [filename]" where [filename] is the name of the compiled file you wish to debug (the name you type to run your program).
   
   
3. Set the arguments.
   If your program runs with any command line arguments, you should input them with "set args". For example, if you would normally run your program "test" with the command line "test -paramater1 -parameter2" you would type "set args -parameter1 -parameter2".
   
   
4. Debugging your program
   To debug your program in gdb, you have to run it by typing "run". However, if you just type "run" gdb will run your program to completion without debugging it at all. If your program crashes, gdb will stop it and allow you to debug it. However, you will sometimes want to stop your program at other positions. To stop your program while it is running, type "(ctrl) + c" (hold down the ctrl key and press c). gdb will stop your program at whatever line it has just executed. From here you can examine variables and move through your program. To specify other places where gdb should stop, see the section on breakpoints below.
   
   
5. Controlling program execution Once your program has stopped, you can move through your code one step at a time, or execute multiple lines at once. To execute one line of code, type "step" or "s". If the line to be executed is a function call, gdb will step into that function and start executing its code one line at a time. If you want to execute the entire function with one keypress, type "next" or "n". This is equivalent to the "step over" command of most debuggers.
   
   If you want gdb to resume normal execution, type "continue" or "c". gdb will run until your program ends, your program crashes, or gdb encounters a breakpoint.
   
   Since all of gdb is all in one window, when you are debugging you cannot see the source code for your program. To view the source code, type "list" or "l". gdb will print out the source code for the lines around the current line to be executed. To view other lines, just type "list [linenumber]", and gdb will print out the 20 or so lines around that line. gdb remembers what lines you have seen, so if you type "list" again it will print out the next bunch of lines.
   
   
6. Setting breakpoints A breakpoint is like a stop sign in your code -- whenever gdb gets to a breakpoint it halts execution of your program and allows you to examine it. To set breakpoints, type "break [filename]:[linenumber]". For example, if you wanted to set a breakpoint at line 55 of main.cpp, you would type "break main.cpp:55".
   
   You can also set breakpoints on function names. To do this, just type "break [functionname]". gdb will stop your program just before that function is called. Breakpoints stay set when your program ends, so you do not have to reset them unless you quit gdb and restart it.
   
   
7. Working with breakpoints
   • To list current breakpoints: "info break"
   • To delete a breakpoint: "del [breakpointnumber]"
   • To temporarily disable a breakpoint: "dis [breakpointnumber]"
   • To enable a breakpoint: "en [breakpointnumber]"
   • To ignore a breakpoint until it has been crossed x times:"ignore [breakpointnumber] [x]"
   
   
8. Examining data When your program is stopped you can examine or set the value of any variable. To examine a variable, type "print [variablename]". To set the value of a variable, type "set [variablename]=[valuetoset]".
   
   
9. General Tips
   
   • gdb has very good help files. Type "help [commandname]" while in gdb.
   • gdb also keeps lots of information about your program while it's running. Type "info" to see this information while you're in gdb.
   • if you change and recompile your program in another window, you don't need to restart gdb. Just type "run" again, and gdb will notice the changes and load the new copy of your program.
   • pressing enter executes the last command again. This makes it easily to step through your program line by line.
   
   
10. Focus your inquiry.
    When you debug, you can't look at everything all of the time. Be clever and focus your inquiry based on the currently incorrect behavior of your program. If a variable is being output but has the wrong value, study that variable. If a function is not being called, step through the code, study the flow of control, figure out the conditions that must be met for the function to be called, and figure out why they are not being met. If your program seems to enter an infinite loop, study the exit conditions for that loop and figure out why they are not being met. Use breakpoints to skip past parts of the code that you are not investigating.