fix(trim-paths): unambiguous and reversible remap rules by weihanglo · Pull Request #17302 · rust-lang/cargo

weihanglo · 2026-08-03T03:48:33Z

What does this PR try to resolve?

Part of #12137.
This was discussed during 2026 all-hands
rust-lang/all-hands-2026#38 (comment)

Every remap rule now substitutes a distinct prefix
instead of stripping the source prefix to an empty string.
This makes the source remap more unambiguous and reversible.

Category	From	To
Sysroot	`<sysroot>/lib/rustlib/src/rust`	`/rustc/<commit-hash>`
Registry dep	`~/cargo/registry/src/<registry-dir>`	`/cargo/registry/<registry-id>`
Git dep	`~/cargo/git/checkouts/<repo-dir>/<rev-dir>`	`/cargo/git/<git-source-id>/<rev>`
Workspace	`<workspace-root>`	`.` (workspace-relative)
Path dep outside ws	`<pkg-root>`	`/cargo/path/<name>-<version>`
Vendored	`<pkg-root>` (by file location)	workspace or path rules above
Build directory	`<build-dir>`	`/cargo/build-dir`

How to test and review this PR?

Commit by commit.

Old tests show the remap behavior changes.
New tests verify vendored dependencies are covered.
Docs are updated.

The local workspace remap rule and the build-dir rule both match `OUT_DIR` paths. And since the `--remap-path-prefix` is order-dependent, it is worth a test. The build-dir rule is passed last so paths should remapped to `/cargo/build-dir`.

Cover vendored registry and git dependencies, both inside and outside the workspace directory.

Part of <rust-lang#12137>. This was discussed during 2026 all-hands rust-lang/all-hands-2026#38 (comment) Every remap rule now substitutes a distinct prefix instead of stripping the source prefix to an empty string. This makes the source remap more unambiguous and reversible. | Category | From | To | |---------------------|----------------------------------------------|------------------------------------| | Sysroot | `<sysroot>/lib/rustlib/src/rust` | `/rustc/<commit-hash>` | | Registry dep | `~/cargo/registry/src/<registry-dir>` | `/cargo/registry/<registry-id>` | | Git dep | `~/cargo/git/checkouts/<repo-dir>/<rev-dir>` | `/cargo/git/<git-source-id>/<rev>` | | Workspace | `<workspace-root>` | `.` (workspace-relative) | | Path dep outside ws | `<pkg-root>` | `/cargo/path/<name>-<version>` | | Vendored | `<pkg-root>` (by file location) | workspace or path rules above | | Build directory | `<build-dir>` | `/cargo/build-dir` |

rustbot · 2026-08-03T03:48:37Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @epage, @weihanglo
@epage, @weihanglo expanded to epage, weihanglo

epage · 2026-08-03T11:58:14Z

And we are free to change these ids between versions still?

weihanglo · 2026-08-03T12:11:31Z

And we are free to change these ids between versions still?

My read is that people should use unremap files to unremap them. It also has with a rust_version field attached so it is possible for them to refetch deps or tweak unremap files.

Regardless, today's depinfo files are written with absolute paths and not immune with those ID changes either.

