skip to content

What does the `rust-lldb` script import before LLDB loads a Rust binary, and how does that change the way a `Vec<u32>` is displayed?

level: juniorimportance: should knowfreq 35%

answer

  1. a shell script, not a debugger
  2. a Python module imported at startup
  3. summaries and synthetic children
  4. type-name regex per std type

basics

~20 s

rust-lldb is a shell script that starts LLDB after importing the toolchain's lldb_lookup.py, which registers Rust summaries and synthetic children for std types. Plain LLDB has no such formatters, so it prints the raw struct layout.

solid answer

~40 s

`rust-lldb` is a short shell script that rustup installs next to `rustc`. It asks `rustc` for the sysroot, picks an `lldb` (the sysroot's own copy if there is one, otherwise the one on `PATH`, on a Mac typically the system LLDB) and execs it with `command script import "<sysroot>/lib/rustlib/etc/lldb_lookup.py"` run before the target loads. That module creates a `Rust` type category and registers **summaries** (`size=3`, `"katana"`) and **synthetic children** (`[0]`, `[1]`) for standard-library types, matched by type-name regexes such as `^(alloc::([a-z_]+::)+)Vec<.+>$`. Plain `lldb` has none of that, so it shows the real layout: `buf`, `inner`, `ptr`, `cap`, `len`. Seeing those fields proves the debug info is there; only the formatter is missing. Importing the same module into any LLDB session gives the same output.

code

plaintext · 15 lines
plaintext
(lldb) frame variable v
(alloc::vec::Vec<unsigned int, alloc::alloc::Global>) v = {
  buf = {
    inner = {
      ptr = {
        pointer = (pointer = "\n")
        _marker = {}
      }
      cap = (__0 = 3)
      alloc = {}
    }
    _marker = {}
  }
  len = 3
}

go deeper

for a junior

Say that rust-lldb is a script around LLDB that loads Python formatters, and that plain lldb shows the raw struct fields of Vec and String.

for a middle

Explain the startup command: it imports lldb_lookup.py from the sysroot's lib/rustlib/etc, which registers summaries and synthetic children for std types in a Rust category.

for a senior

Show you can diagnose the situation: raw fields prove debug info exists, and the fix is importing the module into the session or the editor's LLDB setup, not rebuilding.

for a principal

Point out that formatter coverage is per type and tied to std's private layout, so a team debugging in editors should standardise how the import is configured.

## What `rust-lldb` actually is `rust-lldb` is not a debugger of its own. rustup installs it beside `rustc` as a short POSIX shell script (the toolchain's `bin/rust-lldb`, reached through the `rust-lldb` proxy in `~/.cargo/bin`). The script does four things: 1. Asks `rustc --print host-tuple` for the host target and `rustc --print sysroot` for the toolchain directory. 2. Uses `lib/rustlib/<host>/bin/lldb` inside the sysroot if that file exists. Otherwise it uses whatever `lldb` is on `PATH`, and stops with `lldb not found! Please install it.` when there is none. 3. Builds one LLDB command: `command script import "<sysroot>/lib/rustlib/etc/lldb_lookup.py"`. 4. Runs `exec` on LLDB with `--one-line-before-file` carrying that command, followed by your own arguments. Every command, breakpoint and step is therefore LLDB's own. The stable `aarch64-apple-darwin` toolchain ships no `lldb` in that sysroot directory, so on a Mac the wrapper runs the system LLDB that the macOS developer tools put on `PATH`. That LLDB even says so when a process starts: `warning: This version of LLDB has no plugin for the language "rust". Inspection of frame variables will be limited.` The Python formatters are what fill that gap. ## What the import registers `lldb_lookup.py` runs when LLDB loads it. It creates (or reuses) a **type category** named `Rust`, enables it, and registers two kinds of formatter, implemented in `lldb_providers.py`: - **Summaries**: the one-line text after `=`, such as `size=3` for a `Vec` or `"katana"` for a `String`. - **Synthetic children**: the child list LLDB shows and indexes instead of the real fields, such as `[0]` and `[1]` for a `Vec`'s elements. Each registration is keyed by a **regular expression over the type name** recorded in the debug info: | Type-name pattern | Synthetic provider | Summary shown | |---|---|---| | `^(alloc::([a-z_]+::)+)String$` | `StdStringSyntheticProvider` | the text in quotes | | `^(alloc::([a-z_]+::)+)Vec<.+>$` | `StdVecSyntheticProvider` | `size=N` | | `^(std::collections::([a-z_]+::)+)HashMap<.+>$` | `classify_hashmap` | `size=N` | | `^(alloc::([a-z_]+::)+)Rc<.+>$` | `StdRcSyntheticProvider` | `strong=N, weak=N` | With an LLDB new enough to offer callback recognizers, your own structs, tuples and enums are matched by small Python functions (`is_udt`, `is_tuple_type`, `is_gnu_enum`) instead of by name. In a live session, `type synthetic list -w Rust` prints the whole table. ## The same values in both debuggers | Value | Plain `lldb` | `rust-lldb` | |---|---|---| | `Vec<u32>` | `buf`, `inner`, `ptr`, `cap = (__0 = 3)`, `len = 3` | `size=3` with `[0] = 10`, `[1] = 20`, `[2] = 30` | | `&str` | `data_ptr = "hello..."` running on, plus `length = 5` | `"hello"` | | `HashMap<String, Vec<u32>>` | `base`, then `hash_builder` and `table` | `size=2`, `[0] = ("GET /", size=3)` | | `Option<String>` | a `$variants$` tree with `$discr$` members | `Some("ana")` | The `&str` row is a classic confusion. Without the summary, LLDB treats `data_ptr` as a C string and reads until it meets a zero byte, so `"hello"` runs straight into whatever constants the linker placed next to it (panic-message text, in a real session). The correct `length` sits right beside it, but nothing reads it. Raw fields do **not** mean the build lacks debug info. They mean the debug info is present and LLDB has no formatter for that type name; a binary without debug info could not name `buf` or `len` at all. ## Getting the formatters without the wrapper - In any LLDB session, `command script import` with the full path to the toolchain's `lib/rustlib/etc/lldb_lookup.py` (take the directory from `rustc --print sysroot`) registers the same category. It works even after the process has stopped. - `type category enable Rust` on its own does nothing useful in plain `lldb`: the category does not exist until the import creates it, and LLDB answers `warning: empty category enabled (typo?)`. - An editor front-end built on LLDB shows Rust values readably only when it loads these formatters, or its own, at startup. ## Limits worth knowing - Coverage is per type. The 1.99 LLDB scripts register no provider for `BTreeMap`, so one prints as raw nodes with `keys` and `vals` arrays. - The providers read memory from Python. They never call into the Rust program, so no `Debug` impl runs. - A comment in `lldb_lookup.py` notes that the `Rust` category cannot yet be tied to the Rust language, so it is active for every frame; its patterns still only match Rust standard-library type names. - Exporting `RUST_LLDB` does not choose the binary: the script assigns that variable itself from the sysroot path.

  • Which `lldb` binary does `rust-lldb` run, and can you point it at another one?
    It first looks for `lib/rustlib/<host>/bin/lldb` inside the sysroot that `rustc --print sysroot` reports; if that file is absent it runs `lldb` from `PATH`, and exits with `lldb not found! Please install it.` when there is none. On a Mac the stable toolchain ships no copy, so the system LLDB runs. Exporting `RUST_LLDB` has no effect, because the script assigns that variable itself; put a different `lldb` first on `PATH` instead.
  • How do you get rust-lldb's output in a plain `lldb` session that is already stopped?
    Run `command script import` with the full path to `lib/rustlib/etc/lldb_lookup.py` under the toolchain's sysroot. The module creates and enables the `Rust` type category on load, and every later `frame variable` uses its summaries and synthetic children. This is exactly the command the wrapper passes with `--one-line-before-file`, so nothing else differs.

  • rust-lldb is a separate debugger with its own Rust engine.
  • Raw buf, cap and len fields mean the binary has no debug info.
  • rustc embeds the LLDB formatters into the binary's debug info.
  • Plain lldb cannot set breakpoints or step in a Rust binary.
  • Exporting RUST_LLDB tells the wrapper which lldb to run.