Skip to content

Commit f231c91

Browse files
ehusstraviscross
ehuss
authored and
traviscross
committed
Move debugger_visualizer examples into example blocks
1 parent c384cd6 commit f231c91

File tree

1 file changed

+105
-103
lines changed

1 file changed

+105
-103
lines changed

‎src/attributes/debugger.md

Lines changed: 105 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -24,60 +24,61 @@ r[attributes.debugger.debugger_visualizer.natvis.msvc]
2424
This attribute only supports embedding Natvis files on `-windows-msvc` targets.
2525

2626
r[attributes.debugger.debugger_visualizer.natvis.path]
27-
The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file:
28-
29-
<!-- ignore: requires external files, and msvc -->
30-
```rust ignore
31-
#![debugger_visualizer(natvis_file = "Rectangle.natvis")]
32-
33-
struct FancyRect {
34-
x: f32,
35-
y: f32,
36-
dx: f32,
37-
dy: f32,
38-
}
39-
40-
fn main() {
41-
let fancy_rect = FancyRect { x: 10.0, y: 10.0, dx: 5.0, dy: 5.0 };
42-
println!("set breakpoint here");
43-
}
44-
```
45-
46-
and `Rectangle.natvis` contains:
47-
48-
```xml
49-
<?xml version="1.0" encoding="utf-8"?>
50-
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
51-
<Type Name="foo::FancyRect">
52-
<DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
53-
<Expand>
54-
<Synthetic Name="LowerLeft">
55-
<DisplayString>({x}, {y})</DisplayString>
56-
</Synthetic>
57-
<Synthetic Name="UpperLeft">
58-
<DisplayString>({x}, {y + dy})</DisplayString>
59-
</Synthetic>
60-
<Synthetic Name="UpperRight">
61-
<DisplayString>({x + dx}, {y + dy})</DisplayString>
62-
</Synthetic>
63-
<Synthetic Name="LowerRight">
64-
<DisplayString>({x + dx}, {y})</DisplayString>
65-
</Synthetic>
66-
</Expand>
67-
</Type>
68-
</AutoVisualizer>
69-
```
70-
71-
When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
27+
The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file.
7228

