Debug Information

By the time the backend has finished, the correspondence between what you wrote and what executes is gone. [[information-loss]] describes the deaths one by one: names die at register allocation, expression structure dies at lowering, types die at erasure or at codegen, scopes die when the stack frame is laid out. Debug information is the record kept as each of those dies, and it has four parts that answer four different questions.

The line table answers "which source position produced this address". It is a mapping from address ranges to (file, line, column), plus flags — most importantly is_stmt, marking addresses that are reasonable places to set a breakpoint, because after optimization most addresses are not. In DWARF this table is not stored as a table: it is encoded as a program for a small state machine, with opcodes that advance the address and the line by deltas, because the raw table would be enormous.

Variable locations answer "where is count right now". Not "where is count" — there is no such fact. A local variable lives in a register for one range of addresses, in a different register after a call clobbered the first, in a stack slot while it is spilled, and nowhere at all where the optimizer proved it unnecessary. DWARF records this as a *location list*: a set of address ranges, each with an expression saying where the value is. The expression is itself a small stack language (DW_OP_reg3, DW_OP_fbreg -24, DW_OP_breg6 -16; DW_OP_deref) capable of describing values that are computed rather than stored.

Type and scope descriptions answer "how do I interpret those bytes, and what is in scope here". A tree of entries — DWARF calls them DIEs, debugging information entries — describing every type, every struct member and its offset, every function, every lexical block and its address range, every inlined instance and where it came from. This is what lets a debugger print a struct field by name rather than as hex.

Unwind information answers "given this program counter and stack pointer, where is the caller". Modern code does not keep a frame pointer by default, so walking the stack requires a table describing, per address range, how to compute the canonical frame address and where each saved register was stored. On ELF this lives in .eh_frame and is used by both the debugger and the language runtime, since [[stack-unwinding]] for exceptions needs exactly the same information.

Two mainstream formats, and the split is by platform rather than by compiler. DWARF is used on Linux, the BSDs, macOS and most embedded targets, and is carried in sections of the object and executable files themselves. PDB — Program Database — is Microsoft's format, and it is always a separate file next to the binary, linked to it by a GUID and an age counter stamped into the executable.

The macOS arrangement is a third case worth knowing because it surprises people: Clang leaves DWARF in the individual .o files and the linker writes only a *debug map* into the executable, recording which object file and symbol each address came from. dsymutil then follows that map and gathers the DWARF into a .dSYM bundle. The consequence is practical: deleting your build directory can leave a binary whose debug information is unreachable, and shipping a build means shipping or archiving the .dSYM.

The size is the other thing to internalise. Debug information is routinely larger than the code it describes — several times larger is normal for C++ with heavy template instantiation, because every translation unit re-describes the same types. DWARF 5 added .debug_str_offsets and other deduplication; -gsplit-dwarf moves the bulk into separate .dwo files so the linker never sees it; -gz compresses the sections; and dwz deduplicates across a whole distribution. None of this affects the shipped instructions, which is exactly the point of the legality condition above.

Emitting debug information from an unoptimized frontend is straightforward. Keeping it accurate through a hundred optimization passes is the actual engineering problem, and it is why "debug info quality" is a long-running work item in every serious compiler rather than a solved feature.

Every transformation has an obligation. Instruction scheduling moves an instruction, so its source location moves with it — and now two source lines are interleaved. Inlining copies a body into a caller, so every copied instruction needs a location that records both where it is and which call it came from, which is what DW_TAG_inlined_subroutine and DWARF's inline call-site attributes exist for. Register allocation moves a value between registers and stack slots, so its location list acquires a new range at every move. Dead-code elimination deletes an instruction, and the debug metadata attached to it must be dropped rather than reattached to an unrelated neighbour — a mistake that shows up as a variable reporting a plausible, wrong value.

LLVM makes this concrete in a way worth knowing: debug locations are attached to instructions as metadata, and variable locations are tracked by dedicated intrinsic records that the passes must maintain like any other use. The historical bug class is exactly what you would expect — a pass that correctly transforms the code and forgets the metadata, producing a build that runs right and debugs wrong. Test suites for this compare debug output between optimization levels, because there is no other way to notice.

The reason to care as a user is that this determines what you can trust. When a debugger prints a value at -O2, it is reporting what the location list says, and the location list is only as good as the last pass that touched it. That is the mechanism behind [[debugging-optimized-code]], and it is why the honest answer to "can I trust this value" is "check whether the variable is live and whether the location list covers this address".

Debuggers are the obvious consumer and not the largest one. The same metadata is what makes a profiler show source lines, and a [[symbolication]] pipeline turn a crash address into a function and line, and a sanitizer report a stack trace, and a coverage tool attribute execution to source. Several language runtimes read the unwind tables directly to implement exceptions, which is why .eh_frame is present even in binaries built without -g — unwind information is not optional in the way the rest of DWARF is.

This is worth stating because it changes the cost calculation. Debug information is often described as "for debugging", implying it is only needed when you attach a debugger, and therefore droppable in production. In practice it is what makes production crash reports readable, what makes a continuous profiler show a line number instead of an address, and what a core dump from a customer is useless without. The correct arrangement is almost always to build with it and *split* it out of the shipped artifact rather than not to generate it — which is the whole argument of [[debug-vs-release]].