natvis-pdbs

A metabuild / build.rs compatible crate to embed .natvis debug visualizer files into your executable's .pdbs, for ease of debugging.

Limitations

• Natvis and PDBs being Microsoft technologies, this won't have any effect unless using MSVC-based build toolchains.

• While crate-type=rlib crates can contain .natvis files, they should not directly rely on natvis-pdbs. (Due to the way crates are isolated for build, natvis-pdbs will only work when used for the final .exe, .lib, or .dll crate at this time.)

• This abuses the %LINK% environment variable since there's currently no stable build.rs-friendly arbitrary link-args.

Quick Start

To author crates containing .natvis files (example)

Place one or more natvis files inside any of:

• the root folder of your crate.
• inside the {root}\src folder.
• inside a {root}\debug_metadata folder.

Any other locations (including subdirectories of the above) will not (currently) be searched. See Recommended Reading bellow for more information about the .natvis format.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
  <Type Name="example_crate_with_natvis::Flags">
      <Expand>
        <Item Name="bits"   ExcludeView="sparse">bits,bb</Item>
        <Item Name="A (1)"  ExcludeView="sparse">(bits &amp; (1 &lt;&lt; 0)) != 0</Item>
        <Item Name="B (2)"  ExcludeView="sparse">(bits &amp; (1 &lt;&lt; 1)) != 0</Item>
        <Item Name="C (4)"  ExcludeView="sparse">(bits &amp; (1 &lt;&lt; 2)) != 0</Item>
      </Expand>
  </Type>
</AutoVisualizer>

To consume .natvis files via build.rs (example)

Add the following to your executable's Cargo.toml:

[build-dependencies]
natvis-pdbs = "1"

And the following to your build.rs:

fn main() {
    natvis_pdbs::metabuild();
}

To consume .natvis files via metabuild (nightly only, example)

Add the following to your executable's Cargo.toml:

cargo-features = ["metabuild"]

[package]
metabuild = ["natvis-pdbs"]

[build-dependencies]
natvis-pdbs = "1"

Recommended Reading

• Create custom views of C++ objects

• Format specifiers for C++ in the Visual Studio debugger

• Context Operator in the Visual Studio Debugger (C++)

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.