Update cargo submodule 21 commits in 7c83d4cc0953b81d823e47d640c64da9b8bd4fac..c79e8f89441b3e73d6d65d125c0c745792808c74 2026-07-29 21:34:53 +0000 to 2026-08-04 19:17:33 +0000 - fix(diag): Ensure diagnostic titles work without snippets (rust-lang/cargo#17304) - refactor: Remove unnecessary mut in sources (rust-lang/cargo#17305) - feat(trim-paths): emit unremap files for final artifacts (rust-lang/cargo#17303) - fix: prevent panic when `package.build` is empty (rust-lang/cargo#17268) - Add a suggestion when adding `[lints]` to a workspace to use `[workspace.lints]` instead (rust-lang/cargo#17300) - chore(deps): update embarkstudios/cargo-deny-action action to v2.1.1 (rust-lang/cargo#17291) - refactor: move sysroot lookup to GlobalContext (rust-lang/cargo#17276) - fix(trim-paths): unambiguous and reversible remap rules (rust-lang/cargo#17302) - Avoid parsing unchanged lockfiles (rust-lang/cargo#17301) - Remove unnecessary to_path_buf (rust-lang/cargo#17295) - chore(deps): update cargo-semver-checks to v0.50.0 (rust-lang/cargo#17297) - chore(deps): update actions/checkout action to v6.1.0 (rust-lang/cargo#17290) - Remove unnecessary return at end of functions (rust-lang/cargo#17292) - make __CARGO_TEST_FORCE_ARGFILE available in distributed builds (rust-lang/cargo#17293) - Fix manual_readme lint for lower-priority README files (rust-lang/cargo#17208) - fix(git): make checkout names independent of git config (rust-lang/cargo#17289) - fix(diag): Rename redundant_readme to manual_readme (rust-lang/cargo#17288) - Remove redundant double call .to_string() (rust-lang/cargo#17286) - fix(completions): complete paths for cargo run arguments (rust-lang/cargo#17284) - test(git): exercise multi git revision lockfile (rust-lang/cargo#17279) - add context to lints documentation (rust-lang/cargo#17273) r? ghost

*[View all comments](https://triagebot.infra.rust-lang.org/gh-comments/rust-lang/cargo/pull/17488)* # Stabilization report: `profile.trim-paths` Resolves rust-lang#12137 Resolves rust-lang/rust#111540 RFC: <https://rust-lang.github.io/rfcs/3127-trim-paths.html> ## What is stabilized The rustc side `--remap-path-scope` was already stabilized in Rust 1.95 via rust-lang/rust#147611 This stabilizes the Cargo side: * `profile.<name>.trim-paths = "none" | "object" | "all"` in both manifest and config * The remap rules of how Cargo passes `--remap-path-{prefix,scope}`. The exact remap prefixes still stay unspecified. * The unremap file `<artifact>.trim-paths.json` (schema v1), which is emitted beside final artifacts when debuginfo is on. * `CARGO_TRIM_PATHS_SCOPE` and `CARGO_TRIM_PATHS_REMAP` for build scripts. When this is merged and sync in rust-lang/rust, we'll also stabilize * The `rust-gdb` and `rust-lldb` unremap loaders. `RUST_GDB_TRIM_PATHS=unstable` and `RUST_LLDB_TRIM_PATHS=unstable` are not needed anymore. See doc for details: https://github.com/rust-lang/cargo/blob/8814ead110e36ed8fdcf1fdd4009baf82bd78523/doc/book/src/reference/unstable.md?plain=1#L1441-L1645 ## What is not stabilized / included * This doesn't guarantee full sanitization. It is a best-effort feature. * Other `--remap-path-scope` values in rustc (`macro`, `diagnostics`, `debuginfo`, `coverage`), boolean values, and comma-separated list options. These are removed in rust-lang#17432. They can come back later when needed. * A default trim-path value for built-in profiles. RFC originall proposed to set `release` to `"object"`. This is left for future when this is more adopted and battle-tested. We have loose stability guarantee for changing profile settings anyway. * `__CARGO_RUSTC_BOOTSTRAP_WS_REMAP`. This stays as an internal thing between rustc bootstrap and cargo (see rust-lang#17349, rust-lang#17366) * Doctest remapping and `documentation` scope. This will be integrated in the future incrementally when those scopes and features are stable. * The exact remap prefixes are unspecified as documented. However, in practice, rustc bootstrap and debugger depend on the stabilized shape, so any change needs careful coordination with them. * Unremap files for artifact deps: deferred, non-blocking. * `build-rs` API for the two build script variables: deferred, non-blocking. * If there are new kinds of artifacts, we can decide whether to remap freely. ### Doors closed * The trim-paths profile key name, its shape, and its options. * The unremap file name suffix `.trim-paths.json` and the v1 schema. * The environment variable `CARGO_TRIM_PATHS_SCOPE` and `CARGO_TRIM_PATHS_REMAP`. ## Post-RFC changes * rustc removed `split-debuginfo` scopes, and Cargo followed and stopped caring split debuginfo. * The RFC remapped the current package to relative paths and every dependency to `<name>-<version>`. In rust-lang#17302 we chose workspace members relative remap, so debuggers resolve workspace sources with zero configuration. The RFC worried that relative paths only work when running from the right directory, and symbolication tools need a second process for joining workspace relative paths. THe unremap file has `workspace_root`, so the join is fairly mechanical. Remap prefixes are unspecified anyway, so we can still change if it turns out not ideal. * The unremap file is new (introduced in rust-lang#17303), for helping debugging find sources, as well as our keeping remap rules unspecified. The RFC had no answer about this. * `CARGO_TRIM_PATHS_REMAP` build script env is new. It lets build scripts forward the same rules to C/C++ compilers to flags like `-fmacro-prefix-map`. `cc-rs` has integrated that since rust-lang/cc-rs#1794. ## Feedback * rustc bootstrap builds the compiler and standard library with `trim-paths` via rust-lang/rust#161049 since 2026-09-02. This exercises the sysroot remap and the workspace prefix override in rust-lang/rust CI. * `cc-rs` forwards the remap rules to C/C++ compiler since 1.3.0: <https://github.com/rust-lang/cc-rs/releases/tag/cc-v1.3.0> * Zulip thread: [#t-cargo > stabilization plan for &rust-lang#96;-Ztrim-paths&rust-lang#96;](https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/stabilization.20plan.20for.20.60-Ztrim-paths.60/with/622955580) * Call for testing posted on 2026-09-09 * rust-lang#12137 (comment) * Included in TWiR issue 669 <https://this-week-in-rust.org/blog/2026/09/16/this-week-in-rust-669/> ## Known limitations This sanitization is best-effort. See * rustc: <https://doc.rust-lang.org/rustc/remap-source-paths.html#caveats-and-limitations> * Cargo: <https://github.com/rust-lang/cargo/blob/8814ead110e36ed8fdcf1fdd4009baf82bd78523/doc/book/src/reference/unstable.md?plain=1#L1603-L1626> ## Implementation ### History | PR | Merged | Title | |--------|------------|-------------------------------------------------| | rust-lang#12625 | 2023-10-31 | implement RFC 3127 `-Ztrim-paths` | | rust-lang#12900 | 2023-10-31 | set env `CARGO_TRIM_PATHS` for build scripts | | rust-lang#12908 | 2023-11-02 | merge `trim-paths` from different profiles | | rust-lang#13118 | 2023-12-06 | assert `OSO` and `SO` cannot be trimmed | | rust-lang#14389 | 2024-08-12 | rustdoc supports trim-paths for diagnostics | | rust-lang#14908 | 2024-12-09 | use Path::push to construct remap-path-prefix | | rust-lang#14917 | 2024-12-11 | use stable hash from rustc-stable-hash | | rust-lang#15614 | 2025-06-02 | remap all paths to `build.build-dir` | | rust-lang#15621 | 2025-06-02 | enable more tests for windows-msvc | | rust-lang#16536 | 2026-01-21 | `--remap-path-scope` stabilized in 1.95-nightly | | rust-lang#17104 | 2026-06-15 | emit `CARGO_TRIM_PATHS_REMAP` for build.rs | | rust-lang#17221 | 2026-07-15 | exercise GDB on windows-gnu | | rust-lang#17302 | 2026-08-03 | unambiguous and reversible remap rules | | rust-lang#17303 | 2026-08-04 | emit unremap files for final artifacts | | rust-lang#17326 | 2026-08-07 | exercise unremap files with debuggers | | rust-lang#17338 | 2026-08-08 | `/cargo/deps` fallback sources | | rust-lang#17337 | 2026-08-10 | workspace remap under -Zroot-dir | | rust-lang#17349 | 2026-08-11 | honor workspace prefix override from env | | rust-lang#17366 | 2026-08-26 | custom workspace-relative member paths remap | | rust-lang#17424 | 2026-09-02 | remove default scope from release profile | | rust-lang#17425 | 2026-09-02 | docs: add limitations and polish | | rust-lang#17432 | 2026-09-04 | limit options to `none\|object\|all` | | rust-lang#17476 | 2026-09-15 | unremap file in one JSON doc | | rust-lang#17491 | 2026-09-21 | `build-rs` support | ### Test coverage * Remap for each dependency kind * `"object"` with every `split-debuginfo` mode * `"all"` diagnostics remapping for rustc and rustdoc * The new build-script environment variables. * Real world debugger exercises with GDB, LLDB, and CDB * unremap files with rebuilds, `cargo clean`, JSON messages * rustc bootstrap workspace prefix override * `-Zbuild-std` backtraces show `/rustc/<hash>` paths ## Follow-ups after stabilization * [ ] Revisit reproducibility issues, such as * rust-lang#13586 * rust-lang#15122 * rust-lang#7645 * rust-lang#10915 Absolute paths of workspace and `CARGO_HOME` still get into `-Cmetadata`/`-Cextra-filename`/fingerprints. With `trim-paths = "object"` we might be able to also trim paths in those places. * [ ] Revisit a new default for built-in profiles e.g., `release` * [ ] In rust-lang/rust stabilize loader logic in `src/etc/gdb_trim_paths.py` and `src/etc/lldb_trim_paths.py` * [x] A new issue for `build-rs` adding `CARGO_TRIM_PATHS_SCOPE` and `CARGO_TRIM_PATHS_REMAP` support * [ ] A new issue for supporting doctest remapping and documentation scope. * [ ] Track unremap files support in artifact dependencies tracking issue --- 🤖 LLM disclosure: impl history was generated. heading was generated. meats are human-written.

weihanglo added 5 commits August 2, 2026 23:39

refactor(trim-paths): extract remap into own module

c0102f5

test(trim-paths): cover vendored dependencies

bf4a306

Cover vendored registry and git dependencies, both inside and outside the workspace directory.

docs(trim-paths): unambiguous and reversible remap rules

2a8b6fd

rustbot assigned epage Aug 3, 2026

rustbot added A-build-execution Area: anything dealing with executing the compiler A-build-scripts Area: build.rs scripts A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 3, 2026

weihanglo mentioned this pull request Aug 3, 2026

feat(trim-paths): emit unremap files for final artifacts #17303

Merged

epage approved these changes Aug 3, 2026

View reviewed changes

epage added this pull request to the merge queue Aug 3, 2026

Merged via the queue into rust-lang:master with commit 5ca823a Aug 3, 2026
29 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 3, 2026

rustbot mentioned this pull request Aug 3, 2026

refactor: move sysroot lookup to GlobalContext #17276

Merged

This was referenced Aug 4, 2026

Update cargo submodule rust-lang/rust#160527

Merged

Tracking Issue for trim-paths RFC 3127 #12137

Closed

trim-paths: Remap rules for different dependency kinds #13171

Closed

weihanglo deleted the remap-rules branch August 5, 2026 11:25

rustbot added this to the 1.99.0 milestone Aug 6, 2026

weihanglo added the A-trim-paths Area: path sanitization in resulting binaries label Aug 6, 2026

weihanglo mentioned this pull request Sep 18, 2026

feat(trim-paths): stabilize profile.trim-paths #17488

Merged

3 of 6 tasks

Navigation Menu

Repository navigation

fix(trim-paths): unambiguous and reversible remap rules - #17302

fix(trim-paths): unambiguous and reversible remap rules#17302
epage merged 5 commits into
rust-lang:masterfrom
weihanglo:remap-rules

weihanglo commented Aug 3, 2026

Uh oh!

rustbot commented Aug 3, 2026

Uh oh!

epage commented Aug 3, 2026

Uh oh!

weihanglo commented Aug 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

weihanglo commented Aug 3, 2026

What does this PR try to resolve?

How to test and review this PR?

Uh oh!

rustbot commented Aug 3, 2026

Uh oh!

epage commented Aug 3, 2026

Uh oh!

weihanglo commented Aug 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants