From b2249476b81c69b301675e5ff5f6046b6891f9ca Mon Sep 17 00:00:00 2001 From: Urgau Date: Wed, 11 Jun 2025 18:23:06 +0200 Subject: [PATCH] Improve `--remap-path-prefix` documentation --- src/doc/rustc/src/SUMMARY.md | 1 + src/doc/rustc/src/command-line-arguments.md | 21 ++++------ src/doc/rustc/src/remap-source-paths.md | 43 +++++++++++++++++++++ 3 files changed, 51 insertions(+), 14 deletions(-) create mode 100644 src/doc/rustc/src/remap-source-paths.md diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index a3939e5a5c451..063715763fb5b 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -23,6 +23,7 @@ - [Linker-plugin-based LTO](linker-plugin-lto.md) - [Checking Conditional Configurations](check-cfg.md) - [Cargo Specifics](check-cfg/cargo-specifics.md) +- [Remap source paths](remap-source-paths.md) - [Exploit Mitigations](exploit-mitigations.md) - [Symbol Mangling](symbol-mangling/index.md) - [v0 Symbol Format](symbol-mangling/v0.md) diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md index b704cee705b05..c7572a54cf93e 100644 --- a/src/doc/rustc/src/command-line-arguments.md +++ b/src/doc/rustc/src/command-line-arguments.md @@ -418,22 +418,15 @@ This flag takes a number that specifies the width of the terminal in characters. Formatting of diagnostics will take the width into consideration to make them better fit on the screen. -## `--remap-path-prefix`: remap source names in output +## `--remap-path-prefix`: remap source paths in output Remap source path prefixes in all output, including compiler diagnostics, -debug information, macro expansions, etc. It takes a value of the form -`FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`. -The `FROM` may itself contain an `=` symbol, but the `TO` value may not. This -flag may be specified multiple times. - -This is useful for normalizing build products, for example by removing the -current directory out of pathnames emitted into the object files. The -replacement is purely textual, with no consideration of the current system's -pathname syntax. For example `--remap-path-prefix foo=bar` will match -`foo/lib.rs` but not `./foo/lib.rs`. - -When multiple remappings are given and several of them match, the **last** -matching one is applied. +debug information, macro expansions, etc. It takes a value of the form `FROM=TO` +where a path prefix equal to `FROM` is rewritten to the value `TO`. This flag may be +specified multiple times. + +Refer to the [Remap source paths](remap-source-paths.md) of this book for +further details and explanation. ## `--json`: configure json messages printed by the compiler diff --git a/src/doc/rustc/src/remap-source-paths.md b/src/doc/rustc/src/remap-source-paths.md new file mode 100644 index 0000000000000..d6e8b117159f9 --- /dev/null +++ b/src/doc/rustc/src/remap-source-paths.md @@ -0,0 +1,43 @@ +# Remap source paths + +`rustc` supports remaping source paths prefixes *(as a best effort)* in all output, including +compiler diagnostics, debug information, macro expansions, etc. + +This is useful for normalizing build products, for example by removing the current directory +out of the paths emitted into the object files. + +The remaping is done via the `--remap-path-prefix` option. + +## `--remap-path-prefix` + +It takes a value of the form `FROM=TO` where a path prefix equal to `FROM` is rewritten +to the value `TO`. `FROM` may itself contain an `=` symbol, but `TO` value may not. + +The replacement is purely textual, with no consideration of the current system's path separator. + +When multiple remappings are given and several of them match, the **last** matching one is applied. + +### Example + +```bash +rustc --remap-path-prefix "/home/user/project=/redacted" +``` + +This example replaces all occurrences of `/home/user/project` in emitted paths with `/redacted`. + +## Caveats and Limitations + +- **Linkers generated paths**: On some platforms, especially Windows, the linker (such as `link.exe`) + may embed absolute host paths and compiler arguments into debug info files (like `.pdb`) independently + of rustc. + + The `--remap-path-prefix` option does not affect these linker-generated paths. + +- **Textual replacement only**: The remapping is strictly textual and does not account for different + path separator conventions across platforms. Care must be taken when specifying prefixes, especially + on Windows where both `/` and `\` may appear in paths. + +- **External tools**: Paths introduced by external tools or environment + variables may not be covered by `--remap-path-prefix` unless explicitly accounted for. + + For example, generated code introduced by Cargo's build script.