1## Debugger Visualizers
2
3Many languages and debuggers enable developers to control how a type is
4displayed in a debugger. These are called "debugger visualizations" or "debugger
5views".
6
7The Windows debuggers (WinDbg\CDB) support defining custom debugger visualizations using
8the `Natvis` framework. To use Natvis, developers write XML documents using the natvis
9schema that describe how debugger types should be displayed with the `.natvis` extension.
10(See: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2019)
11The Natvis files provide patterns which match type names a description of how to display
12those types.
13
14The Natvis schema can be found either online (See: https://code.visualstudio.com/docs/cpp/natvis#_schema)
15or locally at `<VS Installation Folder>\Xml\Schemas\1033\natvis.xsd`.
16
17The GNU debugger (GDB) supports defining custom debugger views using Pretty Printers.
18Pretty printers are written as python scripts that describe how a type should be displayed
19when loaded up in GDB/LLDB. (See: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html#Pretty-Printing)
20The pretty printers provide patterns, which match type names, and for matching
21types, describe how to display those types. (For writing a pretty printer, see: https://sourceware.org/gdb/onlinedocs/gdb/Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter).
22
23### Embedding Visualizers
24
25Through the use of the currently unstable `#[debugger_visualizer]` attribute, the `smallvec`
26crate can embed debugger visualizers into the crate metadata.
27
28Currently the two types of visualizers supported are Natvis and Pretty printers.
29
30For Natvis files, when linking an executable with a crate that includes Natvis files,
31the MSVC linker will embed the contents of all Natvis files into the generated `PDB`.
32
33For pretty printers, the compiler will encode the contents of the pretty printer
34in the `.debug_gdb_scripts` section of the `ELF` generated.
35
36### Testing Visualizers
37
38The `smallvec` crate supports testing debugger visualizers defined for this crate. The entry point for
39these tests are `tests/debugger_visualizer.rs`. These tests are defined using the `debugger_test` and
40`debugger_test_parser` crates. The `debugger_test` crate is a proc macro crate which defines a
41single proc macro attribute, `#[debugger_test]`. For more detailed information about this crate,
42see https://crates.io/crates/debugger_test. The CI pipeline for the `smallvec` crate has been updated
43to run the debugger visualizer tests to ensure debugger visualizers do not become broken/stale.
44
45The `#[debugger_test]` proc macro attribute may only be used on test functions and will run the
46function under the debugger specified by the `debugger` meta item.
47
48This proc macro attribute has 3 required values:
49
501. The first required meta item, `debugger`, takes a string value which specifies the debugger to launch.
512. The second required meta item, `commands`, takes a string of new line (`\n`) separated list of debugger
52commands to run.
533. The third required meta item, `expected_statements`, takes a string of new line (`\n`) separated list of
54statements that must exist in the debugger output. Pattern matching through regular expressions is also
55supported by using the `pattern:` prefix for each expected statement.
56
57#### Example:
58
59```rust
60#[debugger_test(
61    debugger = "cdb",
62    commands = "command1\ncommand2\ncommand3",
63    expected_statements = "statement1\nstatement2\nstatement3")]
64fn test() {
65
66}
67```
68
69Using a multiline string is also supported, with a single debugger command/expected statement per line:
70
71```rust
72#[debugger_test(
73    debugger = "cdb",
74    commands = "
75command1
76command2
77command3",
78    expected_statements = "
79statement1
80pattern:statement[0-9]+
81statement3")]
82fn test() {
83
84}
85```
86
87In the example above, the second expected statement uses pattern matching through a regular expression
88by using the `pattern:` prefix.
89
90#### Testing Locally
91
92Currently, only Natvis visualizations have been defined for the `smallvec` crate via `debug_metadata/smallvec.natvis`,
93which means the `tests/debugger_visualizer.rs` tests need to be run on Windows using the `*-pc-windows-msvc` targets.
94To run these tests locally, first ensure the debugging tools for Windows are installed or install them following
95the steps listed here, [Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/).
96Once the debugging tools have been installed, the tests can be run in the same manner as they are in the CI
97pipeline.
98
99#### Note
100
101When running the debugger visualizer tests, `tests/debugger_visualizer.rs`, they need to be run consecutively
102and not in parallel. This can be achieved by passing the flag `--test-threads=1` to rustc. This is due to
103how the debugger tests are run. Each test marked with the `#[debugger_test]` attribute launches a debugger
104and attaches it to the current test process. If tests are running in parallel, the test will try to attach
105a debugger to the current process which may already have a debugger attached causing the test to fail.
106
107For example:
108
109```
110cargo test --test debugger_visualizer --features debugger_visualizer -- --test-threads=1
111```
112