Debugging your programs

Debugging basics

To debug your program you must have debug information added to your program. This information is used by the debugger so that it may show you your source code, and allow you to view and alter program data structures. Since generating a program executable is a two step process, compiling and linking, including debug information is also a two step process. The environment can eliminate one of these steps for you however.

The first step is to have the compiler generate debug information about your source code. There are two types of debug information that the compiler generates. Source file information, and symbolic information about your types and variables. These options can be set separately. To include source file information use the Line Numbers debug option. To include symbolic debug information use the Debug Symbols option. Generally you will always turn both options on or off together.

Note: The project option Recompile for debug, can automatically turn these options on for you when you issue a Debug command.

The second step is to have the linker include the debug information the compiler generated in your final executable file. If the linker does not include debug information any compiler generated debug information will be ignored. To have the linker include debug information in the executable file use the linker Include debug info option. This step the environment can do automatically for you so you do not have to worry about setting a linker option. When you give the Debug command to the environment it will always include debug information in an executable file regardless of the linker option currently set.

Finally when you want to debug your program execute the Debug command from the build menu. The environment will always compile any files as necessary, link your program if necessary and then execute your program under the debugger every time you issue a Debug command.

Program Stack size

For those targets which allow you to specify a stack size for a program, the stack size given the program is specified in one of two ways. The default stack size or a specific stack size for a given program module. The default stack size is specified in the Project Options dialog. The specific stack size for a program module is specified in the Module menu. If a program module has a stack size of zero, the default, then the default stack size is used.

Make debuggable option

Set the Make debuggable compiler option to Yes to turn off certain optimizations that can cause confusion when you are trying to debug a program.  You can leave this option turned on all the time, because it functions only when you have set the Debug symbols option to Yes as well.  If the Debug symbols option is set to No, the compiler fully optimizes your code, regardless of the Make debuggable setting.

Debug option strategies

There are two basic strategies to including debug information for debugging.

• Set the options on as a global option, thus compiling all files with debug information. This affects the quality of generated code from the compiler.
• Set the options on for only those files you want to view in the debugger.

For the second option we would suggest the following strategy.

• Set Line number information, Yes, as a global option.
• Set Local symbol information, Yes, only for those modules you suspect could contain problems and you want to debug.

This allows you to step through all locations in your program, but view variables only in the questionable code. Compiler code generation is not affected except in those modules with symbolic debug information. Line number information does not significantly bloat the size of object files generated by the compiler.

Program environment

If your program takes command line parameters you can specify those in the Build menu Program parameters menu item.

Default directory

Many times your program will need data files and other necessary information since it is part of a complete system. Usually your development files and the system you are developing will be placed in different directories just to keep, things separated and organized. The Build menu Execution path menu item allows you to specify a different default path to be used when executing or debugging for your program.

DOS debugger differences

The debuggers supplied for 32-bit DOS extended and 16-bit real mode DOS are DOS based text mode debuggers and do not have the exact same user interface or all of the features of the graphical debugger. This section describes the differences and unless mentioned, all documented features are the same.

The graphical Win32 based debugger cannot debug DOS based programs due to bugs(Windows NT/2000/XP) or limitations(Windows 95/98/Me) of the host operating system.

The DOS debuggers operate in full screen text mode. Windows do not overlap as the debugger always tiles the displayed windows and adjusts the sizes of the windows automatically to fill the entire text screen.

The DOS debuggers only have a right mouse click context sensitive menu in the source display window.

The DOS debuggers highlight the currently executing line of code, but they do not use colors to highlight breakpoints. Instead breakpoints are indicated on the left side of the source window. The breakpoint indication will overlap the line number in source display mode. This indication has the following format

[B|D][E]-breakNumber

Examples:

The DOS debuggers only support a fixed maximum number of breakpoints.

You can have only one data window visible in the DOS debuggers. The data display in the window is slightly different. The data window does not support the expansion and contraction of structured items as the GUI debugger does. Instead of expanding the item within the same window, the DOS debuggers expand the data item into a new window that is overlapped on top of the previous window. There can be a maximum of six data windows. You can close the data window by pressing the Esc key or using the mouse. The previous data window, if any, will then again become active. You can expand a data item within the same data window, by pressing Ctrl-Enter, but using this method you cannot reverse the expansion.

The watch window does not support data item expansion or contraction, and the watch window only supports a fixed maximum number of watch items.

The File Menu

These debuggers do not have the Open and Attach menu items. The only way to start a debug session with the DOS debuggers is to give the program name on the command line to the debugger.

The DOS debuggers have a menu item, DOS command, that lets you execute any DOS program or batch file while debugging your program.

The View Menu

The DOS debuggers have an additional menu item, Output, that lets you view the output of your program. This is necessary because the debugger operates full screen.

The Locals window menu item is not supported in these debuggers.

Since DOS is not a multi-tasking operating system the Thread Window menu item is not supported.

The Search Menu

There are no differences in this menu.

The Run menu

The stop running menu item is not supported, however when your application is running pressing Ctrl+Break may return control back to the debugger. This cannot be guaranteed.

Since DOS is not a multi-tasking operating system the Thread state menu item is not supported.

The terminate program menu item is not supported. When you exit the debugger your program is terminated if it is still running.

The Debug menu

The DOS debuggers do not have an Add to watch menu item.

The DOS debuggers do not have an options dialog, instead the options are listed in the debug menu as individual menu items.

Screen Modes

The DOS debuggers can operate in different screen modes. These can be accessed via command line switches.

/DISPLAY:[LOW | MEDIUM | HIGH | MONO]