skip to content

rust-lldb

The lldb wrapper with Rust formatters, which is the default debugging path on macOS and other LLVM toolchains. Interviewers ask alongside rust-gdb, usually to check you know which debugger your platform actually ships with.

on this pageshow

explore

questions

5

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.
open as a page

Under rust-lldb, how do you stop a Rust program at the moment it panics, and then reach the frame that caused it?

level: middleimportance: should knowfreq 30%

basics

~20 s

Set breakpoint set -n rust_panic: std keeps that function as the place to break, after the panic hook runs but before unwinding starts. Then bt, frame select the first frame in your crate, and frame variable.

open as a page

Under rust-lldb, why does `p name.len()` fail on a Rust `String` while `p name` prints "katana", and what do you use instead?

level: middleimportance: should knowfreq 28%

basics

~20 s

LLDB has no Rust expression parser: name.len() goes to the expression evaluator, which runs it as Objective C++ and finds no member len. p name is a plain variable path, printed through the formatters. Read fields with frame variable instead.

open as a page

A Rust CLI from `cargo build` debugs fine under rust-lldb on your Mac, but copied to another Mac its breakpoints get no locations; why, and what do you ship?

level: seniorimportance: should knowfreq 18%

basics

~20 s

On macOS, Cargo leaves debug info unpacked in the object files under target/debug/deps, and the binary only points to them. Copied alone, it has no DWARF. Ship a .dSYM bundle, made with split-debuginfo = "packed" or dsymutil.

open as a page

Under rust-lldb on macOS, an `Option<String>` the code set to `None` prints as `Some(<error: ...>)`; what is happening, and how do you check the real value?

level: seniorimportance: nice to knowfreq 10%

basics

~20 s

The program is fine; the formatter picked the wrong variant. Option<String> stores None as an impossible capacity value, and when the provider cannot match that value to a variant it falls back to Some. frame variable -R shows the raw discriminant.

open as a page