Skip to content

feat(trim-paths): rustdoc supports trim-paths for diagnostics - #14389

Merged
bors merged 3 commits into
rust-lang:masterfrom
weihanglo:rustdoc
Aug 12, 2024
Merged

feat(trim-paths): rustdoc supports trim-paths for diagnostics #14389
bors merged 3 commits into
rust-lang:masterfrom
weihanglo:rustdoc

Conversation

@weihanglo

@weihanglo weihanglo commented Aug 12, 2024

Copy link
Copy Markdown
Member

What does this PR try to resolve?

Part of #12137

This enables rustdoc invocation from cargo doc to trim paths
in diagnostics.

How should we test and review this PR?

Tests were added and followed by the behavior changing commit.

Additional information

Doc tests are out-of-scope, as they are handled
in a different mechanism, which needs more cares.

@weihanglo
refactor: extract remap rules into functions
0a752c6
@weihanglo
test: show trim-paths=diagnostics doesnt works for rustdoc
33a800c 
It should be working with the next commit.
@weihanglo
feat(trim-paths): rustdoc supports trim-paths for diagnostics
b8a3dbe 
This enables rustdoc invocation from `cargo doc` to trim paths
in diagnostics. Doc tests are out-of-scope, as they are handled
in a different mechanism, which needs more cares.
@weihanglo weihanglo added the A-trim-paths Area: path sanitization in resulting binaries label Aug 12, 2024
@rustbot

rustbot commented Aug 12, 2024

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

@rustbot rustbot added A-build-execution Area: anything dealing with executing the compiler S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 12, 2024
@weihanglo weihanglo changed the title refactor: extract remap rules into functions feat(trim-paths): rustdoc supports trim-paths for diagnostics Aug 12, 2024
@weihanglo weihanglo mentioned this pull request Aug 12, 2024
Closed
14 of 19 tasks
@epage

epage commented Aug 12, 2024

Copy link
Copy Markdown
Contributor

@bors r+

@bors

bors commented Aug 12, 2024

Copy link
Copy Markdown
Contributor

📌 Commit b8a3dbe has been approved by epage

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 12, 2024
@bors

bors commented Aug 12, 2024

Copy link
Copy Markdown
Contributor

⌛ Testing commit b8a3dbe with merge 3bd891d...

bors added a commit that referenced this pull request Aug 12, 2024
@bors
Auto merge of #14389 - weihanglo:rustdoc, r=epage
3bd891d 
feat(trim-paths): rustdoc supports trim-paths for diagnostics
@bors

bors commented Aug 12, 2024

Copy link
Copy Markdown
Contributor

💔 Test failed - checks-actions

@bors bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Aug 12, 2024
@weihanglo

weihanglo commented Aug 12, 2024

Copy link
Copy Markdown
Member Author 
---- everything stdout ----
error: test failed, to rerun pass `-p rustfix --test parse_and_replace`
failed: ./tests/everything/use-insert.rs
thread 'everything' panicked at crates/rustfix/tests/parse_and_replace.rs:264:9:
1 out of 9 fixture asserts failed
(run with `env RUST_LOG=parse_and_replace=info` to get more details)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Can't reproduce the error. Flaky I believe.

@bors retry

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 12, 2024
@bors

bors commented Aug 12, 2024

Copy link
Copy Markdown
Contributor

⌛ Testing commit b8a3dbe with merge 94935a0...

@bors

bors commented Aug 12, 2024

Copy link
Copy Markdown
Contributor

☀️ Test successful - checks-actions
Approved by: epage
Pushing 94935a0 to master...

@bors
bors merged commit 94935a0 into rust-lang:master Aug 12, 2024
@weihanglo
weihanglo deleted the rustdoc branch August 12, 2024 21:19
@weihanglo weihanglo mentioned this pull request Aug 13, 2024
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Aug 14, 2024
@bors
Auto merge of rust-lang#129066 - weihanglo:update-cargo, r=weihanglo
9af6a95 
Update cargo

