Introduction

Welcome to the Watcom Debugger! This chapter includes the following topics:

What's the Watcom Debugger?

The Watcom Debugger is a powerful debugging tool that helps you analyze your programs and find out why they aren't behaving as you expect. It allows you to single-step through your code, set breakpoints based on complex conditions, modify variables and memory, expand structures and classes, and much more. Watcom provides debuggers for QNX as well as the following platforms:

New features

The latest version of the debugger contains many new features you should know about.

User interface

The debugger's user interface has been redesigned, incorporating powerful features such as context-sensitive menus, eliminating the need for command-oriented debugging.

Note: You can use the Watcom Debugger in character-mode as well as in Photon. The user interface is almost always the same in both modes. Any differences when running in Photon are identified throughout this manual by the following icon: Photon button

Reverse execution

The debugger keeps a history of your interactions that modify the state of the program you're debugging. This includes the effects of statements in your program that you trace. The size of this history is limited only by available memory. Undo and Redo allow you to step backward and forward through this history. These commands let you reverse the effects of tracing over simple statements in your program. You can also reverse any accidental interactions that affect your program's state.

This feature is described in the section on the ``Undo menu'' in the Controlling Program Execution chapter.

Replay

The debugger keeps a history of all interactions that affect the execution of your program, such as setting breakpoints and tracing. Replay allows you to restart the application and run the application back to a previous point. This is particularly useful when you accidentally trace over a call. This replay information may be saved to a file in order to resume a debugging session at a later date.

This feature is described in the section on the ``Replay window'' in the Controlling Program Execution chapter.

Stack unwinding

You can navigate up and down the program's call stack to see where the currently executing routine was called from. As you do this, all other windows in the debugger are updated automatically. Local variables in the calling routines are displayed, along with their current values.

This feature is described in the section on the ``Undo menu'' in the Controlling Program Execution chapter.

Simplified breakpoints

The debugger allows you to set breakpoints when code is executed or data is modified. These breakpoints may be conditional, based on an expression or a countdown. Simple breakpoints are created with a keystroke or single mouse click. More complex breakpoints are entered using a dialog. See the Breakpoints chapter for more information.

Context-Sensitive menus

Context-sensitive menus are present in each debugger window. To use them, select an item from the the screen using the right mouse button, or press the period (.) key. A menu containing a list of actions appropriate for that item is displayed. You can use this capability to perform actions, such as displaying the value of an expression that you've selected from the source window.

Buttons

The debugger contains small buttons that appear on the left side of some windows. These buttons are shortcuts for the most common operations. For example, you can set and clear a breakpoint by clicking on the button to the left of a source line.

Common menu items

The debugger's context-sensitive menus contain many useful items. Each of these items behaves differently, depending on what you've selected in the window. Here's a description of some of the commonly found menu items:

Inspect
displays the selected item. The debugger determines how to best display the selected item, based on its type. If you inspect a variable or an expression, the debugger opens a new window showing its value. If you inspect a function, the debugger positions the source code window at the function definition. If you inspect a hexadecimal address from the assembly window, a window showing memory at that address is opened, and so on. Experimenting with Inspect will help you learn to use the debugger effectively.
Modify
lets you change the selected item. You're normally prompted for a new value. For example, select the name of a variable from any window, and choose Modify to change its value.
New
adds another item to a list of items displayed in a window. For example, choosing New in the Break window lets you create a new breakpoint.
Delete
removes the selected item from the window. For example, you can use Delete to remove a variable from the Watches window.
Source
displays the source code associated with the selected item. The debugger repositions the source code window at the appropriate line. Selecting a module name and choosing Source displays the module's source code.
Assembly
positions the assembly code window at the code associated with the selected item.
Functions
shows a list of all functions associated with the selected item or window. For example, choose Functions in the source window to see a list of all functions defined in that module.
Watch
adds the selected variable or expression to the Watches window. This allows you to watch its value change as the program runs.
Note: This isn't a watchpoint, as execution doesn't stop when the variable changes. See the Examining and Modifying the Program State chapter for information about setting watchpoints.
Break
sets a breakpoint based on the selected item. If a variable is selected, the program stops when the variable is modified. If a function is selected, the program stops when the function is executed.
Globals
shows a list of global variables associated with the selected item.
Show
presents a cascaded menu that lets you show things related to the selected item. For example, you can use the Line command from the Show menu in the source code window to see the line number of the selected line.
Type
presents a cascaded menu that allows you to change the display type of the window or selected item.