Skip to content

debugger: stabilize trim-paths unremap file loading #163910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
weihanglo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

debugger: stabilize trim-paths unremap file loading #163910

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions src/bootstrap/src/core/build_steps/dist.rs
View file
Open in desktop

@weihanglo weihanglo Oct 25, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In reply to @Mark-Simulacrum's #163910 (comment):

Did we look at what other ecosystems are doing in this space? I'm loosely aware that Javascript has sourcemaps for a similar-ish goal -- though I think those are commonly embedded in the file itself as a comment?

We looked at remap part, but not too much in the unremap part. Some goals here are binary reproducibility and local developer experience so embedding any absolute paths is not a "base" solution here. Could be extensions of course.

The other thing to compare is go's -trimpath flag. Go is a bit different as every module has a clear identity even for local ones, though go doesn't have "unremap" concept, and mostly relies on their debugger to guess and requires kinda the exact checkout layout for finding sources.

As for JavaScript sourcemaps URL, if they don't contain absolute maps across builds and is reproducible enough we could definitely extend them in the unremap files, or embed them in the object I think.

With regards to the location we look for the file, is the relative location the right approach? How does that interact with (IIUC) Cargo's goal to not uplift artifacts that aren't intended for user consumption?

Cargo only put trim-paths aside final binaries, like dSYM or PDB files. This doesn't seem to be an issue.

Is there some way for a user to more explicitly specify the path (e.g., RUST_{GDB,LLDB}_TRIM_PATHS=/path/to/file.json), and/or should there be?

Not sure if we need to, but users can set their own substitution rules if needed. Doesn't need to tie to the unremap files.

Does our gdb/lldb integration allow for fetching the file from debuginfod servers (does that make sense conceptually)?

Not yet I believe, see this and this. And there is one real gap of the current remap rules: the local workspace source is mapped to path relative to workspace root (DW_AT_comp_dir = "."). The reason of this decision is a tradeoff of local debug experience. With relative paths users can use debugger without any substitution rules for their local packages.

Related to the debuginfod aspect, do we expect any compatibility and/or performance issues from using JSON here? How big are these files?

Small enough (for cargo itself is 462 bytes). JSON is parsed once per object file or module load.

As aforementioned the current remap rules may not be useful for debuginfod. Need some pre/post-process. And anyway debuginfod is not supported at this moment in rustc and related tools. However, a future extension is that Cargo allows extending and customizing the remap rules, which we kinda have one for bootstrap for remapping to /rustc/<sha>.

Maybe the right way to summarize all of that is that it's not entirely clear to me the scope of this stabilization: is this just stabilizing that our debugger scripts will load such a file, but not guaranteeing much else? E.g., where / who owns FCP on the file format and documentation for it (did Cargo already do that)?

True, debugger scripts load them, though the v1 schema is stabilized but exact remap prefixes is subject to change, and adding fields later doesn't break the compatibility per Cargo JSON policy (that one is more for cargo metadata but it is in general our attitude towards JSON outputs). And yes Cargo did an FCP. See the doc and the links in the updated PR description.

View changes since the review

@Mark-Simulacrum Mark-Simulacrum Oct 25, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I think that answers my questions enough that I'm comfortable checking a box (done). It seems plausible that we'll want/need a v2 format (or extra fields in v1) for some of the goals based on it, if I'm understanding right, but that doesn't seem like a blocker for this stabilization.

Original file line number Diff line number Diff line change
Expand Up @@ -776,9 +776,7 @@ impl Step for DebuggerScripts {
cp_debugger_script("gdb_load_rust_pretty_printers.py");
cp_debugger_script("gdb_lookup.py");
cp_debugger_script("gdb_providers.py");
if builder.sess.unstable_features() {
cp_debugger_script("gdb_trim_paths.py");
}
cp_debugger_script("gdb_trim_paths.py");

// lldb debugger scripts
builder.install(
Expand All @@ -789,9 +787,7 @@ impl Step for DebuggerScripts {

cp_debugger_script("lldb_lookup.py");
cp_debugger_script("lldb_providers.py");
if builder.sess.unstable_features() {
cp_debugger_script("lldb_trim_paths.py");
}
cp_debugger_script("lldb_trim_paths.py");
}
}

Expand Down
8 changes: 4 additions & 4 deletions src/etc/rust-gdb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ set -- \
-iex "set substitute-path /rustc/$RUSTC_COMMIT_HASH $RUSTC_SYSROOT/lib/rustlib/src/rust" \
"$@"

# Unstable (nightly-only) trim-paths feature, activated only if
# - RUST_GDB_TRIM_PATHS=unstable is set
# - and if the python file is present (only shipped on nightly)
# Load Cargo trim-paths unremap files beside each loaded binary.
#
# Set RUST_GDB_TRIM_PATHS=0 to disable this feature.
GDB_TRIM_PATHS="$GDB_PYTHON_MODULE_DIRECTORY/gdb_trim_paths.py"
if [ "${RUST_GDB_TRIM_PATHS:-}" = "unstable" ] && [ -f "$GDB_TRIM_PATHS" ]; then
if [ "${RUST_GDB_TRIM_PATHS:-}" != "0" ] && [ -f "$GDB_TRIM_PATHS" ]; then
set -- -x "$GDB_TRIM_PATHS" "$@"
fi

Expand Down
8 changes: 4 additions & 4 deletions src/etc/rust-lldb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,11 @@ fi

script_import="command script import \"$RUSTC_SYSROOT/lib/rustlib/etc/lldb_lookup.py\""

# Unstable (nightly-only) trim-paths feature, activated only if
# - RUST_LLDB_TRIM_PATHS=unstable is set
# - and if the python file is present (only shipped on nightly)
# Load Cargo trim-paths unremap files beside each loaded binary.
#
# Set RUST_LLDB_TRIM_PATHS=0 to disable this feature.
LLDB_TRIM_PATHS="$RUSTC_SYSROOT/lib/rustlib/etc/lldb_trim_paths.py"
if [ "${RUST_LLDB_TRIM_PATHS:-}" = "unstable" ] && [ -f "$LLDB_TRIM_PATHS" ]; then
if [ "${RUST_LLDB_TRIM_PATHS:-}" != "0" ] && [ -f "$LLDB_TRIM_PATHS" ]; then
set -- --one-line-before-file "command script import \"$LLDB_TRIM_PATHS\"" "$@"
fi

Expand Down
Loading