mirror of https://github.com/rust-lang/reference
move to debugger page, modify style
This commit is contained in:
parent
2749bce830
commit
ed69dfa154
|
@ -224,7 +224,6 @@ The following is an index of all built-in attributes.
|
|||
- [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level.
|
||||
- [`deprecated`] — Generates deprecation notices.
|
||||
- [`must_use`] — Generates a lint for unused values.
|
||||
- [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type
|
||||
- ABI, linking, symbols, and FFI
|
||||
- [`link`] — Specifies a native library to link with an `extern` block.
|
||||
- [`link_name`] — Specifies the name of the symbol for functions or statics
|
||||
|
@ -272,6 +271,8 @@ The following is an index of all built-in attributes.
|
|||
- Type System
|
||||
- [`non_exhaustive`] — Indicate that a type will have more fields/variants
|
||||
added in future.
|
||||
- Debugger
|
||||
- [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type
|
||||
|
||||
[Doc comments]: comments.md#doc-comments
|
||||
[ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
|
||||
|
@ -292,7 +293,7 @@ The following is an index of all built-in attributes.
|
|||
[`cold`]: attributes/codegen.md#the-cold-attribute
|
||||
[`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
|
||||
[`crate_type`]: linkage.md
|
||||
[`debugger_visualizer`]: attributes/diagnostics.md#the-debugger_visualizer-attribute
|
||||
[`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute
|
||||
[`deny`]: attributes/diagnostics.md#lint-check-attributes
|
||||
[`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
|
||||
[`derive`]: attributes/derive.md
|
||||
|
|
|
@ -0,0 +1,150 @@
|
|||
# Debugger attributes
|
||||
|
||||
The following [attributes] are used for enhancing the debugging experience when using third-party debuggers like GDB or LLDB.
|
||||
|
||||
## The `debugger_visualizer` attribute
|
||||
|
||||
The `debugger_visualizer` attribute can be used to embed a debugger visualizer file into the debug information generated by `rustc`.
|
||||
This enables an improved debugger experience for types outside of Rust's standard library.
|
||||
|
||||
### Using `debugger_visualizer` with Natvis
|
||||
|
||||
Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg that uses declarative rules to customize the display of types.
|
||||
A Natvis file is embedded using the `natvis-file` meta item.
|
||||
For detailed information on the Natvis format, refer to Microsoft's [Natvis documentation].
|
||||
|
||||
<div class="warning">
|
||||
Currently, this attribute only supports embedding Natvis files on `-windows-msvc` targets.
|
||||
</div>
|
||||
|
||||
Consider a crate with this directory structure:
|
||||
|
||||
```text
|
||||
/Cargo.toml
|
||||
/Rectangle.natvis
|
||||
+-- src
|
||||
+-- main.rs
|
||||
```
|
||||
|
||||
Where `main.rs` contains:
|
||||
|
||||
```rust
|
||||
#![debugger_visualizer(natvis_file = "../Rectangle.natvis")]
|
||||
struct FancyRect {
|
||||
pub x: f32,
|
||||
pub y: f32,
|
||||
pub dx: f32,
|
||||
pub dy: f32,
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let mut fancy_rect = FancyRect::new(10.0, 10.0, 5.0, 5.0);
|
||||
}
|
||||
```
|
||||
|
||||
and `Rectangle.natvis` contains:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
|
||||
<Type Name="Rectangle::FancyRect">
|
||||
<DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
|
||||
<Expand>
|
||||
<Synthetic Name="LowerLeft">
|
||||
<DisplayString>({x}, {y})</DisplayString>
|
||||
</Synthetic>
|
||||
<Synthetic Name="UpperLeft">
|
||||
<DisplayString>({x}, {y + dy})</DisplayString>
|
||||
</Synthetic>
|
||||
<Synthetic Name="UpperRight">
|
||||
<DisplayString>({x + dx}, {y + dy})</DisplayString>
|
||||
</Synthetic>
|
||||
<Synthetic Name="LowerRight">
|
||||
<DisplayString>({x + dx}, {y})</DisplayString>
|
||||
</Synthetic>
|
||||
</Expand>
|
||||
</Type>
|
||||
</AutoVisualizer>
|
||||
```
|
||||
|
||||
When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
|
||||
|
||||
```text
|
||||
> Variables:
|
||||
> fancy_rect: (10, 10) + (5, 5)
|
||||
> LowerLeft: (10, 10)
|
||||
> UpperLeft: (10, 15)
|
||||
> UpperRight: (15, 15)
|
||||
> LowerRight: (15, 10)
|
||||
```
|
||||
|
||||
### Using `debugger_visualizer` with GDB
|
||||
|
||||
GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view.
|
||||
These scripts are embedded using the `gdb_script_file` meta item.
|
||||
For detailed information on pretty printers, refer to GDB's [pretty print documentation].
|
||||
|
||||
Consider a crate with this directory structure:
|
||||
|
||||
```text
|
||||
/Cargo.toml
|
||||
/person_printer.py
|
||||
+-- src
|
||||
+-- main.rs
|
||||
```
|
||||
|
||||
Where `main.rs` contains:
|
||||
|
||||
```rust
|
||||
#![debugger_visualizer(gdb_script_file = "../bar.py")]
|
||||
mod person {
|
||||
pub struct Person {
|
||||
pub name: String,
|
||||
pub age: i32,
|
||||
}
|
||||
}
|
||||
|
||||
use person::Person;
|
||||
|
||||
fn main() {
|
||||
let person = Person::new(String::from("Bob"), 10);
|
||||
}
|
||||
```
|
||||
|
||||
and `person_printer.py` contains:
|
||||
|
||||
```python
|
||||
import gdb
|
||||
|
||||
class PersonPrinter:
|
||||
"Print a Person"
|
||||
|
||||
def __init__(self, val):
|
||||
self.val = val
|
||||
self.name = val["name"]
|
||||
self.age = int(val["age"])
|
||||
|
||||
def to_string(self):
|
||||
return "{} is {} years old.".format(self.name, self.age)
|
||||
|
||||
def lookup(val):
|
||||
lookup_tag = val.type.tag
|
||||
if lookup_tag is None:
|
||||
return None
|
||||
if "person::Person" == lookup_tag:
|
||||
return PersonPrinter(val)
|
||||
|
||||
return None
|
||||
|
||||
gdb.current_objfile().pretty_printers.append(lookup)
|
||||
```
|
||||
|
||||
When the crate's debug executable is passed into GDB, `print person` will display:
|
||||
|
||||
```
|
||||
"Bob" is 10 years old.
|
||||
```
|
||||
|
||||
[attributes]: ../attributes.md
|
||||
[Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects
|
||||
[pretty print documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
|
|
@ -301,154 +301,7 @@ When used on a function in a trait implementation, the attribute does nothing.
|
|||
> let _ = five();
|
||||
> ```
|
||||
|
||||
## The `debugger_visualizer` attribute
|
||||
|
||||
The `debugger_visualizer` attribute can be used to embed a debugger visualizer file into the PDB/ELF generated by `rustc`.
|
||||
This enables an improved debugger experience for types outside of Rust's standard library.
|
||||
|
||||
### Using `debugger_visualizer` with Natvis
|
||||
|
||||
Natvis is an XML-based framework, and a `.natvis` file declares how a type's fields should be displayed in the debugger view.
|
||||
A Natvis file is embedded using the `natvis-file` meta item.
|
||||
Microsoft's [Natvis documentation] can be referenced to help developers write their own `.natvis` files.
|
||||
|
||||
<div class="warning">
|
||||
Currently, this attribute only supports embedding Natvis files on `-windows-msvc` targets.
|
||||
`-windows-gnu` targets are not currently supported.
|
||||
</div>
|
||||
|
||||
Consider a crate with this directory structure:
|
||||
|
||||
```text
|
||||
/Cargo.toml
|
||||
/Foo.natvis (Note: the Natvis file does not have to match the name of the crate.)
|
||||
+-- src
|
||||
+-- main.rs
|
||||
```
|
||||
|
||||
Where `main.rs` contains:
|
||||
|
||||
```rust
|
||||
#![debugger_visualizer(natvis_file = "../Foo.natvis")]
|
||||
struct FancyRect {
|
||||
pub x: f32,
|
||||
pub y: f32,
|
||||
pub dx: f32,
|
||||
pub dy: f32,
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let mut fancy_rect = FancyRect::new(10.0, 10.0, 5.0, 5.0);
|
||||
}
|
||||
```
|
||||
|
||||
and `Foo.natvis` contains:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
|
||||
<Type Name="foo::FancyRect">
|
||||
<DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
|
||||
<Expand>
|
||||
<Synthetic Name="LowerLeft">
|
||||
<DisplayString>({x}, {y})</DisplayString>
|
||||
</Synthetic>
|
||||
<Synthetic Name="UpperLeft">
|
||||
<DisplayString>({x}, {y + dy})</DisplayString>
|
||||
</Synthetic>
|
||||
<Synthetic Name="UpperRight">
|
||||
<DisplayString>({x + dx}, {y + dy})</DisplayString>
|
||||
</Synthetic>
|
||||
<Synthetic Name="LowerRight">
|
||||
<DisplayString>({x + dx}, {y})</DisplayString>
|
||||
</Synthetic>
|
||||
</Expand>
|
||||
</Type>
|
||||
</AutoVisualizer>
|
||||
```
|
||||
|
||||
When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
|
||||
|
||||
```text
|
||||
> Variables:
|
||||
> fancy_rect: (10, 10) + (5, 5)
|
||||
> LowerLeft: (10, 10)
|
||||
> UpperLeft: (10, 15)
|
||||
> UpperRight: (15, 15)
|
||||
> LowerRight: (15, 10)
|
||||
```
|
||||
|
||||
### Using `debugger_visualizer` with GDB
|
||||
|
||||
Developers using GDB are able to embed *pretty printers* onto types.
|
||||
In GDB, a pretty printer is a structured Python script that describes how a type's fields should be displayed in the debugger view.
|
||||
These scripts are embedded using the `gdb_script_file` meta item.
|
||||
GDB's [pretty print documentation] can be referenced by developers to help them write their own `.py` scripts.
|
||||
|
||||
Consider a crate with this directory structure:
|
||||
|
||||
```text
|
||||
/Cargo.toml
|
||||
/bar.py (Note: the file does not have to match the name of the crate.)
|
||||
+-- src
|
||||
+-- main.rs
|
||||
```
|
||||
|
||||
Where `main.rs` contains:
|
||||
|
||||
```rust
|
||||
#![debugger_visualizer(gdb_script_file = "../bar.py")]
|
||||
mod person {
|
||||
pub struct Person {
|
||||
pub name: String,
|
||||
pub age: i32,
|
||||
}
|
||||
}
|
||||
|
||||
use person::Person;
|
||||
|
||||
fn main() {
|
||||
let person = Person::new(String::from("Bob"), 10);
|
||||
}
|
||||
```
|
||||
|
||||
and `bar.py` contains:
|
||||
|
||||
```python
|
||||
import gdb
|
||||
|
||||
class PersonPrinter:
|
||||
"Print a Person"
|
||||
|
||||
def __init__(self, val):
|
||||
self.val = val
|
||||
self.name = val["name"]
|
||||
self.age = int(val["age"])
|
||||
|
||||
def to_string(self):
|
||||
return "{} is {} years old.".format(self.name, self.age)
|
||||
|
||||
def lookup(val):
|
||||
lookup_tag = val.type.tag
|
||||
if lookup_tag is None:
|
||||
return None
|
||||
if "main::Person" == lookup_tag:
|
||||
return PersonPrinter(val)
|
||||
|
||||
return None
|
||||
|
||||
gdb.current_objfile().pretty_printers.append(lookup)
|
||||
```
|
||||
|
||||
When the crate's debug executable is passed into GDB, `print person` should display:
|
||||
|
||||
```
|
||||
"Bob" is 10 years old.
|
||||
```
|
||||
|
||||
[Clippy]: https://github.com/rust-lang/rust-clippy
|
||||
[Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects
|
||||
[pretty print documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
|
||||
[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
|
||||
[_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax
|
||||
[_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
|
||||
|
|
Loading…
Reference in New Issue