73-
```text
74-
> Variables:
75-
> fancy_rect: (10.0, 10.0) + (5.0, 5.0)
76-
> LowerLeft: (10.0, 10.0)
77-
> UpperLeft: (10.0, 15.0)
78-
> UpperRight: (15.0, 15.0)
79-
> LowerRight: (15.0, 10.0)
80-
```
29+
> [!EXAMPLE]
30+
> <!-- ignore: requires external files, and msvc -->
31+
> ```rust ignore
32+
> #![debugger_visualizer(natvis_file = "Rectangle.natvis")]
33+
>
34+
> struct FancyRect {
35+
> x: f32,
36+
> y: f32,
37+
> dx: f32,
38+
> dy: f32,
39+
> }
40+
>
41+
> fn main() {
42+
> let fancy_rect = FancyRect { x: 10.0, y: 10.0, dx: 5.0, dy: 5.0 };
43+
> println!("set breakpoint here");
44+
> }
45+
> ```
46+
>
47+
> and `Rectangle.natvis` contains:
48+
>
49+
> ```xml
50+
> <?xml version="1.0" encoding="utf-8"?>
51+
> <AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
52+
> <Type Name="foo::FancyRect">
53+
> <DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
54+
> <Expand>
55+
> <Synthetic Name="LowerLeft">
56+
> <DisplayString>({x}, {y})</DisplayString>
57+
> </Synthetic>
58+
> <Synthetic Name="UpperLeft">
59+
> <DisplayString>({x}, {y + dy})</DisplayString>
60+
> </Synthetic>
61+
> <Synthetic Name="UpperRight">
62+
> <DisplayString>({x + dx}, {y + dy})</DisplayString>
63+
> </Synthetic>
64+
> <Synthetic Name="LowerRight">
65+
> <DisplayString>({x + dx}, {y})</DisplayString>
66+
> </Synthetic>
67+
> </Expand>
68+
> </Type>
69+
> </AutoVisualizer>
70+
> ```
71+
>
72+
> When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
73+
>
74+
> ```text
75+
> > Variables:
76+
> > fancy_rect: (10.0, 10.0) + (5.0, 5.0)
77+
> > LowerLeft: (10.0, 10.0)
78+
> > UpperLeft: (10.0, 15.0)
79+
> > UpperRight: (15.0, 15.0)
80+
> > LowerRight: (15.0, 10.0)
81+
> ```
8182
8283
r[attributes.debugger.debugger_visualizer.gdb]
8384
### Using `debugger_visualizer` with GDB
@@ -95,56 +96,57 @@ There are two ways to enable auto-loading embedded pretty printers:
9596
r[attributes.debugger.debugger_visualizer.gdb.path]
9697
These scripts are embedded using the `gdb_script_file` key, which is a path relative to the crate source file.
9798
98-
<!-- ignore: requires external files -->
99-
```rust ignore
100-
#![debugger_visualizer(gdb_script_file = "printer.py")]
101-
102-
struct Person {
103-
name: String,
104-
age: i32,
105-
}
106-
107-
fn main() {
108-
let bob = Person { name: String::from("Bob"), age: 10 };
109-
println!("set breakpoint here");
110-
}
111-
```
112-
113-
and `printer.py` contains:
114-
115-
```python
116-
import gdb
117-
118-
class PersonPrinter:
119-
"Print a Person"
120-
121-
def __init__(self, val):
122-
self.val = val
123-
self.name = val["name"]
124-
self.age = int(val["age"])
125-
126-
def to_string(self):
127-
return "{} is {} years old.".format(self.name, self.age)
128-
129-
def lookup(val):
130-
lookup_tag = val.type.tag
131-
if lookup_tag is None:
132-
return None
133-
if "foo::Person" == lookup_tag:
134-
return PersonPrinter(val)
135-
136-
return None
137-
138-
gdb.current_objfile().pretty_printers.append(lookup)
139-
```
140-
141-
When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` will display:
142-
143-
```text
144-
"Bob" is 10 years old.
145-
```
146-
147-
[^rust-gdb]: Note: This assumes you are using the `rust-gdb` script which configures pretty-printers for standard library types like `String`.
99+
> [!EXAMPLE]
100+
> <!-- ignore: requires external files -->
101+
> ```rust ignore
102+
> #![debugger_visualizer(gdb_script_file = "printer.py")]
103+
>
104+
> struct Person {
105+
> name: String,
106+
> age: i32,
107+
> }
108+
>
109+
> fn main() {
110+
> let bob = Person { name: String::from("Bob"), age: 10 };
111+
> println!("set breakpoint here");
112+
> }
113+
> ```
114+
>
115+
> and `printer.py` contains:
116+
>
117+
> ```python
118+
> import gdb
119+
>
120+
> class PersonPrinter:
121+
> "Print a Person"
122+
>
123+
> def __init__(self, val):
124+
> self.val = val
125+
> self.name = val["name"]
126+
> self.age = int(val["age"])
127+
>
128+
> def to_string(self):
129+
> return "{} is {} years old.".format(self.name, self.age)
130+
>
131+
> def lookup(val):
132+
> lookup_tag = val.type.tag
133+
> if lookup_tag is None:
134+
> return None
135+
> if "foo::Person" == lookup_tag:
136+
> return PersonPrinter(val)
137+
>
138+
> return None
139+
>
140+
> gdb.current_objfile().pretty_printers.append(lookup)
141+
> ```
142+
>
143+
> When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` will display:
144+
>
145+
> ```text
146+
> "Bob" is 10 years old.
147+
> ```
148+
>
149+
> [^rust-gdb]: Note: This assumes you are using the `rust-gdb` script which configures pretty-printers for standard library types like `String`.
148150
149151
[auto-loading documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Auto_002dloading-safe-path.html
150152
[attributes]: ../attributes.md

0 commit comments

Comments
 (0)