From 948426bc0a81990f3ffbbe17873ca1ac83d0bfd3 Mon Sep 17 00:00:00 2001 From: Ridwan Abdilahi Date: Fri, 22 Jul 2022 10:22:13 -0700 Subject: [PATCH 1/3] Add documentation about Microsoft provided debuggers and CodeView/PDB in the `Debugging support in the Rust compiler` page. --- src/debugging-support-in-rustc.md | 36 ++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/src/debugging-support-in-rustc.md b/src/debugging-support-in-rustc.md index 3241294c8..b75831173 100644 --- a/src/debugging-support-in-rustc.md +++ b/src/debugging-support-in-rustc.md @@ -3,7 +3,7 @@ This document explains the state of debugging tools support in the Rust compiler (rustc). -It gives an overview of GDB, LLDB, +It gives an overview of GDB, LLDB, WinDbg/CDB, as well as infrastructure around Rust compiler to debug Rust code. If you want to learn how to debug the Rust compiler itself, see [Debugging the Compiler]. @@ -42,6 +42,15 @@ Debugging Information Entry (DIE) which stores the information as "tags" to deno variables etc., e.g., `DW_TAG_variable`, `DW_TAG_pointer_type`, `DW_TAG_subprogram` etc. You can also invent your own tags and attributes. +### CodeView/PDB + +[PDB] (Program Database) is a file format created by Microsoft that contains debug information. +PDBs can be consumed by debuggers such as WinDbg/CDB and other tools to display debug information. +A PDB contains multiple streams that describe debug information about a specific binary such +as types, symbols, and source files used to compile the given binary. CodeView is another +format which defines the structure of [symbol records] and [type records] that appear within +PDB streams. + ## Supported debuggers ### GDB @@ -104,6 +113,27 @@ LLDB has Rust-like value and type output. * LLDB has a plugin architecture but that does not work for language support. * GDB generally works better on Linux. +### WinDbg/CDB + +Microsoft provides [Windows Debugging Tools] such as the Windows Debugger (WinDbg) and +the Console Debgugger (CDB) which both support debugging programs written in Rust. These +debuggers parse the debug info for a binary from the `PDB`, if available, to construct a +visualization to serve up in the debugger. + +#### Natvis + +Both WinDbg and CDB support defining and viewing custom visualizations for any given type +within the debugger using the Natvis framework. The Rust compiler defines a set of Natvis +files that define custom visualizations for a subset of types in the standard libraries such +as, `std, core and alloc`. These Natvis files are embedded into `PDBs` generated by the +`*-pc-windows-msvc` target triples to automatically enable these custom visualizations when +debugging. This default can be overridden by setting the `strip` rustc flag to either `debuginfo` +or `symbols`. + +Rust has support for embedding Natvis files for crates outside of the standard libraries by +using the `#[debugger_visualizer]` attribute. For more details on how to embed debugger visualizers +please refer to the `#[debugger_visualizer]` attribute in [the unstable book](https://doc.rust-lang.org/unstable-book/). + ## DWARF and `rustc` [DWARF] is the standard way compilers generate debugging information that debuggers read. @@ -316,3 +346,7 @@ but may have to add some mode to let the compiler understand some extensions. [Apple developer documentation for System Integrity Protection]: https://developer.apple.com/library/archive/releasenotes/MacOSX/WhatsNewInOSX/Articles/MacOSX10_11.html#//apple_ref/doc/uid/TP40016227-SW11 [https://github.com/rust-lang/lldb]: https://github.com/rust-lang/lldb [https://github.com/rust-lang/llvm-project]: https://github.com/rust-lang/llvm-project +[PDB]: https://llvm.org/docs/PDB/index.html +[symbol records]: https://llvm.org/docs/PDB/CodeViewSymbols.html +[type records]: https://llvm.org/docs/PDB/CodeViewTypes.html +[Windows Debugging Tools]: https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/ \ No newline at end of file From 20068052d1d06ae8cfd99253472d564d55b8971c Mon Sep 17 00:00:00 2001 From: ridwanabdillahi <91507758+ridwanabdillahi@users.noreply.github.com> Date: Fri, 22 Jul 2022 15:15:55 -0700 Subject: [PATCH 2/3] Update src/debugging-support-in-rustc.md Cleanup typos. Co-authored-by: Yuki Okushi --- src/debugging-support-in-rustc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/debugging-support-in-rustc.md b/src/debugging-support-in-rustc.md index b75831173..20ec05c5e 100644 --- a/src/debugging-support-in-rustc.md +++ b/src/debugging-support-in-rustc.md @@ -116,7 +116,7 @@ LLDB has Rust-like value and type output. ### WinDbg/CDB Microsoft provides [Windows Debugging Tools] such as the Windows Debugger (WinDbg) and -the Console Debgugger (CDB) which both support debugging programs written in Rust. These +the Console Debugger (CDB) which both support debugging programs written in Rust. These debuggers parse the debug info for a binary from the `PDB`, if available, to construct a visualization to serve up in the debugger. From 99c6b805af93dbf0c15171da4b9d442af72eb77e Mon Sep 17 00:00:00 2001 From: Ridwan Abdilahi Date: Fri, 22 Jul 2022 15:17:45 -0700 Subject: [PATCH 3/3] Add a direct link to the `debugger_visualizer` page in the unstable book. --- src/debugging-support-in-rustc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/debugging-support-in-rustc.md b/src/debugging-support-in-rustc.md index 20ec05c5e..d0c258927 100644 --- a/src/debugging-support-in-rustc.md +++ b/src/debugging-support-in-rustc.md @@ -132,7 +132,7 @@ or `symbols`. Rust has support for embedding Natvis files for crates outside of the standard libraries by using the `#[debugger_visualizer]` attribute. For more details on how to embed debugger visualizers -please refer to the `#[debugger_visualizer]` attribute in [the unstable book](https://doc.rust-lang.org/unstable-book/). +please refer to the `#[debugger_visualizer]` attribute in [the unstable book](https://doc.rust-lang.org/unstable-book/language-features/debugger-visualizer.html). ## DWARF and `rustc`