All program symbols, including locals, globals, and publicsAfter you compile and link your program into a running executable file, you can begin debugging with CodeView. To take full advantage of CodeView, however, you must compile and link with the options that generate CodeView Symbolic Debugging Information. This book refers to this information as “CodeView information,” “debugging information,” or “symbolic information.”
The CodeView information tells CodeView about:
All program symbols, including locals, globals, and publics
Data types
Line numbers
Segments
Modules
Without this information, you cannot refer to any source-level names, and you can view the program only in Assembly display mode. When CodeView loads a module that does not contain symbolic information, CodeView starts in Assembly mode and displays the message:
CV0101 Warning: No symbolic information for PROGRAM.EXE
You get this message if you try to debug an executable file that you did not compile and link with CodeView options, if you use a compiler that does not generate CodeView information, or if you link your program with an old version of the linker. If you retain an old linker version and it is first in your path, the proper information may not be generated for CodeView.
You can specify CodeView compiler and linker options from the command line, in a makefile, or from within the Microsoft Programmer's Workbench (PWB). To compile and link your program with CodeView options from PWB, choose Build Options from the Options menu, and turn on Use Debug Options. By default, all project templates enable the generation of CodeView information for debug builds.
Summary: Compile with /Zi for full CodeView information.
You can specify CodeView options when you compile a source file of a program you want to debug. Specify the /Zi option on the command line or in a makefile to instruct the compiler to include line-number and complete symbolic information in the object file.
Summary: Compile with /Zd to save space.
Symbolic information takes up a large amount of space in the executable file and in memory while debugging. If you do not need full symbolic information in some modules, compile those modules with the /Zd option. The /Zd option specifies that only line numbers and public symbols are included in the object file. In such modules you can view the source file and examine and modify global variables, but type information and names with local scope are not available.
You can also limit the amount of debugging information included in your program by using precompiled headers that do not include debugging information. For more information on generating and using precompiled headers, see Chapter 2 of the Programming Techniques manual.
For modules that are compiled with the /Zd option, all names in that module are displayed and can only be referred to using their “decorated name.” The decorated name is the form of the name in the object code produced by the compiler. With full debugging information, CodeView can translate between the source form of the name and the decorated name.
Name decoration encodes additional information into a symbol's name by adding prefixes and suffixes. For example, the C compiler prefixes the names of functions that use the C calling convention with an underscore. You often see decorated names for library routines in disassembly or output from the Examine Symbols (X) command. For more information on decorated names, see “Symbol Formats” on page 408 and Appendix B.
Summary: Disable optimizations with /Od.
All Microsoft high-level language compilers are optimizing compilers that may rearrange and remove source code. As a result, optimizations destroy the correspondence between source lines and generated machine code, which can make debugging especially difficult. While you are debugging, you should disable optimizations with the /Od compiler option. When you finish debugging, you can compile a final version of your program with full optimizations.
Note:
The /Od option does not pertain to MASM.
When you are using Microsoft C/C++, you must use the Microsoft Segmented Executable Linker (LINK) version 5.30 or later to generate an executable file with CodeView information. If you include debugging options when you compile, the compiler automatically invokes the linker with the appropriate options. In turn, LINK runs the CVPACK utility, which compresses the symbolic information.
When compiling, you can specify the compile-only (/c) option to disable running LINK. To include debugging information when you link the object modules separately, specify the LINK /CO option. LINK automatically runs CVPACK when you specify /CO.
If you link with the /EXEPACK option, you must execute the program's startup code before setting breakpoints in the program. If you set breakpoints in a packed executable file before the startup code has executed, CodeView behavior is unpredictable.
An executable file that includes debugging information can be executed from the command line like any other program. However, to minimize the size of the final version of the program, compile and link without the CodeView options.
The following command sequence assembles and links two files:
ML /C /Zi MOD1
ML /C /Zd MOD2
LINK /CO MOD1 MOD2
This example produces the object file MOD1.OBJ, which contains line-number and complete symbolic information, and the object file MOD2.OBJ, containing only line-number and public-symbol information. The object files are then linked to produce a smaller file than the file that is produced when both modules are assembled with the /Zi option.
The following commands produce a mixed-language executable file:
CL /Zi PROG.CPP
CL /Zi /Od /c /AL SUB1.C
ML /C /Zi /MX SUB2.ASM
LINK /CO PROG SUB1 SUB2
You can use CodeView to trace through C, C++, and MASM source files in the same session.