# `-Ztrim-paths` mapping rules

Issue: https://github.com/rust-lang/cargo/issues/13171

There are at least five kinds of source paths Cargo need to remap:

* Standard library
* Registry dependencies
* Git dependencies
* Local dependencies (including path dependencies, vendored sources, `[patch]`)
* Generated source (from build scripts)

> Maybe there are more. Would proc macros play a different role? What about the `#[path]` attribute?`

## Design requirements (priority order)

* **Leak nothing.** The expectation of which paths are covered must be set.
* **Easy to configure debuggers.** The fewer settings on debugger side to restore mapping, the better.
* **Trimmed paths to be stable across toolchain versions.** For example, a remapped path `registry/src/foo-0.1.0` should not change between versions.

## Things to consider

* Paths substitution is not a feature supported everywhere. For example, WinDbg and MSVC debugger can only set diretory prefixes. [REF](https://github.com/rust-lang/cargo/issues/13171#issuecomment-1860789526)
* However, std is already remapped to `/rustc/<commit-hash>`, so a path substitution is required anyway for debugging std.
* `CARGO_HOME` has not yet split to multiple directories by functionalities (I tried really hard to avoid using the word XDG). This means the path is not going to be stable, though that might be considered out of scope of RFC 3127.
* The current registry source directory, e.g., `index.crates.io-6f17d22bba15001f`, is leaking the server URL/IP information in its own path. We cannot simply remove it because the path should be as stable as possible.
* Symbol servers / Source Link support ([Zulip discussion](https://rust-lang.zulipchat.com/#narrow/stream/317568-t-compiler.2Fwg-debugging/topic/Source.20Link))
* [Source Link JSON Schema](https://github.com/dotnet/designs/blob/a447d77bb53d189746ccd80c2d814064c2b6c606/accepted/2020/diagnostics/source-link.md)
* [/SOURCELINK](https://learn.microsoft.com/en-us/cpp/build/reference/sourcelink?view=msvc-170) to include Source Link file in PDB
* [DWARF 6 support](https://dwarfstd.org/issues/181223.1.html)
* GDB doesn't have such a concept.

## Proposals

There are two different directions:

#### Remap to relative paths.

Pros:

* Doesn't require path prefix substitution at debug time (good for WinDbg)
* Simpler debug configuration. Only need to set some source paths/directories.

Cons:

* Std still needs path substitutions
* Tied to the file system layout. Means that we need to stabilize more things

#### Remap to a fixed prefix for each kind of source

* Standard library
* Follow what has done in rustc
* `~/.rustup/toolchain/<channel>/lib/rustlib/src/rust` -> `/rustc/<commit-hash>`
* Already needs to work around for this path substituion for WinDbg
* Registry dependencies
*
* Git dependencies
* Local dependencies (including path dependencies, vendored sources, `[patch]`)
* Generated source (from build scripts)