src/debuginfo/intro.md - rust-lang/rustc-dev-guide - Git at Google

 # Debug Info

 Debug info is a collection of information generated by the compiler that allows debuggers to
 correctly interpret the state of a program while it is running. That includes things like mapping
 instruction addresses to lines of code in the source file, and type layout information so that
 bytes in memory can be read and displayed in a meaningful way.

 Debug info can be a slightly overloaded term, covering all the layers between Rust MIR, and the
 end-user seeing the output of their debugger onscreen. In brief, the stack from beginning to end is
 as follows:

 1. Rustc inspects the MIR and communicates the relevant source, symbol, and type information to LLVM
 2. LLVM translates this information into a target-specific debug info format during compilation
 3. A debugger reads and interprets the debug info, mapping source-lines and allowing the debugee's
 variables in memory to be located and read with the correct layout
 4. Built-in debugger formatting and styling is applied to variables
 5. User-defined scripts are run, formatting and styling the variables further
 6. The debugger frontend displays the variable to the user, possibly through the means of additional
 API layers (e.g. VSCode extension by way of the
 [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/))


 > NOTE: This subsection of the dev guide is perhaps more detailed than necessary. It aims to collect
 > a large amount of scattered information into one place and equip the reader with as firm a grasp of
 > the entire debug stack as possible.
 >
 > If you are only interested in working on the visualizer
 > scripts, the information in the [debugger-visualizers](./debugger-visualizers.md) and
 > [testing](./testing.md) will suffice. If you need to make changes to Rust's debug node generation,
 > please see [rust-codegen](./rust-codegen.md). All other sections are supplementary, but can be
 > vital to understanding some of the compromises the visualizers or codegen need to make. It can
 > also be valuable to know when a problem might be better solved in LLVM or the debugger itself.

 # DWARF

 The is the primary debug info format for `*-gnu` targets. It is typically bundled in with the
 binary, but it [can be generated as a separate file](https://gcc.gnu.org/wiki/DebugFission). The
 DWARF standard is available [here](https://dwarfstd.org/).

 > NOTE: To inspect DWARF debug info, [gimli](https://crates.io/crates/gimli) can be used
 > programatically. If you prefer a GUI, the author recommends [DWEX](https://github.com/sevaa/dwex)

 # PDB/CodeView

 The primary debug info format for `*-msvc` targets. PDB is a proprietary container format created by
 Microsoft that, unfortunately,
 [has multiple meanings](https://docs.rs/ms-pdb/0.1.10/ms_pdb/taster/enum.Flavor.html).
 We are concerned with ordinary PDB files, as Portable PDB is used mainly for .Net applications. PDB
 files are separate from the compiled binary and use the `.pdb` extension.

 PDB files contain CodeView objects, equivalent to DWARF's tags. CodeView, the debugger that
 consumed CodeView objects, was originally released in 1985. Its original intent was for C debugging,
 and was later extended to support Visual C++. There are still minor alterations to the format to
 support modern architectures and languages, but many of these changes are undocumented and/or
 sparsely used.

 It is important to keep this context in mind when working with CodeView objects. Due to its origins,
 the "feature-set" of these objects is very limited, and focused around the core features of C. It
 does not have many of the convenience or features of modern DWARF standards. A fair number of
 workarounds exist within the debug info stack to compensate for CodeView's shortcomings.

 Due to its proprietary nature, it is very difficult to find information about PDB and CodeView. Many
 of the sources were made at vastly different times and contain incomplete or somewhat contradictory
 information. As such this page will aim to collect as many sources as possible.

 * [CodeView 1.0 specification](./CodeView.pdf)
 * LLVM
     * [CodeView Overview](https://llvm.org/docs/SourceLevelDebugging.html#codeview-debug-info-format)
     * [PDB Overview and technical details](https://llvm.org/docs/PDB/index.html)
 * Microsoft
     * [microsoft-pdb](https://github.com/microsoft/microsoft-pdb) - A C/C++ implementation of a PDB
     reader. The implementation does not contain the full PDB or CodeView specification, but does
     contain enough information for other PDB consumers to be written. At time of writing (Nov 2025),
     this repo has been archived for several years.
     * [pdb-rs](https://github.com/microsoft/pdb-rs/) - A Rust-based PDB reader and writer based on
     other publicly-available information. Does not guarantee stability or spec compliance. Also
     contains `pdbtool`, which can dump PDB files (`cargo install pdbtool`)
     * [Debug Interface Access SDK](https://learn.microsoft.com/en-us/visualstudio/debugger/debug-interface-access/getting-started-debug-interface-access-sdk).
     While it does not document the PDB format directly, details can be gleaned from the interface
     itself.

 # Debuggers

 Rust supports 3 major debuggers: GDB, LLDB, and CDB. Each has its own set of requirements,
 limitations, and quirks. This unfortunately creates a large surface area to account for.

 > NOTE: CDB is a proprietary debugger created by Microsoft. The underlying engine also powers
 >WinDbg, KD, the Microsoft C/C++ extension for VSCode, and part of the Visual Studio Debugger. In
 >these docs, it will be referred to as CDB for consistency

 While GDB and LLDB do offer facilities to natively support Rust's value layout, this isn't
 completely necessary. Rust currently outputs debug info very similar to that of C++, allowing
 debuggers without Rust support to work with a slightly degraded experience. More detail will be
 included in later sections, but here is a quick reference for the capabilities of each debugger:

 | Debugger | Debug Info Format | Native Rust support | Expression Style | Visualizer Scripts |
 | --- | --- | --- | --- | --- |
 | GDB | DWARF | Full | Rust | Python |
 | LLDB | DWARF and PDB | Partial | C/C++ | Python |
 | CDB | PDB | None | C/C++ | Natvis |

 > IMPORTANT: CDB can be assumed to run only on Windows. No assumptions can be made about the OS
 >running GDB or LLDB.

 ## Unsupported

 Below, are several unsupported debuggers that are of particular note due to their potential impact
 in the future.

 * [Bugstalker](https://github.com/godzie44/BugStalker) is an x86-64 Linux debugger written in Rust,
 specifically to debug Rust programs. While promising, it is still in early development.
 * [RAD Debugger](https://github.com/EpicGamesExt/raddebugger) is a Windows-only GUI debugger. It has
 a custom debug info format that PDB is translated into. The project also includes a linker that can
 generate their new debug info format during the linking phase.
	# Debug Info

	Debug info is a collection of information generated by the compiler that allows debuggers to
	correctly interpret the state of a program while it is running. That includes things like mapping
	instruction addresses to lines of code in the source file, and type layout information so that
	bytes in memory can be read and displayed in a meaningful way.

	Debug info can be a slightly overloaded term, covering all the layers between Rust MIR, and the
	end-user seeing the output of their debugger onscreen. In brief, the stack from beginning to end is
	as follows:

	1. Rustc inspects the MIR and communicates the relevant source, symbol, and type information to LLVM
	2. LLVM translates this information into a target-specific debug info format during compilation
	3. A debugger reads and interprets the debug info, mapping source-lines and allowing the debugee's
	variables in memory to be located and read with the correct layout
	4. Built-in debugger formatting and styling is applied to variables
	5. User-defined scripts are run, formatting and styling the variables further
	6. The debugger frontend displays the variable to the user, possibly through the means of additional
	API layers (e.g. VSCode extension by way of the
	[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/))


	> NOTE: This subsection of the dev guide is perhaps more detailed than necessary. It aims to collect
	> a large amount of scattered information into one place and equip the reader with as firm a grasp of
	> the entire debug stack as possible.
	>
	> If you are only interested in working on the visualizer
	> scripts, the information in the [debugger-visualizers](./debugger-visualizers.md) and
	> [testing](./testing.md) will suffice. If you need to make changes to Rust's debug node generation,
	> please see [rust-codegen](./rust-codegen.md). All other sections are supplementary, but can be
	> vital to understanding some of the compromises the visualizers or codegen need to make. It can
	> also be valuable to know when a problem might be better solved in LLVM or the debugger itself.

	# DWARF

	The is the primary debug info format for `*-gnu` targets. It is typically bundled in with the
	binary, but it [can be generated as a separate file](https://gcc.gnu.org/wiki/DebugFission). The
	DWARF standard is available [here](https://dwarfstd.org/).

	> NOTE: To inspect DWARF debug info, [gimli](https://crates.io/crates/gimli) can be used
	> programatically. If you prefer a GUI, the author recommends [DWEX](https://github.com/sevaa/dwex)

	# PDB/CodeView

	The primary debug info format for `*-msvc` targets. PDB is a proprietary container format created by
	Microsoft that, unfortunately,
	[has multiple meanings](https://docs.rs/ms-pdb/0.1.10/ms_pdb/taster/enum.Flavor.html).
	We are concerned with ordinary PDB files, as Portable PDB is used mainly for .Net applications. PDB
	files are separate from the compiled binary and use the `.pdb` extension.

	PDB files contain CodeView objects, equivalent to DWARF's tags. CodeView, the debugger that
	consumed CodeView objects, was originally released in 1985. Its original intent was for C debugging,
	and was later extended to support Visual C++. There are still minor alterations to the format to
	support modern architectures and languages, but many of these changes are undocumented and/or
	sparsely used.

	It is important to keep this context in mind when working with CodeView objects. Due to its origins,
	the "feature-set" of these objects is very limited, and focused around the core features of C. It
	does not have many of the convenience or features of modern DWARF standards. A fair number of
	workarounds exist within the debug info stack to compensate for CodeView's shortcomings.

	Due to its proprietary nature, it is very difficult to find information about PDB and CodeView. Many
	of the sources were made at vastly different times and contain incomplete or somewhat contradictory
	information. As such this page will aim to collect as many sources as possible.

	* [CodeView 1.0 specification](./CodeView.pdf)
	* LLVM
	* [CodeView Overview](https://llvm.org/docs/SourceLevelDebugging.html#codeview-debug-info-format)
	* [PDB Overview and technical details](https://llvm.org/docs/PDB/index.html)
	* Microsoft
	* [microsoft-pdb](https://github.com/microsoft/microsoft-pdb) - A C/C++ implementation of a PDB
	reader. The implementation does not contain the full PDB or CodeView specification, but does
	contain enough information for other PDB consumers to be written. At time of writing (Nov 2025),
	this repo has been archived for several years.
	* [pdb-rs](https://github.com/microsoft/pdb-rs/) - A Rust-based PDB reader and writer based on
	other publicly-available information. Does not guarantee stability or spec compliance. Also
	contains `pdbtool`, which can dump PDB files (`cargo install pdbtool`)
	* [Debug Interface Access SDK](https://learn.microsoft.com/en-us/visualstudio/debugger/debug-interface-access/getting-started-debug-interface-access-sdk).
	While it does not document the PDB format directly, details can be gleaned from the interface
	itself.

	# Debuggers

	Rust supports 3 major debuggers: GDB, LLDB, and CDB. Each has its own set of requirements,
	limitations, and quirks. This unfortunately creates a large surface area to account for.

	> NOTE: CDB is a proprietary debugger created by Microsoft. The underlying engine also powers
	>WinDbg, KD, the Microsoft C/C++ extension for VSCode, and part of the Visual Studio Debugger. In
	>these docs, it will be referred to as CDB for consistency

	While GDB and LLDB do offer facilities to natively support Rust's value layout, this isn't
	completely necessary. Rust currently outputs debug info very similar to that of C++, allowing
	debuggers without Rust support to work with a slightly degraded experience. More detail will be
	included in later sections, but here is a quick reference for the capabilities of each debugger:

	\| Debugger \| Debug Info Format \| Native Rust support \| Expression Style \| Visualizer Scripts \|
	\| --- \| --- \| --- \| --- \| --- \|
	\| GDB \| DWARF \| Full \| Rust \| Python \|
	\| LLDB \| DWARF and PDB \| Partial \| C/C++ \| Python \|
	\| CDB \| PDB \| None \| C/C++ \| Natvis \|

	> IMPORTANT: CDB can be assumed to run only on Windows. No assumptions can be made about the OS
	>running GDB or LLDB.

	## Unsupported

	Below, are several unsupported debuggers that are of particular note due to their potential impact
	in the future.

	* [Bugstalker](https://github.com/godzie44/BugStalker) is an x86-64 Linux debugger written in Rust,
	specifically to debug Rust programs. While promising, it is still in early development.
	* [RAD Debugger](https://github.com/EpicGamesExt/raddebugger) is a Windows-only GUI debugger. It has
	a custom debug info format that PDB is translated into. The project also includes a linker that can
	generate their new debug info format during the linking phase.