Stabilize --remap-path-prefix in rustdoc#155307
Conversation
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment was marked as outdated.
This comment was marked as outdated.
|
@rfcbot fcp merge rustdoc-internals |
|
Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members: Concerns:
Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See this document for info about what commands tagged team members can give me. |
This comment was marked as outdated.
This comment was marked as outdated.
|
there seems to be a bit of an issue in the description
|
|
The final comment period, with a disposition to merge, as per the review above, is now complete. As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed. |
|
@bors r=GuillaumeGomez |
This comment has been minimized.
This comment has been minimized.
…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
…-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
|
@bors yield |
|
Auto build was cancelled. Cancelled workflows: The next pull request likely to be tested is #156808. |
This comment has been minimized.
This comment has been minimized.
What is this?This is an experimental post-merge analysis report that shows differences in test outcomes between the merged PR and its parent PR.Comparing e96c36b (parent) -> 4d276d7 (this PR) Test differencesShow 5 test diffsStage 2
Additionally, 4 doctest diffs were found. These are ignored, as they are noisy. Job group index
Test dashboardRun cargo run --manifest-path src/ci/citool/Cargo.toml -- \
test-dashboard 4d276d7fdba2a24c73dbca3027461bb202e83436 --output-dir test-dashboardAnd then open Job duration changes
How to interpret the job duration changes?Job durations can vary a lot, based on the actual runner instance |
|
Finished benchmarking commit (4d276d7): comparison URL. Overall result: ❌ regressions - please read:Our benchmarks found a performance regression caused by this PR. Next Steps:
@rustbot label: +perf-regression Instruction countOur most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.
Max RSS (memory usage)Results (primary 2.0%, secondary 2.0%)A less reliable metric. May be of interest, but not used to determine the overall result above.
CyclesResults (secondary 2.6%)A less reliable metric. May be of interest, but not used to determine the overall result above.
Binary sizeThis perf run didn't have relevant results for this metric. Bootstrap: 530.554s -> 511.788s (-3.54%) |
|
perf triage:
@rustbot label: +perf-regression-triaged |
This MR contains the following updates: | Package | Update | Change | |---|---|---| | [rust](https://github.com/rust-lang/rust) | minor | `1.96.1` → `1.97.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>rust-lang/rust (rust)</summary> ### [`v1.97.0`](https://github.com/rust-lang/rust/blob/HEAD/RELEASES.md#Version-1970-2026-07-09) [Compare Source](rust-lang/rust@1.96.1...1.97.0) \========================== <a id="1.97.0-Language"></a> ## Language - [Consider `Result<T, Uninhabited>` and `ControlFlow<Uninhabited, T>` to be equivalent to `T` for must use lint](rust-lang/rust#148214) - [Add allow-by-default `dead_code_pub_in_binary` lint for unused pub items in binary crates](rust-lang/rust#149509) - [Stabilize the `div32`, `lam-bh`, `lamcas`, `ld-seq-sa` and `scq` target features](rust-lang/rust#154510) - [Stabilize `cfg(target_has_atomic_primitive_alignment)`](rust-lang/rust#155006) - [Allow trailing `self` in imports in more cases](rust-lang/rust#155137) <a id="1.97.0-Platform-Support"></a> ## Platform Support - [nvptx64-nvidia-cuda: drop support for old architectures and old ISAs](rust-lang/rust#152443) Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support. [platform-support-doc]: https://doc.rust-lang.org/rustc/platform-support.html <a id="1.97.0-Stabilized-APIs"></a> ## Stabilized APIs - [`Default for RepeatN`](https://doc.rust-lang.org/stable/std/iter/struct.RepeatN.html#impl-Default-for-RepeatN%3CA%3E) - [`Copy for ffi::FromBytesUntilNulError`](https://doc.rust-lang.org/stable/std/ffi/struct.FromBytesUntilNulError.html#impl-Copy-for-FromBytesUntilNulError) - [`Send for std::fs::File` on UEFI](rust-lang/rust#154003) - [`<{integer}>::isolate_highest_one`](https://doc.rust-lang.org/stable/std/primitive.u32.html#method.isolate_highest_one) - [`<{integer}>::isolate_lowest_one`](https://doc.rust-lang.org/stable/std/primitive.u32.html#method.isolate_lowest_one) - [`<{integer}>::highest_one`](https://doc.rust-lang.org/stable/std/primitive.u32.html#method.highest_one) - [`<{integer}>::lowest_one`](https://doc.rust-lang.org/stable/std/primitive.u32.html#method.lowest_one) - [`<{integer}>::bit_width`](https://doc.rust-lang.org/stable/std/primitive.u32.html#method.bit_width) - [`NonZero<{integer}>::isolate_highest_one`](https://doc.rust-lang.org/stable/std/num/struct.NonZero.html#method.isolate_highest_one) - [`NonZero<{integer}>::isolate_lowest_one`](https://doc.rust-lang.org/stable/std/num/struct.NonZero.html#method.isolate_lowest_one) - [`NonZero<{integer}>::highest_one`](https://doc.rust-lang.org/stable/std/num/struct.NonZero.html#method.highest_one) - [`NonZero<{integer}>::lowest_one`](https://doc.rust-lang.org/stable/std/num/struct.NonZero.html#method.lowest_one) - [`NonZero<{integer}>::bit_width`](https://doc.rust-lang.org/stable/std/num/struct.NonZero.html#method.bit_width) These previously stable APIs are now stable in const contexts: - [`char::is_control`](https://doc.rust-lang.org/stable/std/primitive.char.html#method.is_control) <a id="1.97.0-Cargo"></a> ## Cargo - [Stabilize `build.warnings` config.](rust-lang/cargo#16796) This controls how lint warnings from local packages are treated. Useful for enforcing a warning-free build in CI, replacing `-Dwarnings`. [docs](https://doc.rust-lang.org/nightly/cargo/reference/config.html#buildwarnings) - [Stabilize `resolver.lockfile-path` config.](rust-lang/cargo#16694) This allows specifying the path to the lockfile to use when resolving dependencies. Useful when working with read-only source directories. [docs](https://doc.rust-lang.org/nightly/cargo/reference/config.html#resolverlockfile-path) - [cargo-clean: Error when `--target-dir` doesn't look like a Cargo target directory.](rust-lang/cargo#16712) This prevents accidental deletion of non-target directories. - [Add `-m` shorthand for `--manifest-path`](rust-lang/cargo#16858) - [Remove `curl` dependency from `crates-io` crate](rust-lang/cargo#16936) <a id="1.97.0-Rustdoc"></a> ## Rustdoc - [Stabilize `--emit` flag](rust-lang/rust#146220) - [Stabilize `--remap-path-prefix`](rust-lang/rust#155307) <a id="1.97.0-Compatibility-Notes"></a> ## Compatibility Notes - [Emit a future-compatibility warning when relying on `f32: From<{float}>` to constrain `{float}`](rust-lang/rust#139087) - [Rust will use the v0 symbol mangling scheme by default.](rust-lang/rust#151994) This may cause some tools (such as debuggers or profilers, especially with old versions) to fail to demangle symbols emitted by Rust. It may also cause the formatting of text in backtraces to change. - [Prevent deref coercions in `pin!`, in order to prevent unsoundness.](rust-lang/rust#153457) The most likely case where this might impact users is: writing `pin!(x)` where `x` has type `&mut T` will now always correctly produce a value of type `Pin<&mut &mut T>`, instead of sometimes allowing a coercion that produces a value of type `Pin<&mut T>`. This coercion was previously incorrectly allowed since Rust 1.88.0. - [Deprecate `std::char` constants and functions](rust-lang/rust#153873) - [Warn on linker output by default](rust-lang/rust#153968) - [Remove hidden `f64` methods which have been deprecated since 1.0](rust-lang/rust#153975) - [report the `varargs_without_pattern` lint in deps](rust-lang/rust#154599) - [Forbid passing generic arguments to module path segments even if the module reexports a generic enum variant](rust-lang/rust#154971) - [Error on invalid macho `link_section` specifier](rust-lang/rust#155065) - The encoding of certain `enum`s [have changed](rust-lang/rust#155473). This is not a breaking change, as it only applies to `enum`s without layout guarantees, but is noted here as we've seen people impacted from having made assumptions about the layout algorithm. - [Error on `#[export_name = "..."]` where the name is empty](rust-lang/rust#155515) - [Syntactically reject tuple index shorthands in struct patterns](rust-lang/rust#155698) - [validate `#[link_name = "..."]` & `#[link(name = "...")]` parameters](rust-lang/rust#155817) - On Windows, after calling `shutdown` on a socket to shut down the write side, attempting to write to the socket will now produce a `BrokenPipe` error rather than `Other`. [Map `WSAESHUTDOWN` to `io::ErrorKind::BrokenPipe`](rust-lang/rust#156063) </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box --- This MR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4yNTYuMCIsInVwZGF0ZWRJblZlciI6IjQzLjI1Ni4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJSZW5vdmF0ZSBCb3QiLCJhdXRvbWF0aW9uOmJvdC1hdXRob3JlZCIsImRlcGVuZGVuY3ktdHlwZTo6bWlub3IiXX0=-->
View all comments
Stabilization report of
--remap-path-prefixin rustdocSummary
rustcsupports 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
rustcinrustdoc.There are no tracking issue.
Stabilization was discussed at the last meeting, #t-rustdoc/meetings > 2026-04-13 @ 💬.
What is stabilized
The rustdoc
--remap-path-prefixflag 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=TOwhere a path prefix equal toFROMis rewritten to the valueTO.Example
rustdoc src/lib.rs --remap-path-prefix="$PWD=/foo"What isn't stabilized
Neither
--remap-path-scope(soon to be added as unstable in#155451) or the already unstable inrustdocrustcdocumentationscope are being stabilized or added here.Design
Implementation history
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
documentationscope, which currently can only be set fromrustc, as we need to add an equivalent to the--remap-path-scopeflag,which is planned(EDIT: #155451), but not required, the current--remap-path-prefixdefaults to theallscope, likerustc.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 only seems to only reveals the
rustcusage (over 6k though).Rust-for-Linux is using the flag.
Implementation
Major parts
documentationremapping path scope for rustdoc usage #151589Coverage
tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rstests/rustdoc-ui/remap-path-prefix-invalid-doctest.rstests/rustdoc-ui/remap-path-prefix-macro.rstests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rstests/rustdoc-ui/lints/remap-path-prefix-lint.rstests/rustdoc-html/import-remapped-paths.rstests/rustdoc-html/macro/external-macro-src.rsOutstanding bugs
There are no outstanding bugs regarding
--remap-path-prefixinrustdoc.There are caveats and limitation 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
@rustbot labels +T-rustdoc +F-trim-paths
cc @ojeda (for Rust-for-Linux)
r? rustdoc