Appendix D. Debug Symbols

Another topic that comes up all the time (and is the duty of the build team) is creating and maintaining symbols for various builds. Since this topic does not really fit into any of the chapters in this book, I thought I would include some notes and some of the best practices in this appendix.

A great place to start on debugging and symbols is at http://www.microsoft.com/whdc/devtools/debugging/debugstart.mspx.

The best book concerning these areas is written by, arguably, the single best source on debugging and symbols, John Robbins: Debugging Applications for Microsoft .NET and Microsoft Windows.

I will give a brief overview of what symbols are, give an example of what Windows does to build them, and a short pointer on setting up a symbol server that the build team would own.

Symbol files (or symbols) are required to do both kernel and usermode debugging in Windows or Windows applications. Symbols make debugging possible by providing data, such as variable and function names, for a loaded executable file.

The linker (and the compiler [csc.exe] in .NET) in C++ or C produces symbols when a program is built and puts them in a separate file with a .PDB (Program Database) extension. The symbols in a PDB file are called CodeView symbols. The linker creates a full PDB file that contains some private information which, in most cases, should not be shipped externally to customers. The Windows build process strips this private information out of the PDB file and ships the stripped PDB to customers. You can do this by using the /PDBSTRIPPED linker switch. In fact, the stripped PDB file will be generated alongside the full PDB file so that you can use this with your release builds. The following is a brief description of the information contained in full PDBs and stripped PDBs.

Full PDBs:

• Contain all the information you would ever want about an image: global variables, function names\addresses, frame pointer omission (FPO) data, line numbers (to match up with the source), and local variables.

• Required for internal use only.

Stripped PDBs:

• Contain the minimum amount of information necessary to get stack traces: function names and addresses, and FPO data. Getting valid stack traces is very important. It provides product support and provides customers a means for obtaining basic information about where bugs are occurring in the source code.

• Are shipped on the Customer Support Diagnostics CD and are available to every customer by default in Windows.