Rollup merge of #147611 - stablize-remap-path-scope, r=davidtwco

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:

- #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 #111540 (comment).

### 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

- https://github.com/rust-lang/rust/blob/b3f8586fb1e4859678d6b231e780ff81801d2282/compiler/rustc_session/src/config.rs#L1373-L1384
- https://github.com/rust-lang/rust/blob/b3f8586fb1e4859678d6b231e780ff81801d2282/compiler/rustc_session/src/session.rs#L1526
- https://github.com/rust-lang/rust/blob/b3f8586fb1e4859678d6b231e780ff81801d2282/compiler/rustc_span/src/lib.rs#L352-L372

### Coverage

- [`tests/run-make/split-debuginfo/rmake.rs`](https://github.com/rust-lang/rust/blob/9725c4baacef19345e13f91b27e66e10ef5592ae/tests/run-make/split-debuginfo/rmake.rs#L7)
- [`tests/ui/errors/remap-path-prefix.rs`](https://github.com/rust-lang/rust/blob/9725c4baacef19345e13f91b27e66e10ef5592ae/tests/ui/errors/remap-path-prefix.rs#L4)
- [`tests/ui/errors/remap-path-prefix-macro.rs`](https://github.com/rust-lang/rust/blob/9725c4baacef19345e13f91b27e66e10ef5592ae/tests/ui/errors/remap-path-prefix-macro.rs#L1-L4)
- [`tests/run-make/remap-path-prefix-dwarf/rmake.rs
`](https://github.com/rust-lang/rust/blob/9725c4baacef19345e13f91b27e66e10ef5592ae/tests/run-make/remap-path-prefix-dwarf/rmake.rs)
- [`tests/run-make/remap-path-prefix/rmake.rs`](https://github.com/rust-lang/rust/blob/9725c4baacef19345e13f91b27e66e10ef5592ae/tests/run-make/remap-path-prefix/rmake.rs)
- [`tests/ui/errors/remap-path-prefix-diagnostics.rs`](https://github.com/rust-lang/rust/blob/9725c4baacef19345e13f91b27e66e10ef5592ae/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.

- #115214
- #122450
- #139550
- #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

Author: GuillaumeGomez

compiler/rustc_session/src/config.rs

@@ -22,7 +22,9 @@ use rustc_hashes::Hash64;
 use rustc_macros::{BlobDecodable, Decodable, Encodable, HashStable_Generic};
 use rustc_span::edition::{DEFAULT_EDITION, EDITION_NAME_LIST, Edition, LATEST_STABLE_EDITION};
 use rustc_span::source_map::FilePathMapping;
-use rustc_span::{FileName, RealFileName, SourceFileHashAlgorithm, Symbol, sym};
+use rustc_span::{
+    FileName, RealFileName, RemapPathScopeComponents, SourceFileHashAlgorithm, Symbol, sym,
+};
 use rustc_target::spec::{
     FramePointer, LinkSelfContainedComponents, LinkerFeatures, PanicStrategy, SplitDebuginfo,
     Target, TargetTuple,
@@ -1317,6 +1319,29 @@ impl OutputFilenames {
     }
 }
 
+pub(crate) fn parse_remap_path_scope(
+    early_dcx: &EarlyDiagCtxt,
+    matches: &getopts::Matches,
+) -> RemapPathScopeComponents {
+    if let Some(v) = matches.opt_str("remap-path-scope") {
+        let mut slot = RemapPathScopeComponents::empty();
+        for s in v.split(',') {
+            slot |= match s {
+                "macro" => RemapPathScopeComponents::MACRO,
+                "diagnostics" => RemapPathScopeComponents::DIAGNOSTICS,
+                "debuginfo" => RemapPathScopeComponents::DEBUGINFO,
+                "coverage" => RemapPathScopeComponents::COVERAGE,
+                "object" => RemapPathScopeComponents::OBJECT,
+                "all" => RemapPathScopeComponents::all(),
+                _ => early_dcx.early_fatal("argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `debuginfo`, `coverage`, `object`, `all`"),
+            }
+        }
+        slot
+    } else {
+        RemapPathScopeComponents::all()
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct Sysroot {
     pub explicit: Option<PathBuf>,
@@ -1353,9 +1378,9 @@ pub fn host_tuple() -> &'static str {
 
 fn file_path_mapping(
     remap_path_prefix: Vec<(PathBuf, PathBuf)>,
-    unstable_opts: &UnstableOptions,
+    remap_path_scope: RemapPathScopeComponents,
 ) -> FilePathMapping {
-    FilePathMapping::new(remap_path_prefix.clone(), unstable_opts.remap_path_scope)
+    FilePathMapping::new(remap_path_prefix.clone(), remap_path_scope)
 }
 
 impl Default for Options {
@@ -1367,7 +1392,7 @@ impl Default for Options {
         // to create a default working directory.
         let working_dir = {
             let working_dir = std::env::current_dir().unwrap();
-            let file_mapping = file_path_mapping(Vec::new(), &unstable_opts);
+            let file_mapping = file_path_mapping(Vec::new(), RemapPathScopeComponents::empty());
             file_mapping.to_real_filename(&RealFileName::empty(), &working_dir)
         };
 
@@ -1402,6 +1427,7 @@ impl Default for Options {
             cli_forced_codegen_units: None,
             cli_forced_local_thinlto_off: false,
             remap_path_prefix: Vec::new(),
+            remap_path_scope: RemapPathScopeComponents::all(),
             real_rust_source_base_dir: None,
             real_rustc_dev_source_base_dir: None,
             edition: DEFAULT_EDITION,
@@ -1428,7 +1454,7 @@ impl Options {
     }
 
     pub fn file_path_mapping(&self) -> FilePathMapping {
-        file_path_mapping(self.remap_path_prefix.clone(), &self.unstable_opts)
+        file_path_mapping(self.remap_path_prefix.clone(), self.remap_path_scope)
     }
 
     /// Returns `true` if there will be an output file generated.
@@ -1866,6 +1892,14 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
             "Remap source names in all output (compiler messages and output files)",
             "<FROM>=<TO>",
         ),
+        opt(
+            Stable,
+            Opt,
+            "",
+            "remap-path-scope",
+            "Defines which scopes of paths should be remapped by `--remap-path-prefix`",
+            "<macro,diagnostics,debuginfo,coverage,object,all>",
+        ),
         opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "<VAR>=<VALUE>"),
     ];
     options.extend(verbose_only.into_iter().map(|mut opt| {
@@ -2669,6 +2703,7 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
     let externs = parse_externs(early_dcx, matches, &unstable_opts);
 
     let remap_path_prefix = parse_remap_path_prefix(early_dcx, matches, &unstable_opts);
+    let remap_path_scope = parse_remap_path_scope(early_dcx, matches);
 
     let pretty = parse_pretty(early_dcx, &unstable_opts);
 
@@ -2735,7 +2770,7 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
             early_dcx.early_fatal(format!("Current directory is invalid: {e}"));
         });
 
-        let file_mapping = file_path_mapping(remap_path_prefix.clone(), &unstable_opts);
+        let file_mapping = file_path_mapping(remap_path_prefix.clone(), remap_path_scope);
         file_mapping.to_real_filename(&RealFileName::empty(), &working_dir)
     };
 
@@ -2772,6 +2807,7 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
         cli_forced_codegen_units: codegen_units,
         cli_forced_local_thinlto_off: disable_local_thinlto,
         remap_path_prefix,
+        remap_path_scope,
         real_rust_source_base_dir,
         real_rustc_dev_source_base_dir,
         edition,

compiler/rustc_session/src/options.rs

@@ -454,6 +454,8 @@ top_level_options!(
 
         /// Remap source path prefixes in all output (messages, object files, debug, etc.).
         remap_path_prefix: Vec<(PathBuf, PathBuf)> [TRACKED_NO_CRATE_HASH],
+        /// Defines which scopes of paths should be remapped by `--remap-path-prefix`.
+        remap_path_scope: RemapPathScopeComponents [TRACKED_NO_CRATE_HASH],
 
         /// Base directory containing the `library/` directory for the Rust standard library.
         /// Right now it's always `$sysroot/lib/rustlib/src/rust`
@@ -872,7 +874,6 @@ mod desc {
     pub(crate) const parse_branch_protection: &str = "a `,` separated combination of `bti`, `gcs`, `pac-ret`, (optionally with `pc`, `b-key`, `leaf` if `pac-ret` is set)";
     pub(crate) const parse_proc_macro_execution_strategy: &str =
         "one of supported execution strategies (`same-thread`, or `cross-thread`)";
-    pub(crate) const parse_remap_path_scope: &str = "comma separated list of scopes: `macro`, `diagnostics`, `debuginfo`, `coverage`, `object`, `all`";
     pub(crate) const parse_inlining_threshold: &str =
         "either a boolean (`yes`, `no`, `on`, `off`, etc), or a non-negative number";
     pub(crate) const parse_llvm_module_flag: &str = "<key>:<type>:<value>:<behavior>. Type must currently be `u32`. Behavior should be one of (`error`, `warning`, `require`, `override`, `append`, `appendunique`, `max`, `min`)";
@@ -1737,29 +1738,6 @@ pub mod parse {
         true
     }
 
-    pub(crate) fn parse_remap_path_scope(
-        slot: &mut RemapPathScopeComponents,
-        v: Option<&str>,
-    ) -> bool {
-        if let Some(v) = v {
-            *slot = RemapPathScopeComponents::empty();
-            for s in v.split(',') {
-                *slot |= match s {
-                    "macro" => RemapPathScopeComponents::MACRO,
-                    "diagnostics" => RemapPathScopeComponents::DIAGNOSTICS,
-                    "debuginfo" => RemapPathScopeComponents::DEBUGINFO,
-                    "coverage" => RemapPathScopeComponents::COVERAGE,
-                    "object" => RemapPathScopeComponents::OBJECT,
-                    "all" => RemapPathScopeComponents::all(),
-                    _ => return false,
-                }
-            }
-            true
-        } else {
-            false
-        }
-    }
-
     pub(crate) fn parse_relocation_model(slot: &mut Option<RelocModel>, v: Option<&str>) -> bool {
         match v.and_then(|s| RelocModel::from_str(s).ok()) {
             Some(relocation_model) => *slot = Some(relocation_model),
@@ -2614,8 +2592,6 @@ options! {
         "whether ELF relocations can be relaxed"),
     remap_cwd_prefix: Option<PathBuf> = (None, parse_opt_pathbuf, [TRACKED],
         "remap paths under the current working directory to this path prefix"),
-    remap_path_scope: RemapPathScopeComponents = (RemapPathScopeComponents::all(), parse_remap_path_scope, [TRACKED],
-        "remap path scope (default: all)"),
     remark_dir: Option<PathBuf> = (None, parse_opt_pathbuf, [UNTRACKED],
         "directory into which to write optimization remarks (if not specified, they will be \
 written to standard error output)"),

src/doc/rustc/src/command-line-arguments.md

@@ -428,6 +428,14 @@ specified multiple times.
 Refer to the [Remap source paths](remap-source-paths.md) section of this book for
 further details and explanation.
 
+<a id="option-remap-path-scope"></a>
+## `--remap-path-scope`: remap source paths in output
+
+Defines which scopes of paths should be remapped by `--remap-path-prefix`.
+
+Refer to the [Remap source paths](remap-source-paths.md) section of this book for
+further details and explanation.
+
 <a id="option-json"></a>
 ## `--json`: configure json messages printed by the compiler
 

src/doc/rustc/src/remap-source-paths.md

@@ -6,7 +6,7 @@ output, including compiler diagnostics, debugging information, macro expansions,
 This is useful for normalizing build products, for example, by removing the current directory
 out of the paths emitted into object files.
 
-The remapping is done via the `--remap-path-prefix` option.
+The remapping is done via the `--remap-path-prefix` flag and can be customized via the `--remap-path-scope` flag.
 
 ## `--remap-path-prefix`
 
@@ -39,6 +39,31 @@ rustc --remap-path-prefix "/home/user/project=/redacted"
 
 This example replaces all occurrences of `/home/user/project` in emitted paths with `/redacted`.
 
+## `--remap-path-scope`
+
+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 information
+- `coverage` - apply remappings to coverage information
+- `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`.
+
+The scopes accepted by `--remap-path-scope` are not exhaustive - new scopes may be added in future releases for eventual stabilisation.
+This implies that the `all` scope can correspond to different scopes between releases.
+
+### 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
+```
+
 ## Caveats and Limitations
 
 ### Paths generated by linkers

src/doc/unstable-book/src/compiler-flags/remap-path-scope.md

@@ -10,8 +10,8 @@
 //@ revisions: with_remap with_coverage_scope with_object_scope with_macro_scope
 //@ compile-flags: --remap-path-prefix={{src-base}}=remapped
 //
-//@[with_coverage_scope] compile-flags: -Zremap-path-scope=coverage
-//@[with_object_scope] compile-flags: -Zremap-path-scope=object
-//@[with_macro_scope] compile-flags: -Zremap-path-scope=macro
+//@[with_coverage_scope] compile-flags: --remap-path-scope=coverage
+//@[with_object_scope] compile-flags: --remap-path-scope=object
+//@[with_macro_scope] compile-flags: --remap-path-scope=macro
 
 fn main() {}

tests/coverage/remap-path-prefix.rs

@@ -10,9 +10,9 @@
    LL|       |//@ revisions: with_remap with_coverage_scope with_object_scope with_macro_scope
    LL|       |//@ compile-flags: --remap-path-prefix={{src-base}}=remapped
    LL|       |//
-   LL|       |//@[with_coverage_scope] compile-flags: -Zremap-path-scope=coverage
-   LL|       |//@[with_object_scope] compile-flags: -Zremap-path-scope=object
-   LL|       |//@[with_macro_scope] compile-flags: -Zremap-path-scope=macro
+   LL|       |//@[with_coverage_scope] compile-flags: --remap-path-scope=coverage
+   LL|       |//@[with_object_scope] compile-flags: --remap-path-scope=object
+   LL|       |//@[with_macro_scope] compile-flags: --remap-path-scope=macro
    LL|       |
    LL|      1|fn main() {}
 

tests/coverage/remap-path-prefix.with_macro_scope.coverage

@@ -97,15 +97,15 @@ fn main() {
         location_caller
             .crate_type("lib")
             .remap_path_prefix(cwd(), "/remapped")
-            .arg("-Zremap-path-scope=object")
+            .arg("--remap-path-scope=object")
             .input(cwd().join("location-caller.rs"));
         location_caller.run();
 
         let mut runner = rustc();
         runner
             .crate_type("bin")
             .remap_path_prefix(cwd(), "/remapped")
-            .arg("-Zremap-path-scope=diagnostics")
+            .arg("--remap-path-scope=diagnostics")
             .input(cwd().join("runner.rs"))
             .output(&runner_bin);
         runner.run();

tests/run-make/remap-path-prefix-consts/rmake.rs

@@ -105,7 +105,7 @@ fn check_dwarf_deps(scope: &str, dwarf_test: DwarfDump) {
     let mut rustc_sm = rustc();
     rustc_sm.input(cwd().join("src/some_value.rs"));
     rustc_sm.arg("-Cdebuginfo=2");
-    rustc_sm.arg(format!("-Zremap-path-scope={}", scope));
+    rustc_sm.arg(format!("--remap-path-scope={}", scope));
     rustc_sm.arg("--remap-path-prefix");
     rustc_sm.arg(format!("{}=/REMAPPED", cwd().display()));
     rustc_sm.arg("-Csplit-debuginfo=off");
@@ -117,7 +117,7 @@ fn check_dwarf_deps(scope: &str, dwarf_test: DwarfDump) {
     rustc_pv.input(cwd().join("src/print_value.rs"));
     rustc_pv.output(&print_value_rlib);
     rustc_pv.arg("-Cdebuginfo=2");
-    rustc_pv.arg(format!("-Zremap-path-scope={}", scope));
+    rustc_pv.arg(format!("--remap-path-scope={}", scope));
     rustc_pv.arg("--remap-path-prefix");
     rustc_pv.arg(format!("{}=/REMAPPED", cwd().display()));
     rustc_pv.arg("-Csplit-debuginfo=off");
@@ -158,8 +158,8 @@ fn check_dwarf(test: DwarfTest) {
     rustc.arg("-Cdebuginfo=2");
     if let Some(scope) = test.scope {
         match scope {
-            ScopeType::Object => rustc.arg("-Zremap-path-scope=object"),
-            ScopeType::Diagnostics => rustc.arg("-Zremap-path-scope=diagnostics"),
+            ScopeType::Object => rustc.arg("--remap-path-scope=object"),
+            ScopeType::Diagnostics => rustc.arg("--remap-path-scope=diagnostics"),
         };
         if is_darwin() {
             rustc.arg("-Csplit-debuginfo=off");

tests/run-make/remap-path-prefix-dwarf/rmake.rs

@@ -38,9 +38,9 @@ fn main() {
     rmeta_contains("/the/aux/lib.rs");
     rmeta_not_contains("auxiliary");
 
-    out_object.arg("-Zremap-path-scope=object");
-    out_macro.arg("-Zremap-path-scope=macro");
-    out_diagobj.arg("-Zremap-path-scope=diagnostics,object");
+    out_object.arg("--remap-path-scope=object");
+    out_macro.arg("--remap-path-scope=macro");
+    out_diagobj.arg("--remap-path-scope=diagnostics,object");
     if is_darwin() {
         out_object.arg("-Csplit-debuginfo=off");
         out_macro.arg("-Csplit-debuginfo=off");