skip to content

When `rust-gdb` still prints a Rust `Vec<Order>` as raw fields and std frames without source, which steps of its setup do you check?

level: seniorimportance: nice to knowfreq 18%

answer

  1. which toolchain the script asks
  2. three -iex and --directory arguments
  3. a section naming the loader file
  4. type names matched by regex
  5. /rustc/<hash> mapped to rust-src

basics

~20 s

Check each link: the toolchain whose sysroot the script asks rustc for, the lib/rustlib/etc directory it adds to GDB's source and auto-load safe paths, the binary's .debug_gdb_scripts entry naming the loader, the providers' type-name patterns and std's /rustc/<hash> mapping to rust-src.

solid answer

~40 s

`rust-gdb` asks the `rustc` beside it for `--print=sysroot` and `-vV`, then execs `gdb` (or `RUST_GDB`) with `--directory=<sysroot>/lib/rustlib/etc`, `-iex "add-auto-load-safe-path <etc>"`, `-iex "set substitute-path /rustc/<hash> <sysroot>/lib/rustlib/src/rust"` and the etc directory appended to `PYTHONPATH`. On Linux, the binary's `.debug_gdb_scripts` section names `gdb_load_rust_pretty_printers.py`; GDB finds it through `--directory`, may run it because of the safe path, and the loader registers printers that match std types by regex. So raw output means GDB was started without the wrapper, has no Python, the section is missing for that target, the type does not match, or the scripts come from a toolchain that doesn't know the binary's layout. Missing std source means rust-src is absent or the commit hash differs.

code

console · 12 lines
console
$ cat fakegdb.sh
#!/bin/sh
echo "PYTHONPATH=$PYTHONPATH"
for a in "$@"; do echo "ARG: $a"; done
$ RUST_GDB=./fakegdb.sh rust-gdb ./orders
PYTHONPATH=:<sysroot>/lib/rustlib/etc
ARG: --directory=<sysroot>/lib/rustlib/etc
ARG: -iex
ARG: add-auto-load-safe-path <sysroot>/lib/rustlib/etc
ARG: -iex
ARG: set substitute-path /rustc/58cf8f9c35b355199727627d07ae34a4e2846d67 <sysroot>/lib/rustlib/src/rust
ARG: ./orders

go deeper

for a junior

Recall that rust-gdb finds the toolchain with rustc, points GDB at the lib/rustlib/etc scripts and then starts ordinary GDB.

for a middle

Explain the three arguments the wrapper passes and the PYTHONPATH change, and how the binary's section names the loader file GDB then finds.

for a senior

Walk a failure to its link: plain gdb, no Python, no section on that target, a toolchain mismatch, missing rust-src, or a type name the patterns do not match.

for a principal

Weigh pinning one toolchain for building and debugging across CI, developer machines and crash reproduction, so the printers and source mapping always match the binary.

