Preparing a Program to be Debugged

Before you can debug a program, you must put debugging information into the code. To produce an executable that has debugging information, you need to:

You can use different debugging options during development and production, as explained in the section ``Sample Scenario"'' at the end of this chapter.

Note: Most of the time you'll likely use the cc command to compile and link an application, not the Watcom compilers and linker. When we refer to command options in this manual, we're referring to the ones for wcc and wlink. The cc options that correspond to these are given below.

Compiler debugging options

The cc options are the same as those for wcc, except that the ``d'' is replaced with ``g''. For example, the cc option -g2 corresponds to the wcc option -d2.

The cc option -g is the same as -g2. For more information, see the description of the cc command in the Watcom Utilities Reference.

The debugging options for the C/C++ compilers (wcc, wpp, wcc386 and wpp386) are listed below; see the chapter C/C++ Compiler Options of the Watcom Compiler & Tools User's Guide for more details.

d1
generate debugging information for global symbols and line numbers.
d1+
generate debugging information for global symbols and line numbers, and typing information for local structs and arrays.
d2
generate the most debugging information that's normally needed, including global information, line numbers, types, and local variables.
d3
generate all debugging information generated by the d2 option. In addition, it generates information about all types defined in a compilation unit, regardless of whether or not they're used in that compilation unit.
Note: The d3 option creates very large objects and executable files. Don't use it unless you want to have access to types that have no variables associated with them.

Linker debugging options

The linker, wlink is the tool that puts together a complete program and sets up the debugging information for all the modules in the executable file. It's described in the chapter The Watcom Linker in the Compiler & Tools User's Guide. The DEBUG linker directive tells the linker when it should include debugging information from the modules. You can collect two levels of debugging information during the link:

DEBUG LINES
global names, source line numbers
DEBUG ALL
global names, source line numbers, local variables, typing information

The directives are position-dependent, so you must make sure that the DEBUG directive precedes the object files and libraries that require debugging information.

For instance, if the file mylink.lnk contains: 

#
# invoke with: wlink @mylink
#
file main
debug lines
file input, output
debug all
file process

then the files input and output have global names and source-line information available during debugging. All debugging information in the file process is available during debugging. No information is available for main except global names.

If you use a DEBUG directive anywhere, all files, including main, have global name information.

Note: If you use the cc command with a debugging option other than -g0, the linker directive DEBUG ALL is automatically specified.

Sample scenario

During development, use the d2 option of the compiler and use the debug all directive at the beginning of your linker command line or directive file. This ensures that maximum debugging information is available during your debugging session.

Change to the d1 option when you need to create a distribution version of your product. This is necessary since the d2 option disables most compiler optimizations, whereas d1 won't affect the quality of generated code.

During production, you can use the linker's symfile option to put the d1 debugging information into a separate file, usually with the extension sym. This lets you distribute a production-quality executable, yet still have the luxury of source-line debugging when bugs are reported. You can specify the sym filename on the command line when starting the debugger.