Stabilize `-Zremap-path-scope`
# Stabilization report of `--remap-path-scope`
## Summary
RFC 3127 trim-paths aims to improve the current status of sanitizing paths emitted by the compiler via the `--remap-path-prefix=FROM=TO` command line flag, by offering a profile setting named `trim-paths` in Cargo to sanitize absolute paths introduced during compilation that may be embedded in the compiled binary executable or library.
As part of that RFC the compiler was asked to add the `--remap-path-scope` command-line flag to control the scoping of how paths get remapped in the resulting binary.
Tracking:
- https://github.com/rust-lang/rust/issues/111540
### What is stabilized
The rustc `--remap-path-scope` flag is being stabilized by this PR. It defines which scopes of paths should be remapped by `--remap-path-prefix`.
This flag accepts a comma-separated list of values and may be specified multiple times, in which case the scopes are aggregated together.
The valid scopes are:
- `macro` - apply remappings to the expansion of `std::file!()` macro. This is where paths in embedded panic messages come from
- `diagnostics` - apply remappings to printed compiler diagnostics
- `debuginfo` - apply remappings to debug informations
- `coverage` - apply remappings to coverage informations
- `object` - apply remappings to all paths in compiled executables or libraries, but not elsewhere. Currently an alias for `macro,coverage,debuginfo`.
- `all` (default) - an alias for all of the above, also equivalent to supplying only `--remap-path-prefix` without `--remap-path-scope`.
#### Example
```sh
# With `object` scope only the build outputs will be remapped, the diagnostics won't be remapped.
rustc --remap-path-prefix=$(PWD)=/remapped --remap-path-scope=object main.rs
```
### What isn't stabilized
None of the Cargo facility is being stabilized in this stabilization PR, only the `--remap-path-scope` flag in `rustc` is being stabilized.
## Design
### RFC history
- [RFC3127 - trim-paths](https://rust-lang.github.io/rfcs/3127-trim-paths.html)
### Answers to unresolved questions
> What questions were left unresolved by the RFC? How have they been answered? Link to any relevant lang decisions.
There are no unresolved questions regarding `--remap-path-scope`.
(The tracking issue list a bunch of unresolved questions but they are for `--remap-path-prefix` or the bigger picture `trim-paths` in Cargo and are not related the functionality provided by `--remap-path-scope`.)
### Post-RFC changes
The RFC described more scopes, in particularly regarding split debuginfo. Those scopes where removed after analysis by `michaelwoerister` of all the possible combinations in https://github.com/rust-lang/rust/issues/111540#issuecomment-1994010274.
### Nightly extensions
There are no nightly extensions.
### Doors closed
We are committing to having to having a flag that control which paths are being remapped based on a "scope".
## Feedback
### Call for testing
> Has a "call for testing" been done? If so, what feedback was received?
No call for testing has been done per se but feedback has been received on both the rust-lang/rust and rust-lang/cargo tracking issue.
The feedback was mainly related to deficiencies in *our best-effort* `--remap-path-prefix` implementation, in particular regarding linkers added paths, which does not change anything for `--remap-path-scope`.
### Nightly use
> Do any known nightly users use this feature? Counting instances of `#![feature(FEATURE_NAME)]` on GitHub with grep might be informative.
Except for Cargo unstable `trim-paths` there doesn't appear any committed use [on GitHub](https://github.com/search?q=%22--remap-path-scope%22+NOT+path%3A%2F%5Esrc%5C%2Fcargo%5C%2Fcore%5C%2Fcompiler%5C%2F%2F+NOT+path%3A%2F%5Etext%5C%2F%2F+NOT+path%3A%2F%5Erust%5C%2Fsrc%5C%2Fdoc%5C%2Funstable-book%5C%2Fsrc%5C%2Fcompiler-flags%5C%2F%2F+NOT+path%3A%2F%5Esrc%5C%2Fdoc%5C%2Funstable-book%5C%2Fsrc%5C%2Fcompiler-flags%5C%2F%2F+NOT+path%3A%2F%5Ecollector%5C%2Fcompile-benchmarks%5C%2Fcargo-0%5C.87%5C.1%5C%2Fsrc%5C%2Fcargo%5C%2Fcore%5C%2Fcompiler%5C%2F%2F&type=code).
## Implementation
### Major parts
- b3f8586fb1/compiler/rustc_session/src/config.rs (L1373-L1384)
- b3f8586fb1/compiler/rustc_session/src/session.rs (L1526)
- b3f8586fb1/compiler/rustc_span/src/lib.rs (L352-L372)
### Coverage
- [`tests/run-make/split-debuginfo/rmake.rs`](9725c4baac/tests/run-make/split-debuginfo/rmake.rs (L7))
- [`tests/ui/errors/remap-path-prefix.rs`](9725c4baac/tests/ui/errors/remap-path-prefix.rs (L4))
- [`tests/ui/errors/remap-path-prefix-macro.rs`](9725c4baac/tests/ui/errors/remap-path-prefix-macro.rs (L1-L4))
- [`tests/run-make/remap-path-prefix-dwarf/rmake.rs
`](9725c4baac/tests/run-make/remap-path-prefix-dwarf/rmake.rs)
- [`tests/run-make/remap-path-prefix/rmake.rs`](9725c4baac/tests/run-make/remap-path-prefix/rmake.rs)
- [`tests/ui/errors/remap-path-prefix-diagnostics.rs`](9725c4baac/tests/ui/errors/remap-path-prefix-diagnostics.rs)
### Outstanding bugs
> What outstanding bugs involve this feature? List them. Should any block the stabilization? Discuss why or why not.
There are no outstanding bugs regarding `--remap-path-scope`.
### Outstanding FIXMEs
> What FIXMEs are still in the code for that feature and why is it OK to leave them there?
There are no FIXME regarding `--remap-path-scope` in it-self.
### Tool changes
> What changes must be made to our other tools to support this feature. Has this work been done? Link to any relevant PRs and issues.
- rustdoc (both JSON, HTML and doctest)
- `rustdoc` has support for `--remap-path-prefix`, it should probably also get support for `--remap-path-scope`, although rustdoc maybe want to adapt the scopes for it's use (replace `debuginfo` with `documentation` for example).
## History
> List issues and PRs that are important for understanding how we got here.
- https://github.com/rust-lang/rust/pull/115214
- https://github.com/rust-lang/rust/pull/122450
- https://github.com/rust-lang/rust/pull/139550
- https://github.com/rust-lang/rust/pull/140716
## Acknowledgments
> Summarize contributors to the feature by name for recognition and so that those people are notified about the stabilization. Does anyone who worked on this *not* think it should be stabilized right now? We'd like to hear about that if so.
- @cbeuw
- @michaelwoerister
- @weihanglo
- @Urgau
@rustbot labels +T-compiler +needs-fcp +F-trim-paths
r? @davidtwco
The tests in this directory are shared by two different test modes, and can be
run in multiple different ways:
./x.py test coverage-map (compiles to LLVM IR and checks coverage mappings)
./x.py test coverage-run (runs a test binary and checks its coverage report)
./x.py test coverage (runs both coverage-map and coverage-run)
Maintenance note
These tests can be sensitive to small changes in MIR spans or MIR control flow,
especially in HIR-to-MIR lowering or MIR optimizations.
If you haven't touched the coverage code directly, and the tests still pass in
coverage-run mode, then it should usually be OK to just re-bless the mappings
as necessary with ./x.py test coverage-map --bless, without worrying too much
about the exact changes.
1832bdfe64