Skip to content

docs(trim-paths): add limitations and polish - #17425

Merged
epage merged 5 commits into
rust-lang:masterfrom
weihanglo:trim-paths-docs
Sep 2, 2026
Merged

docs(trim-paths): add limitations and polish#17425
epage merged 5 commits into
rust-lang:masterfrom
weihanglo:trim-paths-docs

Conversation

@weihanglo

@weihanglo weihanglo commented Sep 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

What does this PR try to resolve?

This doc polish is a stabilization preparation.

See #12137 (comment)

How to test and review this PR?

This is stacked on top of #17424 to minimize merge conflict. Please review from c99bbf2

mdbook serve doc/book

@weihanglo weihanglo added the A-trim-paths Area: path sanitization in resulting binaries label Sep 2, 2026
@rustbot rustbot added A-documenting-cargo-itself Area: Cargo's documentation A-profiles Area: profiles S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 2, 2026
@rustbot

rustbot commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

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

@weihanglo

weihanglo commented Sep 2, 2026

Copy link
Copy Markdown
Member Author

cc @Urgau, if you'd also like to take a look. I generally want to mostly refer to rustc docs 😆.

epage
epage reviewed Sep 2, 2026
View reviewed changes
Comment thread doc/book/src/reference/unstable.md Outdated
@rustbot

This comment has been minimized.

Sign in to view
Urgau
Urgau reviewed Sep 2, 2026
View reviewed changes

@Urgau Urgau left a comment •
edited by rustbot
Loading

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.

Not much to say, this looks good to me as well.

View changes since this review

Comment thread doc/book/src/reference/unstable.md
Comment on lines 1520 to 1527
It takes the following values:

- `"none"` and `false` --- 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"` and `true` --- sanitize paths in all possible locations

@Urgau Urgau Sep 2, 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.

I don't know if this list is intended to be the same as rustc, but if it's the case then it's missing the coverage and debuginfo scopes. If it's intended to diverge, it should maybe be mentioned that it's only a subset.

@weihanglo weihanglo Sep 2, 2026

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.

Good point. I avoided touching this right now at this moment as we may want to stabilize a subset.

We are discussing it in #t-cargo > stabilization plan for `-Ztrim-paths` (though no discussions yet)

@Urgau Urgau Sep 2, 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.

We are discussing it in #t-cargo > stabilization plan for -Ztrim-paths (though no discussions yet)

Replied the in the Zulip thread.

Comment thread doc/book/src/reference/unstable.md
Comment thread doc/book/src/reference/unstable.md Outdated
@rustbot

rustbot commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

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.

@epage
epage added this pull request to the merge queue Sep 2, 2026
Merged via the queue into rust-lang:master with commit dbc319b Sep 2, 2026
28 checks passed
@rustbot rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 2, 2026
@weihanglo
weihanglo deleted the trim-paths-docs branch September 2, 2026 20:15
This was referenced Sep 2, 2026
Closed
Merged
rust-bors Bot pushed a commit to rust-lang/rust that referenced this pull request Sep 5, 2026
@bors
Auto merge of #162314 - weihanglo:update-cargo, r=weihanglo
edf8f75 
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)
rust-bors Bot pushed a commit to rust-lang/rust that referenced this pull request Sep 5, 2026
@bors
Auto merge of #162314 - weihanglo:update-cargo, r=weihanglo
546f07f 
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)
@rustbot rustbot added this to the 1.100.0 milestone Sep 5, 2026
renovate-bot pushed a commit to renovate-bot/rust-lang-_-compiler-builtins that referenced this pull request Sep 7, 2026
@bors
Auto merge of #162314 - weihanglo:update-cargo, r=weihanglo
26b1f39 
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)
asukaminato0721 pushed a commit to asukaminato0721/rust-analyzer that referenced this pull request Sep 7, 2026
@bors
Auto merge of #162314 - weihanglo:update-cargo, r=weihanglo
6906345 
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)
@weihanglo weihanglo mentioned this pull request Sep 18, 2026
Merged
3 of 6 tasks
github-actions Bot pushed a commit to codeandsolder/cargo-ephemeral that referenced this pull request Oct 6, 2026
@epage
feat(trim-paths): stabilize profile.trim-paths (rust-lang#17488)
784be26 
*[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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@epage epage epage approved these changes
+1 more reviewer
@Urgau Urgau Urgau approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

@epage epage

Labels

A-documenting-cargo-itself Area: Cargo's documentation A-profiles Area: profiles A-trim-paths Area: path sanitization in resulting binaries

Projects

None yet

Milestone

1.100.0

Development

Successfully merging this pull request may close these issues.

4 participants

@weihanglo @rustbot @epage @Urgau