From 26454bdc4899d46b1d053f3e410ced1e2792676a Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 2 Sep 2026 00:26:30 -0400 Subject: [PATCH 1/5] docs(trim-paths): refer compiler --remap-path-scope doc --- doc/book/src/reference/unstable.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md index 5d60d9d8873..d05811767e4 100644 --- a/doc/book/src/reference/unstable.md +++ b/doc/book/src/reference/unstable.md @@ -1539,11 +1539,10 @@ trim-paths = "all" trim-paths = ["object", "diagnostics"] ``` -The `object` setting sanitizes only the paths in emitted executable or library files. -It always affects paths from macros such as panic messages, and in debug information only if they will be embedded together with the binary -(the default on platforms with ELF binaries, such as Linux and windows-gnu), -but will not touch them if they are in separate files (the default on Windows MSVC and macOS). -But the paths to these separate files are sanitized. +For more information about each scope, +see rustc's documentation on [`--remap-path-scope`]. + +[`--remap-path-scope`]: ../../rustc/remap-source-paths.html#--remap-path-scope If `trim-paths` is not `none` or `false`, then the following paths are sanitized if they appear in a selected scope: From c5712b605d19d22c19dcec700decc98dc75d64dd Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 2 Sep 2026 00:26:30 -0400 Subject: [PATCH 2/5] docs(trim-paths): remampping rules section heading --- doc/book/src/reference/unstable.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md index d05811767e4..a8dfb723d3e 100644 --- a/doc/book/src/reference/unstable.md +++ b/doc/book/src/reference/unstable.md @@ -1544,7 +1544,16 @@ see rustc's documentation on [`--remap-path-scope`]. [`--remap-path-scope`]: ../../rustc/remap-source-paths.html#--remap-path-scope -If `trim-paths` is not `none` or `false`, then the following paths are sanitized if they appear in a selected scope: +##### Remapping rules + +The exact remap path prefixes are unspecified and may change across Cargo versions. +Tools that map paths embedded in artifacts back to local sources +should consume [unremap files] instead of interpreting these prefixes. + +[unremap files]: #unremap-files + +If `trim-paths` is not `"none"` or `false`, +then the following paths are sanitized if they appear in a selected scope: 1. Path to the source files of the standard and core library (sysroot) will begin with `/rustc/`, e.g. `/home/username/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/result.rs` -> @@ -1576,16 +1585,12 @@ otherwise like path dependencies. When a path to the source files of the standard and core library is *not* in scope for sanitization, the emitted path will depend on if `rust-src` component is present. If it is, then some paths will point to the copy of the source files on your file system; -if it isn't, then they will show up as `/rustc/[rustc commit hash]/library/...` +if it isn't, then they will show up as `/rustc//library/...` (just like when it is selected for sanitization). Paths to all other source files will not be affected. This will not affect any hard-coded paths in the source code, such as in strings. -The exact remap path prefixes are not stable across Cargo versions. -Tools that map paths embedded in artifacts back to local sources -should consume unremap files instead of interpreting these prefixes. - ##### Unremap files When the `object` scope is active and debuginfo is enabled, From 5a47293aa6c6d12065d1025a314df031a9374266 Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 2 Sep 2026 00:26:30 -0400 Subject: [PATCH 3/5] docs(trim-paths): talk about limitations --- doc/book/src/reference/unstable.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md index a8dfb723d3e..b65fb7a430c 100644 --- a/doc/book/src/reference/unstable.md +++ b/doc/book/src/reference/unstable.md @@ -1589,8 +1589,6 @@ if it isn't, then they will show up as `/rustc//library/...` (just like when it is selected for sanitization). Paths to all other source files will not be affected. -This will not affect any hard-coded paths in the source code, such as in strings. - ##### Unremap files When the `object` scope is active and debuginfo is enabled, @@ -1630,6 +1628,31 @@ it includes absolute paths of your system, so there is no artifact privacy guarantee. You might want to exclude `*.trim-paths.jsonl` files when distributing artifacts. +##### Limitations + +`trim-paths` supports remapping source path prefixes as a best effort. +Linkers may add paths that rustc cannot remap. +See [the limitations section][remap-limitation] on rustc's documentation for more. + +For example, on macOS, +linkers generate OSO entries containing absolute paths to object files +when debuginfo is enabled. +The following profile settings keep these paths out of the executable +while preserving debuginfo in a separate dSYM bundle: + +```toml +[profile.release] +debug = true +trim-paths = "object" +split-debuginfo = "packed" +strip = "debuginfo" +``` + +The dSYM bundle can be used for debugging, +but it still contains absolute paths. + +[remap-limitation]: ../../rustc/remap-source-paths.html#caveats-and-limitations + #### Environment variable *as a new entry of ["Environment variables Cargo sets for build scripts"](./environment-variables.md#environment-variables-cargo-sets-for-crates)* From 2198a00386686152e8b35a3fbefe30de57572b9e Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 2 Sep 2026 01:22:15 -0400 Subject: [PATCH 4/5] docs(trim-paths): remove compiler remap source internal logic This is implementation details for better diagonstic remap that is not really meaning for cargo users directly. --- doc/book/src/reference/unstable.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md index b65fb7a430c..0fb3e561d0c 100644 --- a/doc/book/src/reference/unstable.md +++ b/doc/book/src/reference/unstable.md @@ -1582,13 +1582,6 @@ are sanitized by their file location instead, like workspace paths when inside the workspace directory, otherwise like path dependencies. -When a path to the source files of the standard and core library is *not* in scope for sanitization, -the emitted path will depend on if `rust-src` component is present. -If it is, then some paths will point to the copy of the source files on your file system; -if it isn't, then they will show up as `/rustc//library/...` -(just like when it is selected for sanitization). -Paths to all other source files will not be affected. - ##### Unremap files When the `object` scope is active and debuginfo is enabled, From e7464bba1931b434f8f109b0e6a846a09377e6bf Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 2 Sep 2026 14:29:25 -0400 Subject: [PATCH 5/5] docs(trim-paths): mention debugger wrappers support --- doc/book/src/reference/unstable.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md index 0fb3e561d0c..c95ea1d97ba 100644 --- a/doc/book/src/reference/unstable.md +++ b/doc/book/src/reference/unstable.md @@ -1589,6 +1589,12 @@ Cargo writes an unremap file beside each final artifact. The file is aimed at helping debuggers substitute sanitized paths back to local ones, e.g., via GDB's `set substitute-path` or LLDB's `target.source-map`. +The Rust toolchain provides `rust-gdb` and `rust-lldb` wrappers, +which can load unremap files automatically. +This integration is currently unstable and available only in nightly toolchains. +To enable it, +set `RUST_GDB_TRIM_PATHS=unstable` or `RUST_LLDB_TRIM_PATHS=unstable` respectively. + The unremap file name ends with `.trim-paths.jsonl`. For example, your `my-app` executable would come with an unremap file named