CS 70

Using the VS Code debugger

VS Code has a built-in C++ debugger that lets run your program step-by-step, pause it at specific points, and inspect the values of variables while it's running. It's like being able to freeze time and examine everything that's happening inside your program.

  • LHS Cow speaking

    Though the VS Code debugger is powerful, you should typically prefer to start with simple print debugging, especially if you just need to see the value of a specific variable.

  • RHS Cow speaking

    The debugger is mainly useful for cases where you're confused about what the code is even doing, like what functions are being called and in what order.

  • Goat speaking

    Meh. I wrote the code, how could I possibly not know what functions are being called?

  • LHS Cow speaking

    In C++ it's not always obvious, especially when it comes to constructors that sometimes get called indirectly!

  • RHS Cow speaking

    And this will become more of a frequent problem as your code gets more and more complex through the semester...

All controls for the VS Code debugger can be found in the "Run and Debug" menu of the sidebar. That's the button that looks like a "Play" button with a small insect in the corner (you can also use the keyboard shortcut Ctrl-Shift-D, or Cmd-Shift-D on Mac).

First-time setup (per project)

The debugger needs to be configured for each individual project (i.e., each homework). If it's your first time using the debugger on a particular homework, the "Run and Debug" menu will be mostly empty. To set up the debugger, you should follow these steps:

  1. Click "create a launch.json file."
  2. In the dropdown list, select C++. This will create a new file launch.json.
  3. When you view that file, click the "Add Configuration..." button.
  4. Select "C/C++ (gdb) launch" from the dropdown list. This will generate a number of lines in launch.json.
  5. In the entry labeled "program":, remove the text enter program name, for example and replace a.out with the name of your executable.
  6. Save and close launch.json.

Once you have followed these directions, the "Run and Debug" menu should change appearance, and there should now be a green "Play" button in the top corner.

Using the debugger

The heart of the VS Code C++ debugger is the concept of breakpoints. A breakpoint is how you tell the debugger "I want you to pause when you get to this point in running the code.

To set a breakpoint, click to the left of a line number. That will create a red dot next to that line. Once you have one or more breakpoints set, you can run your program with the debugger by clicking the green "Play" button (of course, make sure you've already run make to generate your executable!). When you run your program with the debugger, it will pause execution just before the breakpoint line executes.

When the program is paused, you can use the panels on the "Run and Debug" tab to inspect the current values of variables. More powerfully, you can also tell the debugger to continue running the program step-by-step (i.e., one line at a time). This is an extremely powerful tool to help you understand what functions are being called and in what order! Control of program execution is provided by a new control panel that appears at the top of the screen when the program is paused. This control panel provides multiple options for stepping through the code line by line. From left to right, the buttons on this control panel do the following:

  • Continue: unpause execution until the next breakpoint or the end of the program.
  • Step Over: execute just this line, fully executing any function calls, and stopping before the next line.
  • Step Into: begin executing this line, stopping before the next line of execution even if it is in a function call.
  • Step Out: finish executing the current function and stop immediately after the function returns.
  • Restart: start executing from the beginning.
  • Stop: terminate execution without finishing the program.

The most common functions you'll use are "Step Over" and "Step Into". As a rough analogy, you can think of these as being similar to breadth-first and depth-first search, respectively. "Step Over" says to just go past whatever nested function calls might happen on this line and go to the next line of code that visually appears in the source file. "Step Into" instead goes "down the tree" by showing what actually happens next after the breakpoint, which could be a line of code in a different function, perhaps even in a different file! The latter can often help you recognize some function calls you didn't originally think were happening.

How the debugger actually works

Behind the scenes, the VS Code debugger is actually using a tool called gdb. gdb is an extremely old and time-tested debugger that runs entirely on the command line using keyboard shortcuts to send commands like "Step Over" or "Step Into". VS Code simply provides a more intuitive visual interface to gdb.

If you really want to learn more about gdb, we have an entire help page on it. But we certainly don't expect you to know the details of gdb, and in this class you should never need any of the advanced functionality beyond what VS Code exposes. On the other hand, if you take CS 105, you will become very familiar with operating gdb from the command line!

(When logged in, completion status appears here.)