https://github.com/maulingmonkey/natvis-pdbs
A metabuild / build.rs compatible crate to embed .natvis debug visualizer files into your executable's .pdbs, for ease of debugging.
https://github.com/maulingmonkey/natvis-pdbs
debug metabuild natvis pdb rust
Last synced: 2 months ago
JSON representation
A metabuild / build.rs compatible crate to embed .natvis debug visualizer files into your executable's .pdbs, for ease of debugging.
- Host: GitHub
- URL: https://github.com/maulingmonkey/natvis-pdbs
- Owner: MaulingMonkey
- License: apache-2.0
- Created: 2019-11-28T02:24:33.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-05-17T17:57:48.000Z (over 2 years ago)
- Last Synced: 2025-08-07T04:43:06.025Z (2 months ago)
- Topics: debug, metabuild, natvis, pdb, rust
- Language: Rust
- Homepage:
- Size: 35.2 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# natvis-pdbs
[](https://github.com/MaulingMonkey/natvis-pdbs)
[](https://ci.appveyor.com/project/MaulingMonkey/natvis-pdbs)
[](https://crates.io/crates/natvis-pdbs)
[](https://github.com/MaulingMonkey/natvis-pdbs/issues)
[](https://github.com/MaulingMonkey/natvis-pdbs)
[](https://deps.rs/repo/github/MaulingMonkey/natvis-pdbs)
A [metabuild] / [build.rs] compatible crate to embed `.natvis` debug visualizer files into your executable's `.pdb`s, 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](https://github.com/MaulingMonkey/natvis-pdbs/tree/master/crates/example-crate-with-natvis/)\)
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](#recommended-reading) bellow for more information about the .natvis format.
```xml
bits,bb
(bits & (1 << 0)) != 0
(bits & (1 << 1)) != 0
(bits & (1 << 2)) != 0
```
#### To consume .natvis files via [build.rs] \([example](https://github.com/MaulingMonkey/natvis-pdbs/tree/master/crates/example-usage-build-rs/)\)
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](https://github.com/MaulingMonkey/natvis-pdbs/tree/master/crates/example-usage-metabuild/)\)
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](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2019)
* [Format specifiers for C++ in the Visual Studio debugger](https://docs.microsoft.com/en-us/visualstudio/debugger/format-specifiers-in-cpp?view=vs-2019)
* [Context Operator in the Visual Studio Debugger (C++)](https://docs.microsoft.com/en-us/visualstudio/debugger/context-operator-cpp?view=vs-2019)
## License
Licensed under either of
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](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.
[metabuild]: https://github.com/rust-lang/rfcs/blob/master/text/2196-metabuild.md
[build.rs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html