## Step 1: which toolchain the wrapper asks `rust-gdb` in `~/.cargo/bin` is a **rustup proxy**: rustup runs the `bin/rust-gdb` of whichever toolchain it selects for the current directory. That script prefers the `rustc` sitting in its own directory and falls back to `rustc` on `PATH`. It asks that compiler two things: `rustc --print=sysroot` for the toolchain's root, and `rustc -vV` for the `commit-hash` line. Everything that follows comes from that toolchain, not from the binary you are debugging. If the binary was built by a different toolchain, the printers and the source mapping belong to the wrong release. ## Step 2: what it hands GDB The script prepends its own arguments to yours and then runs `exec ${RUST_GDB}`, with `RUST_GDB` defaulting to `gdb`: | Argument or variable | Effect in GDB | |---|---| | `--directory=<sysroot>/lib/rustlib/etc` | adds etc to the **source search path**, where GDB looks for script files a binary names | | `-iex "add-auto-load-safe-path <etc>"` | allows auto-loading scripts from etc; `-iex` runs before the program is loaded | | `-iex "set substitute-path /rustc/<hash> <sysroot>/lib/rustlib/src/rust"` | maps std's recorded source paths to the installed rust-src | | `PYTHONPATH=...:<etc>` | lets GDB's Python import the helper modules | A nightly-only extra, a `trim-paths` script added with `-x` when `RUST_GDB_TRIM_PATHS=unstable` is set and the file exists, is unstable and absent from stable toolchains. Because `RUST_GDB` is honoured, the same setup works with a cross GDB for another architecture. ## Step 3: what the binary contributes On Linux targets, a build with debug info carries a `.debug_gdb_scripts` section. GDB's manual defines it as a list of entries, each starting with a byte that gives the kind; byte 1 means a Python script file. rustc's entry is `\x01gdb_load_rust_pretty_printers.py`. GDB looks for that file in the current directory and then along the source search path, which is why `--directory` matters. File scripts load only from a directory in the **auto-load safe path**, which is why the `-iex` matters. The loader appends its own directory to `sys.path`, imports `gdb_lookup` and registers one printer on the object file. Some targets never get the section. The target 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. A firmware engineer debugging a Cortex-M ELF through a cross GDB therefore gets no auto-load at all. `source` the loader file by hand at the GDB prompt or in a `.gdbinit`. ## Step 4: matching by type name `rust_types.py` classifies each struct by its full debug-info name with regular expressions: - `Vec` matches `^(alloc::([a-z_]+::)+)Vec<.+>$`, `String` matches `^(alloc::([a-z_]+::)+)String$`; - `HashMap` and `HashSet` must sit under `std::collections::`; - `&str` and slices match `^&(mut )?str$` and `^&(mut )?\[.+\]$`. Anything else prints as GDB's ordinary struct view. A `heapless::Vec`, whose type name starts with `heapless::`, stays raw. The providers also hard-code std's private field paths, such as `buf.inner.ptr`. Comments such as `# BACKCOMPAT: rust 1.95` show them reading older layouts, but scripts from an older toolchain cannot know a layout that a newer std introduced. ## A diagnosis checklist 1. Confirm the session really started through `rust-gdb`. An editor or script that calls `gdb` directly skips every step above. 2. Confirm GDB has Python support, because every printer is a Python class. 3. Confirm the binary has the section: `objdump -h` lists `.debug_gdb_scripts` on a Linux build with debug info. 4. Compare toolchains: the hash in the binary's `/rustc/<hash>/library/...` paths should equal the wrapper's `rustc -vV` commit hash. 5. For std frames without source, check that `<sysroot>/lib/rustlib/src/rust` exists. That directory comes from the rust-src component. 6. If only one type is raw, read its full type name and compare it with the patterns. ## Why it is built this way The binary carries only the **name** of the loader, not the printers themselves. The printers therefore improve when you update the toolchain, and std's layout knowledge lives in one place per release rather than in every executable. The safe-path check exists because auto-loading runs arbitrary Python with your privileges. GDB will not do that for a script it merely found on disk, and the wrapper vouches for exactly one directory, the toolchain's own. That split also explains the common failure: everything that makes the printers appear happens outside the binary, so a correct build can still show raw values.

  • Why does rust-gdb need the auto-load safe path at all, if it already passes `--directory`?
    They solve different checks. `--directory` puts etc on the source search path, which is where GDB looks for a script file named in `.debug_gdb_scripts`. Finding the file is not enough: GDB auto-loads such a script only when its location is in the auto-load safe path, so the wrapper adds etc there with `-iex` before the program is loaded.
  • How do you get the Rust printers when debugging Cortex-M firmware with a cross GDB?
    Point `RUST_GDB` at the cross GDB so the wrapper still sets up the paths, then `source` `gdb_load_rust_pretty_printers.py` from the toolchain's etc directory. rustc emits no `.debug_gdb_scripts` section for `thumbv7em-none-eabihf`, so nothing in the ELF asks GDB to load the printers by itself.

  • The pretty-printers are taken from the toolchain that built the binary
  • rust-gdb patches GDB's binary to understand Rust collections
  • Any type named Vec gets the Vec printer, whatever crate defines it
  • Every Rust target embeds the .debug_gdb_scripts section
  • substitute-path downloads std sources when they are missing