Using GDB in VSCode

What is GDB?

The GNU Project debugger, abbreviated GDB, is a debugging tool for a variety of languages including C++. GDB allows you to watch how a program runs step by step, pause the program when it reaches specific places, and examine the values of variables in memory when the program is stopped. This allows you to identify when your program starts behaving incorrectly and gain more information about what is going wrong.

GDB can be run on the command-line within a terminal window, but we are going to set it up so that we can run it within VSCode.

One-time installation

To begin, we should make sure that you have the Microsoft C++ support tools installed. Let's install this from a terminal window by typing: code --install-extension ms-vscode.cpptools

Setting up GDB in VSCode

For each new lab, you'll need to do the following steps:

1. After you have cloned your new lab, change directory into that lab directory.
2. Then start up VSCode by doing code . in that directory.
3. Open one of the files in that directory with a .cpp extension.
4. Now you are ready to set up a debugging profile. Click on the arrow-and-bug symbol on the left side panel. This will open a "Run and Debug" pane. In that pane, click on the hyperlink which says "create a launch.json file".
5. You will be presented with a list of profile types. You should select "C/C++ (gdb) Launch". The launch.json file is stored in a hidden directory named .vscode. Once you have created it, you should see one appear in your editor.
6. Press Ctrl+S to save the launch.json file. This will change the “Run and Debug” pane to display a series of smaller panes labeled things like “variables”, “watch”, and “call stack”.
7. This is a generic setup, and now we need to specify the details for your particular program.

• Find the text "name": "(gdb) Launch" in the configuration file and change it to "name": "CS35 Debug". Make sure when you do this not to delete the quotation marks the comma at the end of the line, as these are necessary for the file to match the format used by VSCode. When you save this file, the name of the selected debug profile in the upper left of the window will change as well.
• Find the text "program": "enter program name..." in the configuration file. You'll need to replace the right-hand side with the full path of where your executable program resides. You can use the command realpath executable_program_name in your terminal window to get the full path.
• Find the text "args": [] in the configuration file. You'll need to add any arguments that your executable program needs here. The arguments must each be quoted and separated by commas.

8. Make sure to press Ctrl+S to save the changes that you made to launch.json file.

Debugging your program in VSCode

Once you have configured your program to run in VSCode’s debugger, you can tell the debugger you’d like it to pause at a particular line by setting a breakpoint. Click the area just to the left of the line number where you want to pause the program; you’ll see a red dot appear and it will brighten when you click it.

Once you have set the breakpoint, you can run the program through the debugger by pressing the green arrow in the upper-left of the “Run and Debug” pane.

The line containing the breakpoint will be highlighted because GDB started running the program but stopped when it saw a breakpoint. Importantly, the highlighted line is the next line to run which has not run yet.

We control the program by pressing the buttons which are docked in the top middle of the screen.

• Step Over: The second button in that row – the dot with an arrow arcing over it – will be particularly useful. It instructs GDB to run the next line of code and then pause again.
• Step In: The third button in our control bar is a downward-pointing arrow over a dot, which denotes stepping into a function.
• Step Out: The fourth button on the control bar (an upward arrow pointing away from the dot), which denotes running the function we’re in to the end and going back to where it was called.

Summary

The three buttons – “Step Over”, “Step Into”, and “Step Out” – are the primary controls you use to run your program while debugging. As you do so, you can see the variables and call stack of your program change. You can use this tool to find bugs by running your program in a way that you know isn’t working correctly and stepping through its execution until you see something wrong: a variable with an incorrect value, a condition not running the way you expected, a loop never finishing, etc. Then, you can use the Variables view to inspect the situation and come to understand why your program behaved the way it did. This perspective can be invaluable in identifying the source of problematic program behavior and determining how to correct it.