gdb QuickStart

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. Load your source file.
   Since gdb does not show you your source file while debugging it, you should open it with an editor such as vi, emacs, or pico in another window. Leave it open, as you will be needing to refer to it throughout your degugging session.
   
   
3. Compile your project.
   If you make changes to your source file, you will need to recompile it before gdb can see those changes. Open another window and compile your project in it. Leave this window open, so that you don't have to quit gdb or the editor to recompile your program.
   
   
4. 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).
   
   
5. Debugging your program
   Before running your program in gdb, you should set some breakpoints. Without breakpoints gdb will run your program to completion without debugging it at all. 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 don't have to reset them unless you quit gdb and restart Sometimes you will want to stop your program without a breakpoint, for example if you are in an infinite loop. To do this, 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.
   
   
6. 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. Try to avoid "stepping into" functions that you didn't write -- usually there is no source code available. If you happen to do this by accident, set a breakpoint at the next statement in your code after the function and press "c" for continue - gdb will run until it reaches that breakpoint.
   
   Since all of gdb is all in one window, when you are debugging you cannot see the source code for your program. To see exactly where you are in 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.
   
   
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 t o 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.