Debugging information

This article needs more citations. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed. Find sources: "Debugging information" – news · newspapers · books · scholar · JSTOR (December 2013) (Learn how and when to remove this message)

Debugging information is information that describes a correspondence of elements in the source code, such as the names of variables and routines, to entities in the object code, which is found in an object file, such as a shared library or an executable. This kind of information allows a symbolic debugger to provide more a debugging experience that corresponds more closely to the source code.

The debugging information may be compiled together with the module's binary file, or distributed in a separate file, or simply discarded during the compilation and/or linking.

Because historically such information was associated with the symbol table (which originally was for the translation from exported identifier names to locations in the object file), they also commonly known as debug symbols'. However, most debug information today exists outside of the symbol table, making this largely a misnomer.

This information can be helpful while trying to investigate and fix a crashing application or any other fault.^[1] They are also used to provide a view of the program's structure when reverse engineering.

Debug symbols can be divided into several levels:

1. Information usually provided by the symbol table, a translation from names to addresses. For dynamic libraries, the symbol table most include the locations functions and global variables that it expects other programs to use, as otherwise these "exports" would simply be unavailable.
2. Information necessary for other features such as type introspection (incl. run-time type information) and reflection.
3. Optional additional information, which may include:
   1. Source code file in which the symbol occurs, as well as the line number at which it is defined.
   2. Data type and size of a symbol.
   3. For custom types such as structs and classes, their names, methods, and members.
   4. Local symbols, usually a mapping from a variable name to a register or a memory location, and their lifetime and scope (block scope or global scope).
   5. Information on exception frames.
   6. The source code itself (found in DWARF 5 and ADATA of § OS/390 et al).

Information of type (3) may be stored in the symbol table of an object file (including executable file or shared library), or may be in a separate file. The other types are required for the functioning of non-debugging features and typically need to stay with the object file.

Debugging information can take up quite a bit of space, especially the filenames and line numbers. Thus, binaries with debugging information can become quite large, often several times the stripped (has its symbols and other debugging information removed) file size.^[2] To avoid this extra size, most operating system distributions ship binaries that are stripped, i.e. from which all of the debugging symbols (type (3)) have been removed. This is accomplished, for example, with the strip command in Unix. If the debugging information is in separate files, those files are usually not shipped with the distribution and fetched only when needed.

The strip command only deletes information of types (1) and (3) – the former not always completely as it may also be told to preserve symbols necessary for relocation processing (--strip-unneeded), often found in a dynamic library. Changing the compiler settings may be required for more complete removal: for example, symbol visibility directly affects the size of the symbol table (1), and whether RTTI is enabled on C++ determines whether (2) is produced.^[3]

stabs was an early format for debugging symbols on Unix-like systems. It worked by encoding extra information into the symbol table as specially-formatted strings and is broadly applicable to many object file formats.

The newer DWARF format, for which formal specifications exist, has largely supplanted it. The specification allows any compatible compiler or assembler to create debug symbols in a standardized format, and for any debugger, such as the GNU Debugger (GDB), to gain access and display these symbols. DWARF is usable on any object format with a concept of named sections.

This section needs expansion. You can help by adding missing information. (July 2024)

The compilers for the IBM mainframe line descended from the System/360 have a TEST option that causes the compiler to include debugging information^[4][5][6] in the object file. Similarly, the Binder and linkage editors have a TEST option that causes the debug information to be retained^[7] in the load module. Various debug tools, e.g., OS/360 TESTRAN, TSO TEST, have the ability to use the embedded symbol definitions.

The IBM High Level Assembler (HLASM) supports Generalized Object File Format (GOFF), which includes embedded ADATA.

Windows PE/COFF can use an embedded CodeView format, though in production programs this information is usually extracted to a separate PDB file (see below). PE/COFF can also use a legacy COFF debug info format.^[8]

On GNU toolchains, DWARF is used in PE/COFF. This information can, too, be extracted to a PDB file using cv2pdb.

• Relocatable Object Module Format (OMF) for Intel x86, the .OBJ files on DOS: debug information encoded as "comments" (obsolete)^[9]
• IEEE-695: outdated format used on the Z80. Uses "comment" fields.^[10][11]
• COFF: Once one of the successors to OMF, has a combination of symbol tables (for identifiers) and annotations in the text segment (for more advanced info).

This section needs expansion. You can help by adding missing information. (July 2024)

The IBM High Level Assembler (HLASM) and other compilers running on, e.g., z/OS, have an ADATA option that produces an Associated data (ADATA) file^[12] containing more information than that produced by the old TEST option. In particular, the ADATA file includes lines of source code and their metadata.

Microsoft compilers generate a program database (PDB) file containing debug symbols. Some companies ship the PDB on their CD/DVD to enable troubleshooting and other companies (like Microsoft, and the Mozilla Corporation) allow downloading debug symbols from the Internet. The WinDbg debugger and the Visual Studio IDE can be configured to automatically download debug symbols for Windows dynamic-link libraries (DLLs) on demand. The PDB debug symbols that Microsoft distributes include only public functions, global variables and their data types. The Mozilla Corporation has similar infrastructure but distributes full debug information.

There are two branches of the PDB file format for PE/COFF (exe, dll). The closed format is used for files that contain usual machine code. The "open" format is used for files that contain .NET code.

DWARF may be emitted or extract into a code-less object file that serves as a separate file for debug information. On Linux systems a lookup service is provided by debuginfod.

On Apple platforms, debug symbols are optionally emitted during the build process as dSYM files, which are bundles that contain a Mach-O file with no code but with debug symbols. Apple uses the term "symbolicate" to refer to the replacement of addresses in diagnostic files with human readable values.^[13]

Minification of source code makes it unreadable. A source map, which includes a mapping between the minified entities and the original entities in source code, serves the function of debugging information.

Bytecode formats such as Java and .NET bytecodes can have different amounts of debugging information as well.^[14]

Symbolic debuggers have existed since the mainframe era, almost since the first introduction of suitable computer displays on which to display the symbolic debugging information (and even earlier with symbolic dumps on paper). They were not restricted to high level compiled languages and were available also for assembly language programs. For the IBM/360, these produced object code (on request) that included "SYM cards". These were usually ignored by the program loader but were useful to a symbolic debugger as they were kept on the same program library as the executable logic code.

• CA/EZTEST
• Debugging data format
• Microsoft SYMDEB

• http://referencesource.microsoft.com/ Microsoft Reference Source Server
• https://firefox-source-docs.mozilla.org/taskcluster/using-the-mozilla-source-server.html Mozilla Source Server
• http://www.symbolsource.org/ .NET libraries at SymbolSource
• Eager, Michael J. (April 2012) [2006]. "Introduction to the DWARF Debugging Format" (PDF). Archived (PDF) from the original on 2018-12-23. Retrieved 2014-11-12. (NB. Concentrates on DWARF, but also discusses debugging formats in general, with an overview of all the major formats.)