Microsoft Visual C++ Debugger QuickStart

This document is intended as a quick start guide for using the Microsoft Visual C++ debugger. Once you get your source code to compile successfully in Microsoft Visual C++ (MSVC) you can use the debugger to examine the inner workings of the program as it executes. When your program does not give you the output you want, this is an excellent tool to help you determine what is wrong.

1. Print out this document.
   This will allow you to have these instructions available without having to flip between the web page and MSVC.



2. Make sure that the debugger is enabled.
   From the "Build" menu, choose "Set Active Configuration...". A dialog will pop up with one main field labelled as "Project configurations:" contiaining two or more items. Make sure that the highlighted one is of the form " - Win32 Debug" where is the name of the current project. If it is not, click on it to make it the highlighted one and click on the "Ok" button. If the active project configuration is not "Win32 Debug" you will not be able to run the debugger on your project.



3. Set one or more breakpoints.
   In the main editor window containing the source code you'd like to debug, select one or more valid statements that you'd like to stop at during execution. Immediately to the left of the main editor window is a light grey column. Right click in that column to bring up a menu and choose "Insert/Remove Breakpoint" from that menu to add a breakpoint. The breakpoint should show up as a dark red octagon (like a stop sign).



4. Compile your program.
   If you don't know how to do this, please refer to the MSVC QuickStart page.



5. Start the debugger.
   From the "Build" menu choose the "Start Debug" sub-menu and then "Go" from that sub-menu. The debugger should start executing your program in a new window. If you cannot see that window, it is likely hidden behind other windows on your screen.
   
   The Debugging Dialogs
   When you start the debugger, most of the MSVC windows change. The InfoViewer/FileView/ClassView and main editor window are replaced by the debugging window. The current line of code waiting to be executed next will be denoted by a yellow arror in the left margin. Below the main debugging window are two smaller tabbed windows. The leftmost one contains a pulldown menu named "Context" containing the name of the current function being executed. Below that is a listing of all the variables given the category ("Auto", "Locals", and "this"). On the right of that window is the Quickwatch window. Here you an drag variables or expressions when highlighted to produce their values in that frame.



6. Control the execution of the program.
   The debugger allows you to step through your code one line at a time, or to execute large sections of code stopping only at breakpoints. Breakpoints can be added/removed/enabled/disabled at any time during the debugging session and at any time in the main editing window while not debugging. The debugging commands are available from the "Debug" window during a debugging session. The program execution items are near the middle of the menu and are explained here:
   • Step Into: Step into the next statement if it contains a function call. You can even step into the source code of the various C++ libraries if their source code is available.
   • Step Over: Execute the next step of code and stop before executing the next statement. Remember that the next statement is the one pointed to by the little yellow arrow. If the next statement is a function call, the entire function will be executed unless it contains a breakpoint during its execution.
   • Step Out: Step out of the current function executing everything from the next line until the function returns to the calling function and stop at the next statement in the calling function. Do not step out of main.
   • Run to Cursor: Place the cursor at a later line in the execution of the program. This option executes every statement before the cursor and stops. This allows you to stop the program without having to set additional breakpoints.



7. Study the contents of the variables
   If the variable is an aggregate type, click on the '+' sign to the left of its name to display its contents. A value in red indicates that the value has just changed.



8. To study a particular variable or expression...
   You can hilight a variable or expression and drag it to the watch window where it will update automatically. Additionally, if the variable you'd like to look at is a non-aggregate type, you can hover over it's name in the debugging window and the value will pop up over the cursor much like tool tips.



9. 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 run past parts of the code that you are not investigating. If your program is crashing but you can't tell where exactly, use breakpoints to narrow your search.

S. Houchard 1/15/99