How does `#![debugger_visualizer(gdb_script_file = "...")]` let a Rust crate ship GDB pretty-printers for its own types, and why might they not load?
answer
- stable since 1.71
- crate root or module only
- embedded at compile time
- auto-load safe path for the binary
basics
~20 sSince Rust 1.71, the attribute embeds a Python pretty-printer script into a Linux binary's .debug_gdb_scripts section at compile time. GDB runs embedded scripts only when the binary's path is in its auto-load safe path, which rust-gdb does not add.
solid answer
~40 s`#![debugger_visualizer(gdb_script_file = "printer.py")]`, stable since Rust 1.71, goes on the crate root or a module; the path is relative to the source file. rustc reads the script at compile time and embeds its text in the binary's `.debug_gdb_scripts` section, and Cargo rebuilds when the script changes. The script defines a printer class with `to_string` and a lookup function that matches `val.type.tag`, such as `"sensor::Reading"`, and registers that lookup with `gdb.current_objfile().pretty_printers`. GDB runs embedded scripts only when the binary's own path is in its auto-load safe path. rust-gdb adds only the toolchain's etc directory, so pass `-iex "add-auto-load-safe-path <binary>"` or add that line to `~/.config/gdb/gdbinit`. macOS (`*-apple-*`), wasm and bare-metal Arm targets get no section at all.
code
rust · 11 lines#![debugger_visualizer(gdb_script_file = "../gdb/reading.py")]
pub struct Reading {
pub raw: u16,
pub scale: u16,
}
fn main() {
let r = Reading { raw: 512, scale: 4 };
println!("{}", r.raw as u32 * r.scale as u32);
}go deeper
Recall that a crate can ship a GDB pretty-printer for its own types with the debugger_visualizer attribute and a Python file.
Explain where the attribute may go, how the script's lookup matches val.type.tag, and that rustc embeds the file at compile time.
Diagnose a printer that will not load: the binary missing from the auto-load safe path, a target without the section, a lookup that never matches, or no debug info.
Weigh shipping GDB visualizers with a library: better debugging for users against keeping Python in sync with private layouts, and asking users to trust embedded scripts.
## What the attribute does Std's types get readable output from the scripts in the toolchain's etc directory, but a library's own types do not. A **visualizer** is the debugger-side description of how to show a type. Rust's `debugger_visualizer` attribute, stabilised in **Rust 1.71**, lets a crate embed one into the debug information of the program it is built into. It takes one of two keys: - `natvis_file` for Natvis XML, used by the Windows debuggers and supported only on `-windows-msvc` targets; - `gdb_script_file` for a GDB **pretty-printer** written in Python. The path is relative to the source file that carries the attribute. The attribute may be repeated, and the Reference says every visualizer file named this way is loaded. ## Writing the script A GDB pretty-printer has two parts: 1. a printer class whose `to_string` returns the display text, and optionally `children` for nested items; 2. a lookup function that receives a value, checks `val.type.tag` against the type's full name, such as `"sensor::Reading"`, and returns a printer or `None`. The script ends by registering the lookup function with `gdb.current_objfile().pretty_printers.append(lookup)`, so it applies to the binary it came from. The tag is the name the debug info records, crate first and then the module path, which you can confirm by printing the type in a debugger. Two habits from std's own providers carry over. A generic type's tag includes its parameters, such as `sensor::Window<u16>`, so match it with a prefix or a regular expression, as std's `rust_types.py` does, rather than with equality. A printer for a collection can return `children` and a `display_hint` of `"array"`, `"map"` or `"string"`, which is how std's `Vec`, `HashMap` and `String` providers get their layout. ## Where the script ends up rustc reads the file **at compile time**. A missing file fails the build with rustc's `couldn't read` error naming the path. The file also appears in Cargo's dependency info, so editing it triggers a rebuild. GDB's manual defines two kinds of `.debug_gdb_scripts` entries, file names and inline script text. Std's printers use a file entry naming `gdb_load_rust_pretty_printers.py`. A crate's visualizer is embedded as inline text under a generated name such as `pretty-printer-<crate>-<n>`, so the `.py` file does not need to exist on the machine that runs GDB. Each entry carries its crate's name, so one binary can hold scripts from several crates; that is how a library's printers reach the programs that link it. ## Why the printers might not load 1. **The auto-load safe path.** GDB runs inline scripts from `.debug_gdb_scripts` only when the file that contains the section, your binary, is in the safe path. The Rust Reference states it plainly: embedded pretty-printers are not loaded automatically. rust-gdb adds only `<sysroot>/lib/rustlib/etc`, which is why std's printers work and yours do not. Fix it per session with `rust-gdb -iex "add-auto-load-safe-path target/debug/app" target/debug/app`, or permanently with an `add-auto-load-safe-path` line in `$HOME/.config/gdb/gdbinit`. 2. **A target without the section.** The specifications of the `*-apple-*` targets, the WebAssembly targets and bare-metal Arm targets such as `thumbv7em-none-eabihf` set `emit-debug-gdb-scripts` to false. The attribute still compiles, but nothing is embedded. A GDB script also does nothing for someone debugging with LLDB. 3. **The lookup never matches.** A tag compared with the wrong crate name, or a generic type whose full name includes its parameters, returns `None`, and GDB falls back to the plain struct view. 4. **No debug info.** The printer needs the type to be described, so a build without full debug info has nothing to print. ## Rules rustc enforces | Mistake | What rustc 1.99 reports | |---|---| | attribute on a struct | an error that it cannot be used on structs, with help saying it can be applied to crates and modules | | an unknown key | error E0539, a malformed attribute input, naming `natvis_file` or `gdb_script_file` as the valid arguments | | a path that does not exist | a `couldn't read` error with the path and the operating system's reason | For a library maintainer, the attribute is the low-friction way to make a complex type debuggable for every downstream user on Linux. Treat the script as code, because GDB runs it with the user's privileges once the binary is trusted.
- Your crate's embedded printer works for you but not for a teammate using the same binary; what differs?Usually the teammate's auto-load safe path. GDB runs inline `.debug_gdb_scripts` entries only for binaries in that path, and rust-gdb adds only the toolchain's etc directory. Your `~/.config/gdb/gdbinit` probably has an `add-auto-load-safe-path` line that theirs lacks. Passing `-iex "add-auto-load-safe-path <binary>"` makes the session independent of either setup.
- Why does the attribute do nothing for a crate built for a macOS target such as `aarch64-apple-darwin`?rustc does not write a `.debug_gdb_scripts` section there: the `*-apple-*` target specifications set `emit-debug-gdb-scripts` to false, and macOS developers normally debug with LLDB, which runs no GDB scripts. The attribute still compiles and the script is still read, but nothing reaches the binary.
- The attribute goes on the struct whose values it should format
- GDB reads the script from the crate's source directory when debugging
- rust-gdb automatically trusts and loads every embedded printer
- natvis_file works with GDB on Linux as well
- The embedded script works the same way under LLDB on macOS
Assumes Rust 1.99; the debugger_visualizer attribute has been stable since Rust 1.71.