From 9f15c4f22f194cf7782dd7224119ed4fe0f7b82f 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 | 53 +++++++++++++++++++++ 3 files changed, 61 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 7c688e32bc0dd..07d53915496de 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 d45ad1be27b8c..a718738870265 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..084e93b82a64e --- /dev/null +++ b/src/doc/rustc/src/remap-source-paths.md @@ -0,0 +1,53 @@ +# Remap source paths + +`rustc` supports remapping source paths prefixes **as a best effort** in all compiler generated +output, including compiler diagnostics, debug informations, 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 remapping 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, the linker (such as `link.exe`) may embed absolute host paths and compiler arguments +into debug info files (like `.pdb`) independently of rustc. + +This currently the case on Apple linkers where the [OSO entries] are not remapped by the compiler and +needs to be manually remapped with `-oso_prefix`. + +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. + +[OSO entries]: https://wiki.dwarfstd.org/Apple%27s_%22Lazy%22_DWARF_Scheme.md