Add a `documentation` remapping path scope for rustdoc usage by Urgau · Pull Request #151589 · rust-lang/rust

Urgau · 2026-01-24T13:07:10Z

This PR adds a new remapping path scope for rustdoc usage: documentation, instead of rustdoc abusing the other scopes for it's usage.

Like remapping paths in rustdoc, this scope is unstable. (rustdoc doesn't even have yet an equivalent to rustc --remap-path-scope).

I also took the opportunity to add a bit of documentation in rustdoc book.

r? @GuillaumeGomez

Urgau · 2026-01-24T14:59:58Z

There are two questions this unstable scope brings is it's relationship with the stable scopes:

should the scope be implied by the all scope (the default one, it currently is)?
- we could make all + -Zunstable-options imply it
should it be part of the object group scope?
- we currently define it as "paths in compiled executables or libraries", we could extend that to mean "artifact" in a more general sense
- ~~if we did, the same question about stable/unstable arise~~

It should be noted that those two questions are mostly theoretical (rustc doesn't use it), the only impact they could have today is in the generated rmeta, and whenever "we leak" the path.

cc @davidtwco

Urgau · 2026-01-24T15:59:20Z

It should be noted that --remap-path-scope was stabilized in the current release (#147611), making any change in behavior non-breaking.

Urgau · 2026-01-25T10:15:59Z

should the scope be implied by the all scope (the default one, it currently is)?

Reflecting back on this question, I think it needs to be included, as we say that all is equal to not passing any --remap-path-scope arguments, and people expect rmeta and rlib to be clean with just --remap-path-prefix (even if we don't officially guarantee it).

We also document clearly document that new scopes may be added in the future, so people shouldn't expect diagnostics,object to be the same as the all, this could be a good way to make sure they don't rely on that.

should it be part of the object group scope?

As for this question, I don't think it should, but we can also leave as it unresolved, it won't change a thing for users doing --remap-path-scope=object as specifying the object scope alone already "leaks" the local in paths in rmeta.

GuillaumeGomez · 2026-01-25T15:56:34Z

Nice, thanks!

@bors r+ rollup

rust-bors · 2026-01-25T15:56:37Z

📌 Commit dd84a4f has been approved by GuillaumeGomez

It is now in the queue for this repository.

…aumeGomez Add a `documentation` remapping path scope for rustdoc usage This PR adds a new remapping path scope for rustdoc usage: `documentation`, instead of rustdoc abusing the other scopes for it's usage. Like remapping paths in rustdoc, this scope is unstable. (rustdoc doesn't even have yet an equivalent to [rustc `--remap-path-scope`](https://doc.rust-lang.org/nightly/rustc/remap-source-paths.html#--remap-path-scope)). I also took the opportunity to add a bit of documentation in rustdoc book.

Rollup of 3 pull requests Successful merges: - #150428 (UnixStream/UnixListener on Windows ) - #151589 (Add a `documentation` remapping path scope for rustdoc usage) - #151645 (Update `sysinfo` version to `0.38.0`)

Rollup of 6 pull requests Successful merges: - #151611 (Improve is_ascii performance on x86_64 with explicit SSE2 intrinsics) - #150705 (Add missing mut to pin.rs docs) - #151294 (compiletest: add implied `needs-target-std` for `codegen` mode tests unless annotated with `#![no_std]`/`#![no_core]`) - #151589 (Add a `documentation` remapping path scope for rustdoc usage) - #151639 (Fix broken WASIp1 reference link) - #151645 (Update `sysinfo` version to `0.38.0`)

Rollup merge of #151589 - Urgau:documentation-scope, r=GuillaumeGomez Add a `documentation` remapping path scope for rustdoc usage This PR adds a new remapping path scope for rustdoc usage: `documentation`, instead of rustdoc abusing the other scopes for it's usage. Like remapping paths in rustdoc, this scope is unstable. (rustdoc doesn't even have yet an equivalent to [rustc `--remap-path-scope`](https://doc.rust-lang.org/nightly/rustc/remap-source-paths.html#--remap-path-scope)). I also took the opportunity to add a bit of documentation in rustdoc book.

Rollup of 6 pull requests Successful merges: - rust-lang/rust#151611 (Improve is_ascii performance on x86_64 with explicit SSE2 intrinsics) - rust-lang/rust#150705 (Add missing mut to pin.rs docs) - rust-lang/rust#151294 (compiletest: add implied `needs-target-std` for `codegen` mode tests unless annotated with `#![no_std]`/`#![no_core]`) - rust-lang/rust#151589 (Add a `documentation` remapping path scope for rustdoc usage) - rust-lang/rust#151639 (Fix broken WASIp1 reference link) - rust-lang/rust#151645 (Update `sysinfo` version to `0.38.0`)

@edward-shen

…GuillaumeGomez Stabilize `--remap-path-prefix` in rustdoc # Stabilization report of `--remap-path-prefix` in rustdoc ## Summary `rustc` supports remapping source paths prefixes as a best effort in all compiler generated output, including compiler diagnostics, debugging information, macro expansions, documentation, doctests, etc. This is useful for normalizing build products, for example, by removing the current directory out of the paths emitted into object files. This stabilization stabilize the same flag used by `rustc` in `rustdoc`. There are no tracking issue. Stabilization was discussed at the last meeting, [#t-rustdoc/meetings > 2026-04-13 @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/393423-t-rustdoc.2Fmeetings/topic/2026-04-13/near/585264347). ### What is stabilized The rustdoc `--remap-path-prefix` flag is being stabilized by this PR. (It's equivalent to rustc flag) It permits remapping (as a best effort) source path prefixes in all output, including diagnostics, debug information, macro expansions, generated documentation, etc. It takes a value of the form `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`. #### Example ```sh rustdoc src/lib.rs --remap-path-prefix="$PWD=/foo" ``` ### What isn't stabilized Neither `--remap-path-scope` (~~soon to be added as unstable in `rustdoc`~~ #155451) or the already unstable in `rustc` `documentation` scope are being stabilized or added here. ## Design ### Implementation history - #107099 ### Unresolved questions There are no unresolved questions. ### Post-implementation changes The implementation has evolved with `rustc`, but no changes to the flag it-self have been made. ### Nightly extensions The `documentation` scope, which currently can only be set from `rustc`, as we need to add an equivalent to the `--remap-path-scope` flag, ~~which is planned~~ (EDIT: #155451), but not required, the current `--remap-path-prefix` defaults to the `all` scope, like `rustc`. ### Doors closed We are committing to having to having a flag that permits remapping paths. The compiler team already made the same commitment. ## Feedback ### Call for testing No call for testing has been done. ### Nightly use Unable to determine. A [GitHub search](https://github.com/search?q=%20%2F--remap-path-prefix%2F&type=code) only seems to only reveals the `rustc` usage (over 6k though). Rust-for-Linux is using the [flag](https://github.com/torvalds/linux/blob/e80d033851b3bc94c3d254ac66660ddd0a49d72c/Makefile#L1151-L1153). ## Implementation ### Major parts - #107099 - #149709 - #150172 - #151589 ### Coverage - [`tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs) - [`tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs) - [`tests/rustdoc-ui/remap-path-prefix-macro.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-macro.rs) - [`tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs) - [`tests/rustdoc-ui/lints/remap-path-prefix-lint.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/lints/remap-path-prefix-lint.rs) - [`tests/rustdoc-html/import-remapped-paths.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-html/import-remapped-paths.rs) - [`tests/rustdoc-html/macro/external-macro-src.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-html/macro/external-macro-src.rs) ### Outstanding bugs There are no outstanding bugs regarding `--remap-path-prefix` in `rustdoc`. There are [caveats and limitation](https://doc.rust-lang.org/nightly/rustc/remap-source-paths.html#caveats-and-limitations) in `rustc`, but they mostly concern generated object files, which we don't really have. ### Outstanding FIXMEs There are no FIXME regarding `--remap-path-prefix`. ## Acknowledgments - @edward-shen - @Urgau

@edward-shen

…-prefix, r=GuillaumeGomez Stabilize `--remap-path-prefix` in rustdoc # Stabilization report of `--remap-path-prefix` in rustdoc ## Summary `rustc` supports remapping source paths prefixes as a best effort in all compiler generated output, including compiler diagnostics, debugging information, macro expansions, documentation, doctests, etc. This is useful for normalizing build products, for example, by removing the current directory out of the paths emitted into object files. This stabilization stabilize the same flag used by `rustc` in `rustdoc`. There are no tracking issue. Stabilization was discussed at the last meeting, [#t-rustdoc/meetings > 2026-04-13 @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/393423-t-rustdoc.2Fmeetings/topic/2026-04-13/near/585264347). ### What is stabilized The rustdoc `--remap-path-prefix` flag is being stabilized by this PR. (It's equivalent to rustc flag) It permits remapping (as a best effort) source path prefixes in all output, including diagnostics, debug information, macro expansions, generated documentation, etc. It takes a value of the form `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`. #### Example ```sh rustdoc src/lib.rs --remap-path-prefix="$PWD=/foo" ``` ### What isn't stabilized Neither `--remap-path-scope` (~~soon to be added as unstable in `rustdoc`~~ rust-lang#155451) or the already unstable in `rustc` `documentation` scope are being stabilized or added here. ## Design ### Implementation history - rust-lang#107099 ### Unresolved questions There are no unresolved questions. ### Post-implementation changes The implementation has evolved with `rustc`, but no changes to the flag it-self have been made. ### Nightly extensions The `documentation` scope, which currently can only be set from `rustc`, as we need to add an equivalent to the `--remap-path-scope` flag, ~~which is planned~~ (EDIT: rust-lang#155451), but not required, the current `--remap-path-prefix` defaults to the `all` scope, like `rustc`. ### Doors closed We are committing to having to having a flag that permits remapping paths. The compiler team already made the same commitment. ## Feedback ### Call for testing No call for testing has been done. ### Nightly use Unable to determine. A [GitHub search](https://github.com/search?q=%20%2F--remap-path-prefix%2F&type=code) only seems to only reveals the `rustc` usage (over 6k though). Rust-for-Linux is using the [flag](https://github.com/torvalds/linux/blob/e80d033851b3bc94c3d254ac66660ddd0a49d72c/Makefile#L1151-L1153). ## Implementation ### Major parts - rust-lang#107099 - rust-lang#149709 - rust-lang#150172 - rust-lang#151589 ### Coverage - [`tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs) - [`tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs) - [`tests/rustdoc-ui/remap-path-prefix-macro.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-macro.rs) - [`tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs) - [`tests/rustdoc-ui/lints/remap-path-prefix-lint.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/lints/remap-path-prefix-lint.rs) - [`tests/rustdoc-html/import-remapped-paths.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-html/import-remapped-paths.rs) - [`tests/rustdoc-html/macro/external-macro-src.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-html/macro/external-macro-src.rs) ### Outstanding bugs There are no outstanding bugs regarding `--remap-path-prefix` in `rustdoc`. There are [caveats and limitation](https://doc.rust-lang.org/nightly/rustc/remap-source-paths.html#caveats-and-limitations) in `rustc`, but they mostly concern generated object files, which we don't really have. ### Outstanding FIXMEs There are no FIXME regarding `--remap-path-prefix`. ## Acknowledgments - @edward-shen - @Urgau

@edward-shen

…GuillaumeGomez Stabilize `--remap-path-prefix` in rustdoc # Stabilization report of `--remap-path-prefix` in rustdoc ## Summary `rustc` supports remapping source paths prefixes as a best effort in all compiler generated output, including compiler diagnostics, debugging information, macro expansions, documentation, doctests, etc. This is useful for normalizing build products, for example, by removing the current directory out of the paths emitted into object files. This stabilization stabilize the same flag used by `rustc` in `rustdoc`. There are no tracking issue. Stabilization was discussed at the last meeting, [#t-rustdoc/meetings > 2026-04-13 @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/393423-t-rustdoc.2Fmeetings/topic/2026-04-13/near/585264347). ### What is stabilized The rustdoc `--remap-path-prefix` flag is being stabilized by this PR. (It's equivalent to rustc flag) It permits remapping (as a best effort) source path prefixes in all output, including diagnostics, debug information, macro expansions, generated documentation, etc. It takes a value of the form `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`. #### Example ```sh rustdoc src/lib.rs --remap-path-prefix="$PWD=/foo" ``` ### What isn't stabilized Neither `--remap-path-scope` (~~soon to be added as unstable in `rustdoc`~~ #155451) or the already unstable in `rustc` `documentation` scope are being stabilized or added here. ## Design ### Implementation history - #107099 ### Unresolved questions There are no unresolved questions. ### Post-implementation changes The implementation has evolved with `rustc`, but no changes to the flag it-self have been made. ### Nightly extensions The `documentation` scope, which currently can only be set from `rustc`, as we need to add an equivalent to the `--remap-path-scope` flag, ~~which is planned~~ (EDIT: #155451), but not required, the current `--remap-path-prefix` defaults to the `all` scope, like `rustc`. ### Doors closed We are committing to having to having a flag that permits remapping paths. The compiler team already made the same commitment. ## Feedback ### Call for testing No call for testing has been done. ### Nightly use Unable to determine. A [GitHub search](https://github.com/search?q=%20%2F--remap-path-prefix%2F&type=code) only seems to only reveals the `rustc` usage (over 6k though). Rust-for-Linux is using the [flag](https://github.com/torvalds/linux/blob/e80d033851b3bc94c3d254ac66660ddd0a49d72c/Makefile#L1151-L1153). ## Implementation ### Major parts - #107099 - #149709 - #150172 - #151589 ### Coverage - [`tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs) - [`tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs) - [`tests/rustdoc-ui/remap-path-prefix-macro.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-macro.rs) - [`tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs) - [`tests/rustdoc-ui/lints/remap-path-prefix-lint.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-ui/lints/remap-path-prefix-lint.rs) - [`tests/rustdoc-html/import-remapped-paths.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-html/import-remapped-paths.rs) - [`tests/rustdoc-html/macro/external-macro-src.rs`](https://github.com/rust-lang/rust/blob/12f35ad39ed3e39df4d953c46d4f6cc6c82adc96/tests/rustdoc-html/macro/external-macro-src.rs) ### Outstanding bugs There are no outstanding bugs regarding `--remap-path-prefix` in `rustdoc`. There are [caveats and limitation](https://doc.rust-lang.org/nightly/rustc/remap-source-paths.html#caveats-and-limitations) in `rustc`, but they mostly concern generated object files, which we don't really have. ### Outstanding FIXMEs There are no FIXME regarding `--remap-path-prefix`. ## Acknowledgments - @edward-shen - @Urgau

Add test for invalid --remap-path-scope arguments

ee6dd56

rustbot assigned GuillaumeGomez Jan 24, 2026

This comment has been minimized.

Sign in to view

Urgau added 4 commits January 24, 2026 15:33

Add the remapping path documentation scope for rustdoc usage

91e3e2a

Make rustdoc use the documentation remapping scope and cleanups

fbab2c0

Make sure the documentation scope doesn't imply other scopes

3d6a5b5

Add documentation for --remap-path-prefix and doc scope in rustdoc

dd84a4f

Urgau force-pushed the documentation-scope branch from 67a2f37 to dd84a4f Compare January 24, 2026 14:33

GuillaumeGomez approved these changes Jan 25, 2026

View reviewed changes

rust-bors Bot 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 Jan 25, 2026

matthiaskrgr mentioned this pull request Jan 25, 2026

Rollup of 3 pull requests #151656

Closed

Zalathar mentioned this pull request Jan 26, 2026

Rollup of 6 pull requests #151667

Merged

rust-bors Bot merged commit e811f07 into rust-lang:main Jan 26, 2026
11 checks passed

rustbot added this to the 1.95.0 milestone Jan 26, 2026

ojeda mentioned this pull request Apr 5, 2026

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

53 tasks

Urgau mentioned this pull request Apr 14, 2026

Stabilize --remap-path-prefix in rustdoc #155307

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add a `documentation` remapping path scope for rustdoc usage#151589

Add a `documentation` remapping path scope for rustdoc usage#151589
rust-bors[bot] merged 5 commits into
rust-lang:mainfrom
Urgau:documentation-scope

Urgau commented Jan 24, 2026

Uh oh!

This comment has been minimized.

Urgau commented Jan 24, 2026 •

edited

Loading

Uh oh!

Urgau commented Jan 24, 2026

Uh oh!

Urgau commented Jan 25, 2026

Uh oh!

GuillaumeGomez commented Jan 25, 2026

Uh oh!

rust-bors Bot commented Jan 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Urgau commented Jan 24, 2026

Uh oh!

This comment has been minimized.

Urgau commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Urgau commented Jan 24, 2026

Uh oh!

Urgau commented Jan 25, 2026

Uh oh!

GuillaumeGomez commented Jan 25, 2026

Uh oh!

rust-bors Bot commented Jan 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Urgau commented Jan 24, 2026 •

edited

Loading