Stabilize --remap-path-scope in rustdoc and the documentation scope

[Urgau]

Stabilization report of --remap-path-scope in rustdoc and the documentation scope

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 to control which generted output has remapped paths in rustdoc.

Cargo is starting to use the rustc flag with rust-lang/cargo#17488.

Tracking issue: #155451.

It's the last major part of the trim-paths feature.

What is stabilized

The rustdoc --remap-path-scope flag is being stabilized by this PR. It's equivalent to the rustc flag.

It permits defines which scopes should be remapped by -–remap-path-prefix: macro,diagnostics,documentation,debuginfo,coverage,object,all.

Example

rustdoc src/lib.rs --remap-path-prefix="$PWD=/foo" --remap-path-prefix=documentation

The documentation

In addition to the other scopes (diagnostics, debuginfo, ...). rustdoc uses the documentation scope, it's a new scope to be shared with rustc (T-compiler FCP here).

Implementation

Major parts

• Add --remap-path-scope as unstable in rustdoc #155357
• Add a documentation remapping path scope for rustdoc usage #151589
• Pass the unremapped path to the rustc invocation for doctests #163956

Coverage

• tests/rustdoc-ui/remap-path-prefix.rs
• tests/rustdoc-ui/remap-path-prefix-doctest.rs
• tests/ui/errors/remap-path-prefix-macro.rs
• tests/ui/errors/remap-path-prefix-diagnostics.rs

Outstanding bugs

There are no outstanding bugs regarding --remap-path-scope in rustdoc.

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-scope (in rustc or rustdoc).

cc @ojeda (for Rust-for-Linux)
cc @weihanglo
r? rustdoc

[Urgau]

@rfcbot merge rustdoc-internals

[rust-rfcbot]

@Urgau has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Urgau
• @camelid
• @fmease
• @lolbinarycat
• @notriddle
• @yotamofek

Concerns:

• inclusion-of-rustc-specific-scopes (Stabilize --remap-path-scope in rustdoc and the documentation scope #163895 (comment))

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.

[weihanglo]

Not a stabilization blocker, but could you clarify what artifacts the documentation scope applies to? Also, what does other scopes mean in rustdoc terms.

I am thinking from build tool integration angle (apparently cargo)

[Urgau]

Not a stabilization blocker, but could you clarify what artifacts the documentation scope applies to? Also, what does other scopes mean in rustdoc terms.

As you discovered we had weird bug with the documentatiopn scope and doctests, that's now fixed with #163956.

As for your more fundamental question, the documentation scope is meant to apply to rustdoc specific places, one that don't have a clear equivalent in rustc, like for example the HTML file viewer, ... so if something has an equivalent meaning in rustc we should use those scope.

[fmease]

@rfcbot concern inclusion-of-rustc-specific-scopes

What's the motivation for allowing the rustc-specific scopes object, coverage & debuginfo. rustdoc cannot generate object files and IINM it cannot generate debug or coverage information either.

The reasoning can't be "it makes it easier for build systems to blindly forward these options to both rustc & rustdoc" because by that logic rustc should also include documention, no? Moreover, AFAICT Cargo doesn't forward the scopes verbatim but parses them itself first, so it knows what scopes it can or cannot forward to rustc or rustdoc.

@rfcbot reviewed

[Urgau]

What's the motivation for allowing the rustc-specific scopes object, coverage & debuginfo. rustdoc cannot generate object files and IINM it cannot generate debug or coverage information either.

We do the use coverage scope in our doc coverage:

rust/src/librustdoc/calculate_doc_coverage.rs

Line 190 in 0617e57

file.display(RemapPathScopeComponents::COVERAGE).to_string(),

As for object it's a alias for macros, debuginfo and coverage, so we do have a use for it as well. (Btw, I'm wondering if our documentation scope shouldn't also be included in object, as it's meant for things written in disk and the docs are written their).

As for the debuginfo scope, it's true that rustdoc doesn't use it directly, but we do pass it to rustc for doctests and it's effect is observable at minimum in backtraces (I should add a test for it):

/// ```rust
/// panic!();
/// ```
pub fn foo() {}

$ RUST_BACKTRACE=1 rustdoc +nightly --test /tmp/foo/a.rs --extern a=liba.rlib --remap-path-prefix=/tmp=/remapped --remap-path-scope=debuginfo -Zunstable-options -Cdebuginfo=1

thread 'main' (118190) panicked at /tmp/foo/a.rs:5:1:
explicit panic
stack backtrace:
   0: std::panicking::begin_panic::<&str>
             at /rustc/6f5da406b56c2db6607202b63daee73aa8c61297/library/std/src/panicking.rs:747:5
   1: rust_out::main::_doctest_main__tmp_foo_a_rs_1_0
             at /remapped/foo/a.rs:5:1
   2: rust_out::main
             at /remapped/foo/a.rs:6:3
   3: <fn() as core::ops::function::FnOnce<()>>::call_once
             at /rustc/6f5da406b56c2db6607202b63daee73aa8c61297/library/core/src/ops/function.rs:250:5

The reasoning can't be "it makes it easier for build systems to blindly forward these options to both rustc & rustdoc" because by that logic rustc should also include documention, no?

That's what I proposing in #163896, that rustc also includes the documentation scope. (Reasoning in that issue).