gitlab.com/Raven-IO/raven-delve@v1.22.4/Documentation/cli/substitutepath.md (about)

     1  ## Path substitution configuration
     2  
     3  Normally Delve finds the path to the source code that was used to produce an executable by looking at the debug symbols of the executable.
     4  However, under [some circumstances](../faq.md#substpath), the paths that end up inside the executable will be different from the paths to the source code on the machine that is running the debugger. If that is the case Delve will need extra configuration to convert the paths stored inside the executable to paths in your local filesystem.
     5  
     6  This configuration is done by specifying a list of path substitution rules.
     7  
     8  
     9  ### Where are path substitution rules specified
    10  
    11  #### Delve command line client
    12  
    13  The command line client reads the path substitution rules from Delve's YAML configuration file located at `$XDG_CONFIG_HOME/dlv/config.yml` or `.dlv/config.yml` inside the home directory on Windows.
    14  
    15  The `substitute-path` entry should look like this:
    16  
    17  ```
    18  substitute-path:
    19    - {from: "/compiler/machine/directory", to: "/debugger/machine/directory"}
    20    - {from: "", to: "/mapping/for/relative/paths"}
    21  ```
    22  
    23  If you are starting a headless instance of Delve and connecting to it through `dlv connect` the configuration file that is used is the one that runs `dlv connect`.
    24  
    25  The rules can also be modified while Delve is running by using the [config substitute-path command](./README.md#config):
    26  
    27  ```
    28  (dlv) config substitute-path /from/path /to/path
    29  ```
    30  
    31  Double quotes can be used to specify paths that contain spaces, or to specify empty paths:
    32  
    33  ```
    34  (dlv) config substitute-path "/path containing spaces/" /path-without-spaces/
    35  (dlv) config substitute-path /make/this/path/relative ""
    36  ```
    37  
    38  #### DAP server
    39  
    40  If you connect to Delve using the DAP protocol then the substitute path rules are specified using the substitutePath option in [launch.json](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#launchjson-attributes).
    41  
    42  ```
    43  	"substitutePath": [
    44  		{ "from": "/from/path", "to": "/to/path" }
    45  	]
    46  ```
    47  
    48  The [debug console](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#dlv-command-from-debug-console) can also be used to modify the path substitution list:
    49  
    50  ```
    51  dlv config substitutePath /from/path /to/path
    52  ```
    53  
    54  This command works similarly to the `config substitute-path` command described above.
    55  
    56  ### How are path substitution rules applied
    57  
    58  Regardless of how they are specified the path substitution rules are an ordered list of `(from-path, to-path)` pairs. When Delve needs to convert a path P found inside the executable file into a path in the local filesystem it will scan through the list of rules looking for the first one where P starts with from-path and replace from-path with to-path.
    59  
    60  Empty paths in both from-path and to-path are special, they represent relative paths: 
    61  
    62  - `(from="" to="/home/user/project/src")` converts all relative paths in the executable to absolute paths in `/home/user/project/src`
    63  - `(from="/build/dir" to="")` converts all paths in the executable that start with `/build/dir` into relative paths.
    64  
    65  The path substitution code is SubstitutePath in pkg/locspec/locations.go.
    66