#metabuild #natvis #debug

natvis-pdbs

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

4 stable releases

1.0.3 Sep 7, 2022
1.0.2 Dec 30, 2019
1.0.1 Nov 30, 2019
0.0.1 Nov 28, 2019

#104 in Debugging

34 downloads per month

MIT/Apache

11KB
82 lines

natvis-pdbs

GitHub Build status Crates.io unsafe: no rust: 1.39.0+ Open issues License dependency status

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

License

Licensed under either of

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.

Dependencies

~0.6–1.3MB
~30K SLoC