Add some documentation for -Zremap-path-prefix to the unstable book · rust-lang/rust@ab9691d (original) (raw)

File tree

2 files changed

lines changed

2 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -2,6 +2,7 @@
2 2
3 3 - [Compiler flags](compiler-flags.md)
4 4 - [linker_flavor](compiler-flags/linker-flavor.md)
5 +- [remap_path_prefix](compiler-flags/remap-path-prefix.md)
5 6 - [Language features](language-features.md)
6 7 - [abi_msp430_interrupt](language-features/abi-msp430-interrupt.md)
7 8 - [abi_ptx](language-features/abi-ptx.md)
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
1 +# `remap-path-prefix`
2 +
3 +The tracking issue for this feature is: [#41555](https://github.com/rust-lang/rust/issues/41555)
4 +
5 +------------------------
6 +
7 +The `-Z remap-path-prefix-from`, `-Z remap-path-prefix-to` commandline option
8 +pair allows to replace prefixes of any file paths the compiler emits in various
9 +places. This is useful for bringing debuginfo paths into a well-known form and
10 +for achieving reproducible builds independent of the directory the compiler was
11 +executed in. All paths emitted by the compiler are affected, including those in
12 +error messages.
13 +
14 +In order to map all paths starting with `/home/foo/my-project/src` to
15 +`/sources/my-project`, one would invoke the compiler as follows:
16 +
17 +```text
18 +rustc -Zremap-path-prefix-from="/home/foo/my-project/src" -Zremap-path-prefix-to="/sources/my-project"
19 +```
20 +
21 +Debuginfo for code from the file `/home/foo/my-project/src/foo/mod.rs`,
22 +for example, would then point debuggers to `/sources/my-project/foo/mod.rs`
23 +instead of the original file.
24 +
25 +The options can be specified multiple times when multiple prefixes should be
26 +mapped:
27 +
28 +```text
29 +rustc -Zremap-path-prefix-from="/home/foo/my-project/src" \
30 + -Zremap-path-prefix-to="/sources/my-project" \
31 + -Zremap-path-prefix-from="/home/foo/my-project/build-dir" \
32 + -Zremap-path-prefix-to="/stable-build-dir"
33 +```
34 +
35 +When the options are given multiple times, the nth `-from` will be matched up
36 +with the nth `-to` and they can appear anywhere on the commandline. Mappings
37 +specified later on the line will take precedence over earlier ones.