jesnor / RustNatvis

Generates Natvis for debug visualization of Rust code

Rust Natvis

Generates a more informative summary for enum's when debugging Rust code in Windows. This requires using a debugger that uses Natvis files, for example WinDbg (doesn't work with LLDB for example).

Example Output

Values of this enum:

enum En {
    A(i32),
    B(String),
    C(Point<i32>),
    D { x: i32, y: i32 },
    E((i32, i32)),
    F(i32, i32, bool, String, f32),
}

that was previously shown like this in the variables debug window (note that you could still expand them to show children):

a: A
b: B
c: C
d: D
e: E
f: F

is now shown like this with children inlined:

a: A (10)
b: B ("Hello")
c: C ({x=1, y=2 })
d: D {x=1, y=2 }
e: E ((1, 2))
f: F (1, 2, false, "Hello", ...)

A maximum of 4 elements of an enum tuple is shown inline, but this can be changed in the Rust code if you prefer more.

How to Use

Copy the intrinsic.natvis file to the \Users\<user name>\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\etc\ folder, replacing the original file, and then re-build your project in debug mode.

In VS Code

1. Install the MS C/C++ extension in VS Code.
2. Change the setting rust-analyzer.debug.engine to ms-vscode.cpptools.
3. Optionally copy the launch.json to the .vscode\ folder in your Rust project, modify it to fit your project and then launch the VS Code debugger.

Why not use LLDB on Windows?

When you use the default *pc-windows-msvc Rust Windows target, debug information will be written into PDB files (the .pdb files stored next to the debug executables). This is the native debug format for MS Windows debuggers (WinDbg, Visual Studio etc.). LLDB only has limited supports for reading this format. For example, if you print Rust enum values in any LLDB debugger in Windows (CodeLLDB in VS Code, JetBrain's RustRover etc.), it will show all enum variant values as children together with the tag child. There is simply not enough information to determine which enum variant is actually used, and the tag value can be really hard to decode. The PDB file on the other hand contains all the required information, even for complicated niche encodings (generated by this compiler source code), so that's why the Natvis pretty printers can provide better display of enum values.

For comparison, this how a expanded value of En::F looks like in LLDB using the enum example above:

f: {...}
  [raw]:
    variant0: {...}
    variant1: {...}
    variant2: {...}
    variant3: {...}
    variant4: {...}
    variant5: {...}
    tag: '\x05'

Not very useful.