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 <?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: toml [build-dependencies] natvis-pdbs = "1"

And the following to your [build.rs]: rust fn main() { natvis_pdbs::metabuild(); }

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

Add the following to your executable's Cargo.toml: ```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.