fix(trim-paths)!: limit options to `none|object|all` by weihanglo · Pull Request #17432 · rust-lang/cargo

weihanglo · 2026-09-03T15:36:34Z

What does this PR try to resolve?

This limits profile trim-paths options to only none, object, and all.
For other scopes and boolean values, we can add it in the future when needed.

This is a stabilization preparation for -Ztrim-paths.
See #12137 (comment).

How to test and review this PR?

Also rewrote the profile trim-paths doc a bit but not extremely satisfied.
Please help proofread.

rustbot · 2026-09-03T15:36:41Z

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-09-03T16:57:43Z

+    > [!NOTE]
+    > For forward compatibility,
+    > build scripts should accept a comma-separated list of scopes.
 * `CARGO_TRIM_PATHS_REMAP` --- The `<from>=<to>` path remap pairs Cargo passes to the compiler,


Aside: do we support this yet in build-rs?

View changes since the review

Sure! I am still thinking about a reasonable API.

My hope is that popular helper build dep dependencies use them, like cc-rs which already supports. Application build scripts likely don't need this. cc-rs likely has covered 95% of the use cases (including cmake-rs which takes cc-rs as a dependency).

Tracked in #12137

epage · 2026-09-03T16:58:48Z

-`trim-paths` is a profile setting which enables and controls the sanitization of file paths in build outputs.
-It takes the following values:
-
- `"none"` --- disable path sanitization
- `"macro"` --- sanitize paths in the expansion of `std::file!()` macro.
-    This is where paths in embedded panic messages come from
- `"diagnostics"` --- sanitize paths in printed compiler diagnostics
- `"object"` --- sanitize paths in compiled executables or libraries
- `"all"` --- sanitize paths in all possible locations
+The `trim-paths` option controls path sanitization in build outputs.
+It uses rustc's [`--remap-path-scope`] to control the scope where paths are sanitized,
+while Cargo supplies the path-prefix mappings described in the [remapping rules].

-It also takes an array with the combinations of `"macro"`, `"diagnostics"`, and `"object"`.
+The valid options are `"none"`, `"object"`, and `"all"`.
+`"none"` disables sanitization.
+The other values select the corresponding rustc remapping scope.


This looks like we are removing the docs that distinguish between object and all

View changes since the review

I tried to minimize this to avoid duplicating docs on rustc side. Oour profile doc is mixed. For strip and split-debuginfo we don't have docs for each, while for debug and opt-level we do enumerate them. Do you think this worth explicit docs and also talking about use cases in Cargo doc?

Okay, after reading other comments

fix(trim-paths)!: limit options to none|object|all #17432 (comment)

fix(trim-paths)!: limit options to none|object|all #17432 (comment)

I think we should have some minimal docs for each options, which I think can address most of doc issues.

Updated. I hope that clarifies things.

epage · 2026-09-03T16:59:31Z

-    This is where paths in embedded panic messages come from
- `"diagnostics"` --- sanitize paths in printed compiler diagnostics
- `"object"` --- sanitize paths in compiled executables or libraries
- `"all"` --- sanitize paths in all possible locations


Does r-a or any other tool need a heads up that with all, diagnostics won't point to valid files?

View changes since the review

We should document issue and perhaps put a warning as precaution. And yes good idea when stabilizing we should let tool authors know about it

epage · 2026-09-03T17:00:18Z

+while Cargo supplies the path-prefix mappings described in the [remapping rules].

-It also takes an array with the combinations of `"macro"`, `"diagnostics"`, and `"object"`.
+The valid options are `"none"`, `"object"`, and `"all"`.


If we're looking to drop things, what are the use cases for having both object and all?

View changes since the review

object, like you have mentioned, preserves certain debuggability and local development experience.

all is more fore hermetic builds to sanitize as many locations as possible. One of the biggest difference is metadata output. Metadadta in in dylib and proc-macors are only remapped in the all scope. When I test this with some caching service, without remapping all for proc-macros, the artifact checksum mismatches and cache missed. See rust-lang/rust#159621

