debuggable

See what your Rust values hold, not how they're stored. A derive macro that embeds GDB and LLDB visualizers for your types.

Quick start · In a library · Attributes · Support · How it works

The same data twice, from examples/showcase.rs. Above: plain types, with the debugger failing on the slot map's empty slots. Below: the same types with #[derive(Debuggable)].

A debugger shows how a type is stored: raw pointers, capacities, bookkeeping fields, slots that aren't in use. Usually you want to see what the value holds. With debuggable you write that down once, next to the type, and GDB, LLDB and VS Code show it that way, for you and for anyone who uses your crate.

This is all it took for the screenshot above:

use debuggable::Debuggable;
use std::mem::MaybeUninit;

#[derive(Debuggable)]
#[debuggable(summary = "{num_elems} items")]
pub struct SlotMap<T> {
    #[debuggable(items, only = "version & 1", value = "u.value")]  // slots in use, as their values
    slots: Vec<Slot<T>>,
    #[debuggable(hide)]
    free_head: u32,
    #[debuggable(hide)]
    num_elems: u32,
}

#[derive(Debuggable)]
#[debuggable(summary = "{xs}")]                                     // shown as just "ferris"
pub struct InlineString<const N: usize> {
    #[debuggable(hide)]
    len: u8,
    #[debuggable(text, len = "len", hide)]                          // the first `len` bytes, as text
    xs: [MaybeUninit<u8>; N],
}

Quick start

1. Add the crate

cargo add debuggable

2. Derive it on your types and say what matters: a summary, fields to hide, a collection's items. All of it is optional; see Attributes.

#[derive(Debuggable)]
#[debuggable(summary = "{len}/{cap}")]
pub struct RawBuf {
    #[debuggable(items, len = "len")]
    ptr: NonNull<u16>,
    len: usize,
    cap: usize,
}

(gdb) print buf                                              without
$1 = my_crate::RawBuf {ptr: core::ptr::non_null::NonNull<u16> {pointer: 0x5555555aded0}, len: 3, cap: 4}

(gdb) print buf                                              with
$1 = 3/4 = {len = 3, cap = 4, [0] = 10, [1] = 20, [2] = 30}

Mistakes are compile errors:

error: summary refers to unknown field `lenght`; did you mean `length`?
 --> src/lib.rs:2:24
  |
2 | #[debuggable(summary = "{lenght} items")]
  |                        ^^^^^^^^^^^^^^^^

3. Set up your debugger, once per machine (and for GDB, once per project):

cargo install cargo-debuggable
cargo debuggable setup --dry-run   # show what would change
cargo debuggable setup

setup configures whichever of GDB, LLDB and VS Code (CodeLLDB) you have installed. It only edits marked blocks in their config files, backs each file up before the first change, and cargo debuggable setup --remove takes everything out again.

4. Debug as usual: rust-gdb, rust-lldb, lldb, or F5 in VS Code with CodeLLDB.

If a type still shows raw, cargo debuggable doctor target/debug/my-app checks the debuggers, their configuration and the binary, and says what to change. See also troubleshooting.

#[derive(Debuggable)]
pub enum Token {
    #[debuggable(summary = "Ident({name})")]
    Ident { name: String },
    #[debuggable(summary = "Num({0})")]
    Num(i64),
    Eof,                                // no summary: shown as `Eof`
}

#[derive(Debuggable)]
#[debuggable(summary = "{len} items")]
pub struct SlotMap<K, V> {
    #[debuggable(items, len = "len")]   // only the first `len` slots
    slots: Vec<Slot<V>>,
    #[debuggable(hide)]
    free_head: u32,
    #[debuggable(hide)]
    len: u32,
    _k: PhantomData<K>,                 // PhantomData is hidden automatically
}

#[derive(Debuggable)]
#[debuggable(summary = "v{version} {value}")]
pub struct Slot<V> {
    value: Option<V>,
    #[debuggable(hide)]
    version: u32,
}

(lldb) v map                                                 without
(my_crate::SlotMap<u8, alloc::string::String>) map = {
  slots = size=3 {
    [0] = {...}
    [1] = {...}
    [2] = {...}
  }
  free_head = 3
  len = 2
  _k =
}

(lldb) v map                                                 with
(my_crate::SlotMap<u8, alloc::string::String>) map = 2 items {
  [0] = v1 Some("alpha") {...}
  [1] = v3 Some("beta") {...}
}

A field that is itself Debuggable shows its own summary, so Slot above appears as v1 Some("alpha") inside the map. ({...} is a collapsed value.)

In a library

Derive it on your public types and your users get the visualizers with no work per type: the descriptions are compiled into their binaries along with your types. They run cargo debuggable setup once, like any user above.

If you'd rather not add a dependency for everyone, make it an optional feature:

[dependencies]
debuggable = { version = "0.1", optional = true }

#[cfg_attr(feature = "debuggable", derive(debuggable::Debuggable))]
#[cfg_attr(feature = "debuggable", debuggable(summary = "{len} items"))]
pub struct Stack {
    #[cfg_attr(feature = "debuggable", debuggable(hide))]
    len: usize,
    #[cfg_attr(feature = "debuggable", debuggable(items, len = "len"))]
    xs: [u32; 4],
}

With the feature off, nothing changes: no dependency, no MSRV bump, nothing in the binary.

Attributes

Shaping the value

Collections

Full reference with examples: docs.rs/debuggable.

Support

On Windows nothing is emitted, so crates that use debuggable still build unchanged.

CI runs every GDB and LLDB version above on every commit, in debug, release, thin-LTO and fat-LTO builds. VS Code was tested by hand on Linux. Details and known issues are in compatibility.

Limitations

• Types defined inside a function body aren't matched by debuggers. cargo debuggable doctor points them out.
• Summaries refer to fields by name. There are no expressions or format specs.
• In plain gdb, standard library types such as String and Vec inside your summaries show raw. rust-gdb loads rustc's printers for them.

How it works

The derive embeds a small JSON description of each type in the binary. On Linux it goes in a section that GDB loads automatically, together with a small runtime that renders the descriptions, so GDB only needs to trust your build directory. LLDB can't load anything from a binary, so cargo debuggable setup installs a loader that reads the same descriptions. More in how it works.

Contributing

See CONTRIBUTING.md for the layout, how to run each tier of tests, and what a schema or runtime change involves.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.