7 commits in 0d8d22f83b066503f6b2b755925197e959e58b4f..2f738d617c6ead388f899802dd1a7fd66858a691
2024-08-08 12:54:24 +0000 to 2024-08-13 10:57:52 +0000
- chore: downgrade to openssl v1.1.1 (again) (rust-lang/cargo#14391)
- feat(trim-paths): rustdoc supports trim-paths for diagnostics (rust-lang/cargo#14389)
- Use longhand gitoxide path-spec patterns (rust-lang/cargo#14380)
- feat: Add `info` cargo subcommand (rust-lang/cargo#14141)
- CI: Switch macos aarch64 to nightly (rust-lang/cargo#14382)
- Use context instead of with_context (rust-lang/cargo#14377)
- Fix: `cargo package` failed on bare commit git repo. (rust-lang/cargo#14359)

r? ghost
bors added a commit to rust-lang-ci/rust that referenced this pull request Aug 14, 2024
@bors
Auto merge of rust-lang#129066 - weihanglo:update-cargo, r=weihanglo
9594488 
Update cargo

7 commits in 0d8d22f83b066503f6b2b755925197e959e58b4f..2f738d617c6ead388f899802dd1a7fd66858a691
2024-08-08 12:54:24 +0000 to 2024-08-13 10:57:52 +0000
- chore: downgrade to openssl v1.1.1 (again) (rust-lang/cargo#14391)
- feat(trim-paths): rustdoc supports trim-paths for diagnostics (rust-lang/cargo#14389)
- Use longhand gitoxide path-spec patterns (rust-lang/cargo#14380)
- feat: Add `info` cargo subcommand (rust-lang/cargo#14141)
- CI: Switch macos aarch64 to nightly (rust-lang/cargo#14382)
- Use context instead of with_context (rust-lang/cargo#14377)
- Fix: `cargo package` failed on bare commit git repo. (rust-lang/cargo#14359)

r? ghost
bors added a commit to rust-lang-ci/rust that referenced this pull request Aug 15, 2024
@bors
Auto merge of rust-lang#129066 - weihanglo:update-cargo, r=weihanglo
c416a6f 
Update cargo

7 commits in 0d8d22f83b066503f6b2b755925197e959e58b4f..2f738d617c6ead388f899802dd1a7fd66858a691
2024-08-08 12:54:24 +0000 to 2024-08-13 10:57:52 +0000
- chore: downgrade to openssl v1.1.1 (again) (rust-lang/cargo#14391)
- feat(trim-paths): rustdoc supports trim-paths for diagnostics (rust-lang/cargo#14389)
- Use longhand gitoxide path-spec patterns (rust-lang/cargo#14380)
- feat: Add `info` cargo subcommand (rust-lang/cargo#14141)
- CI: Switch macos aarch64 to nightly (rust-lang/cargo#14382)
- Use context instead of with_context (rust-lang/cargo#14377)
- Fix: `cargo package` failed on bare commit git repo. (rust-lang/cargo#14359)

r? ghost
@rustbot rustbot added this to the 1.82.0 milestone Aug 15, 2024
lnicola pushed a commit to lnicola/rust-analyzer that referenced this pull request Aug 29, 2024
@bors
Auto merge of #129066 - weihanglo:update-cargo, r=weihanglo
8e1bc89 
Update cargo

7 commits in 0d8d22f83b066503f6b2b755925197e959e58b4f..2f738d617c6ead388f899802dd1a7fd66858a691
2024-08-08 12:54:24 +0000 to 2024-08-13 10:57:52 +0000
- chore: downgrade to openssl v1.1.1 (again) (rust-lang/cargo#14391)
- feat(trim-paths): rustdoc supports trim-paths for diagnostics (rust-lang/cargo#14389)
- Use longhand gitoxide path-spec patterns (rust-lang/cargo#14380)
- feat: Add `info` cargo subcommand (rust-lang/cargo#14141)
- CI: Switch macos aarch64 to nightly (rust-lang/cargo#14382)
- Use context instead of with_context (rust-lang/cargo#14377)
- Fix: `cargo package` failed on bare commit git repo. (rust-lang/cargo#14359)

r? ghost
@weihanglo weihanglo mentioned this pull request Sep 18, 2026
Merged
4 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.
@weihanglo weihanglo mentioned this pull request Oct 7, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@epage epage

Labels

A-build-execution Area: anything dealing with executing the compiler A-trim-paths Area: path sanitization in resulting binaries S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion.

Projects

None yet

Milestone

1.82.0

Development

Successfully merging this pull request may close these issues.

4 participants

@weihanglo @rustbot @epage @bors