1
- - Feature Name: ` debugger-visualizer `
1
+ - Feature Name: ` debugger_visualizer `
2
2
- Start Date: 2021-11-01
3
3
- RFC PR: [ rust-lang/rfcs #3191 ] ( https://github.com/rust-lang/rfcs/pull/3191 )
4
4
- Rust Issue: [ rust-lang/rust #0000 ] ( https://github.com/rust-lang/rust/issues/0000 )
@@ -16,7 +16,7 @@ crates.
16
16
Most, if not all, Rust developers will at some point have to debug an issue
17
17
in their crate. Trying to view types as they are laid out in memory is not
18
18
always the most telling. Furthermore when viewing types from external crates,
19
- the information is even harder to interpret.
19
+ the information is even harder to interpret.
20
20
21
21
Many languages and debuggers enable developers to control how a type is
22
22
displayed in a debugger. These are called "debugger visualizations" or "debugger
@@ -198,7 +198,7 @@ types, a description of how to display those types. This allows for some
198
198
limited support for generic types.
199
199
200
200
Rust developers can add one or more ` .natvis ` files to their crate. Through
201
- the use of a new Rust attribute, ` #[debugger-visualizer ] ` , the compiler will
201
+ the use of a new Rust attribute, ` #[debugger_visualizer ] ` , the compiler will
202
202
encode the contents of the ` .natvis ` file in the crate metadata if the target
203
203
is an ` rlib ` . If the target is a ` dll ` or ` exe ` , the ` /NATVIS ` MSVC linker flag is
204
204
set for each ` .natvis ` file which will embed the Natvis visualizations into the PDB.
@@ -282,7 +282,7 @@ types, descibe how to display those types. (For writing a pretty printer, see: h
282
282
283
283
Rust developers can add one or more pretty printers to their crate. This is done
284
284
in the Rust compiler via ` .py ` python scripts. Through the use of a new Rust attribute,
285
- ` #[debugger-visualizer ] ` , the compiler will encode the contents of the ` .py ` file in
285
+ ` #[debugger_visualizer ] ` , the compiler will encode the contents of the ` .py ` file in
286
286
the crate metadata if the target is an ` rlib ` . If the target is an executable, the
287
287
` .debug_gdb_scripts ` section will include a reference to the pretty printer specified.
288
288
@@ -292,12 +292,12 @@ extension.
292
292
# Reference-level explanation
293
293
[ reference-level-explanation ] : #reference-level-explanation
294
294
295
- In rustc, a new built-in attribute ` #[debugger-visualizer ] ` will be added which
295
+ In rustc, a new built-in attribute ` #[debugger_visualizer ] ` will be added which
296
296
instructs the compiler to take the specified file path for a debugger visualizer
297
297
and add it to the current binary being built. The file path specified must be
298
298
relative to the location of the attribute.
299
299
300
- The ` #[debugger-visualizer ] ` attribute will reserve multiple keys to be able to
300
+ The ` #[debugger_visualizer ] ` attribute will reserve multiple keys to be able to
301
301
specify which type of visualizer is being applied. The following keys will be
302
302
reserved as part of this RFC:
303
303
@@ -311,33 +311,33 @@ For example, to specify that a `.natvis` file should be included in the binary
311
311
being built, the following attribute should be added to the Rust source:
312
312
313
313
``` rust
314
- #![debugger - visualizer (natvis_file = " ../foo.natvis" )]
314
+ #![debugger_visualizer (natvis_file = " ../foo.natvis" )]
315
315
```
316
316
317
317
The same can be done to specify a GDB python debugger script:
318
318
319
319
``` rust
320
- #![debugger - visualizer (gdb_script_file = " ../foo.py" )]
320
+ #![debugger_visualizer (gdb_script_file = " ../foo.py" )]
321
321
```
322
322
323
323
Depending on the Rust target, the correct debugger visualizer will be selected and embedded
324
324
in the output.
325
325
326
326
The Rust compiler will serialize the contents of the file specified via the
327
- ` #[debugger-visualizer ] ` attribute and store it in the crate metadata. This attribute
327
+ ` #[debugger_visualizer ] ` attribute and store it in the crate metadata. This attribute
328
328
can be used multiple times to allow for multiple debugger visualizer files to be
329
329
embedded for each crate. When generating the final binary, the contents of the
330
330
visualizer file will be extracted from the crate metadata and written to a new file
331
331
in the target directory under a new ` visualizer ` directory.
332
332
333
- In the case of a Natvis file, ` #![debugger-visualizer (natvis_file = "../foo.natvis")] `
333
+ In the case of a Natvis file, ` #![debugger_visualizer (natvis_file = "../foo.natvis")] `
334
334
the compiler will set the ` /NATVIS:{.natvis file} ` MSVC linker flag for each of the
335
335
Natvis files specified for the current crate as well as transitive dependencies if
336
336
using the MSVC toolchain. This linker flag ensures that the specified Natvis files
337
337
be embedded in the PDB generated for the binary being built. Any crate type that
338
338
would generate a PDB would have all applicable ` .natvis ` files embedded.
339
339
340
- In the case of GDB pretty printer, ` #![debugger-visualizer (gdb_script_file = "../foo.py")] `
340
+ In the case of GDB pretty printer, ` #![debugger_visualizer (gdb_script_file = "../foo.py")] `
341
341
the compiler will ensure that the set of pretty printers specified will be added to the
342
342
` .debug_gdb_scripts ` section of the ` ELF ` generated. The ` .debug_gdb_scripts ` section
343
343
takes a list of null-terminated entries which specify scripts to load within GDB. The
@@ -495,7 +495,7 @@ need be.
495
495
The drawbacks for this option is that it seems a sub-optimal in terms of user
496
496
experience. It requires the author to operate at a lower level of abstraction by
497
497
having to use a more general attribute and annotating it to tackle a specific use
498
- case. Having a more targeted attribute, i.e. ` #[debugger-visualizer ] ` allows for the
498
+ case. Having a more targeted attribute, i.e. ` #[debugger_visualizer ] ` allows for the
499
499
author to simply specify which debugger visualizer file should be included and allow
500
500
the compiler to select the right one under the covers.
501
501
@@ -573,7 +573,7 @@ Debugger visualizer support for Rust could be improved upon by adding support fo
573
573
574
574
``` rust
575
575
/// A rectangle in first quadrant
576
- #[debugger - visualizer (
576
+ #[debugger_visualizer (
577
577
natvis(r # "
578
578
<DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
579
579
<Item Name="LowerLeft">({x}, {y})</Item>
0 commit comments