See <https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/stabilization.20plan.20for.20.60-Ztrim-paths.60/near/621134225>

rustbot · 2026-09-03T18:55:10Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

Update cargo submodule 9 commits in b2e9d5f9db3fb1c454ab84f10c16508984a266e2..3c0b534756e166d12eb9fd2e1abfe5b42ac6101e 2026-09-02 14:49:16 +0000 to 2026-09-04 17:03:10 +0000 - fix(trim-paths)!: limit options to `none|object|all` (rust-lang/cargo#17432) - fix(git): Apply pr hint to git-fetch-with-cli (rust-lang/cargo#17437) - fix(git): Make PR dep note cloer to our style guide (rust-lang/cargo#17436) - docs: clarify cargo vendor source config option (rust-lang/cargo#17435) - docs(trim-paths): workspace remap begins with `.` (rust-lang/cargo#17433) - docs: Switch from "target triple" to "target tuple" (rust-lang/cargo#17430) - docs(trim-paths): add limitations and polish (rust-lang/cargo#17425) - fix(git): Simplify error message (rust-lang/cargo#17429) - chore(deps): update rust crate base64 to 0.23.0 (rust-lang/cargo#17418)

Cargo dropped the boolean forms of the profile `trim-paths` setting in rust-lang/cargo#17432 as stabilization preparation, so nightlies from 2026-09-04 refuse to load the config and CI fails before the first build step. `"all"` is the value `true` used to mean.

*[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 the A-trim-paths Area: path sanitization in resulting binaries label Sep 3, 2026

rustbot assigned epage Sep 3, 2026

rustbot added A-documenting-cargo-itself Area: Cargo's documentation A-manifest Area: Cargo.toml issues S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 3, 2026

weihanglo mentioned this pull request Sep 3, 2026

Tracking Issue for trim-paths RFC 3127 #12137

Closed

14 of 19 tasks

epage reviewed Sep 3, 2026

View reviewed changes

weihanglo added 3 commits September 3, 2026 14:55

fix(trim-paths)!: remove boolean profile values

c4cec46

See <https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/stabilization.20plan.20for.20.60-Ztrim-paths.60/near/621134225>

chore: bump cargo-util-schemas to 0.15.0

d7c51f0

fix(trim-paths)!: limit options to none|object|all

a966ddc

weihanglo force-pushed the only-object-scope branch from c72071f to 0480619 Compare September 3, 2026 18:55

docs(trim-paths)!: limit options to none|object|all

e7c7688

weihanglo force-pushed the only-object-scope branch from 0480619 to e7c7688 Compare September 3, 2026 19:02

epage approved these changes Sep 4, 2026

View reviewed changes

epage added this pull request to the merge queue Sep 4, 2026

Merged via the queue into rust-lang:master with commit 3c0b534 Sep 4, 2026
30 checks passed

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

weihanglo deleted the only-object-scope branch September 4, 2026 17:44

weihanglo mentioned this pull request Sep 4, 2026

Update cargo submodule rust-lang/rust#162314

Merged

rustbot added this to the 1.100.0 milestone Sep 5, 2026

weihanglo mentioned this pull request Sep 18, 2026

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

Merged

3 of 6 tasks

Conversation

weihanglo commented Sep 3, 2026

What does this PR try to resolve?

How to test and review this PR?

Uh oh!

rustbot commented Sep 3, 2026

Uh oh!

epage Sep 3, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

epage Sep 3, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

epage Sep 3, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

epage Sep 3, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

rustbot commented Sep 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

epage Sep 3, 2026 •

edited by rustbot

Loading

epage Sep 3, 2026 •

edited by rustbot

Loading

epage Sep 3, 2026 •

edited by rustbot

Loading

epage Sep 3, 2026 •

edited by rustbot

Loading