Stabilize -Zremap-path-scope as --remap-path-scope

In the process also document that new `--remap-path-scope` scopes may be
added in the future, and that the `all` always represent all the scopes.

Co-authored-by: David Wood <[email protected]>

Author: Urgau

compiler/rustc_session/src/config.rs

@@ -1395,6 +1395,29 @@ bitflags::bitflags! {
     }
 }
 
+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>,
@@ -1431,18 +1454,18 @@ 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(),
-        if unstable_opts.remap_path_scope.contains(RemapPathScopeComponents::DIAGNOSTICS)
+        if remap_path_scope.contains(RemapPathScopeComponents::DIAGNOSTICS)
             && !remap_path_prefix.is_empty()
         {
             FileNameDisplayPreference::Remapped
         } else {
             FileNameDisplayPreference::Local
         },
-        if unstable_opts.remap_path_scope.is_all() {
+        if remap_path_scope.is_all() {
             FileNameEmbeddablePreference::RemappedOnly
         } else {
             FileNameEmbeddablePreference::LocalAndRemapped
@@ -1484,6 +1507,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,
@@ -1510,7 +1534,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.
@@ -1951,6 +1975,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| {
@@ -2849,6 +2881,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);
 
@@ -2912,7 +2945,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);
     let working_dir = file_mapping.to_real_filename(&working_dir);
 
     let verbose = matches.opt_present("verbose") || unstable_opts.verbose_internals;
@@ -2949,6 +2982,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`
@@ -869,7 +871,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`)";
@@ -1693,29 +1694,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),
@@ -2565,8 +2543,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)"),

compiler/rustc_session/src/session.rs

@@ -877,7 +877,7 @@ impl Session {
             scope.bits().count_ones() == 1,
             "one and only one scope should be passed to `Session::filename_display_preference`"
         );
-        if self.opts.unstable_opts.remap_path_scope.contains(scope) {
+        if self.opts.remap_path_scope.contains(scope) {
             FileNameDisplayPreference::Remapped
         } else {
             FileNameDisplayPreference::Local
@@ -1544,7 +1544,7 @@ impl RemapFileNameExt for rustc_span::FileName {
             scope.bits().count_ones() == 1,
             "one and only one scope should be passed to for_scope"
         );
-        if sess.opts.unstable_opts.remap_path_scope.contains(scope) {
+        if sess.opts.remap_path_scope.contains(scope) {
             self.prefer_remapped_unconditionally()
         } else {
             self.prefer_local()
@@ -1560,7 +1560,7 @@ impl RemapFileNameExt for rustc_span::RealFileName {
             scope.bits().count_ones() == 1,
             "one and only one scope should be passed to for_scope"
         );
-        if sess.opts.unstable_opts.remap_path_scope.contains(scope) {
+        if sess.opts.remap_path_scope.contains(scope) {
             self.remapped_path_if_available()
         } else {
             self.local_path_if_available()

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`
 
@@ -25,6 +25,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
 
 ### Linkers generated paths

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

@@ -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");