add `sourceFileMap` setting for conversion of paths between ide and gdb

[GitMensch]

This may be useful for both the WSL scenario and for external debugging where the source path on the client (vscode) is not the same as the debugger (gdbserver, possibly running on wsl) sees:

I suggest to add a sourceFileMap setting. This would need to applied anywhere the client passes paths (breakpoints, "go to cursor") and when the client receives paths (I guess that's the stack only).

Originally posted by @GitMensch in https://github.com/Marus/cortex-debug/issues/467#issuecomment-1063129125

---

People are using their own gdb-init scripts to [do path substitutions] - No help from extension needed.

The bigger problem is how breakpoints are set and how stack traces are interpreted. Disassembly is affected as well.. How we look for static variables is also affected -- as in we have to implement what gdb does. VSCode manages breakpoints with paths (file/line) that it sees. It wasn't clear to me how gdb handled file/line breakpoints and if clients (us) have to do the reverse mapping. [..m]

cpptools/cppdbg added support for source maps. We can check to see what all they do with that info.

Originally posted by @haneefdm in https://github.com/Marus/cortex-debug/issues/467#issuecomment-1063201875

[GitMensch]

The issue is that the ide through DAP sends requests, at least the following:

• create a breakpoint at some path:line
• go to some path:line
• maybe (I don't know): open disassembly for file/function

When the ide and the running debugger doesn't have the sources on the same place then there needs to be a mapping - for example in a WSL case X:\projects\cortex\app vs. /home/me/app - GDB won't understand the former when send from the IDE and path substitutions or source paths don't apply to that, so the dap-implementation needs to provide the mapping before sending the paths to GDB.

Similar GDB sends paths back, especially:

• stack information
• breakpoint information (for example when a function breakpoint is set)

In this case there needs to be a reverse mapping.

The start of a solution was merged upstream, it may be a useful start - or at least showcase for the principles (note: this isn't 100% finished yet and has at least one bug in that slipped in with Win32 support); and I'd say the "target" is likely always posix, so it can be simplified, too. https://github.com/WebFreak001/code-debug/pull/323/commits/ecb2da4b4ccc8e3249c50dd0a071f69c2b7b875a

[saloid]

Here is my workaround for now, add it into launch.json into your configuration:

"preAttachCommands": [
                "set substitute-path /path/during/build /path/for/debuging",
            ],

You can also use ${workspaceRoot} variable in path. Found it here: https://alex.dzyoba.com/blog/gdb-source-path/

[GitMensch]

Thanks for the note, but as previously said;

When the ide and the running debugger doesn't have the sources on the same place then there needs to be a mapping - for example in a WSL case X:\projects\cortex\app vs. /home/me/app - GDB won't understand the former when send from the IDE and path substitutions or source paths don't apply to that, so the dap-implementation needs to provide the mapping before sending the paths to GDB.

If you use GDB on the same machine where the sources reside and the sources in the IDE are in the same place (either because the machine is identical, which isn't necessary the case with extended-remote; or because ... you have a copy on the correct place or use / network paths in both cases) then GDB's substitute-path is enough. In the case of remote debugging via ssh (GDB isn't even running where the IDE is running) this commonly isn't the case (and you may even need both path substitution (for GDB) and a source mapping (IDE<->GDB)

[dsabala]

@saloid Thanks for set substitute-path tip, this was the last thing that I need to use Docker builds on daily basis without using Devcontainers plugin

[ethpch]

I'm debugging with Andes toolchains based on Cygwin. While hitting breakpoint vscode opens an editor path to "/cygdrive/c/..." and shows "cannot find this file". Command set substitute-path doesn't work with me.

Here is the launch and screenshot:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "HPM6750 Debug",
            "type": "cortex-debug",
            "request": "launch",
            "executable": "${command:cmake.launchTargetPath}",
            "cwd": "${workspaceFolder}",
            "interface": "jtag",
            "device": "HPM6750",
            "runToEntryPoint": "main",
            "servertype": "openocd",
            "searchDir": [
                "${env:OPENOCD_SCRIPTS}"
            ],
            "configFiles": [
                "probes/jlink.cfg",
                "soc/hpm6750-single-core.cfg",
                "boards/hpm6750evk.cfg"
            ],
            "overrideLaunchCommands": [
                "set substitute-path /cygdrive/c/ c:\\\\",
                "monitor reset halt",
                "load"
            ],
            "overrideResetCommands": [
                "set substitute-path /cygdrive/c/ c:\\\\",
                "monitor reset halt",
                "load"
            ],
            "overrideRestartCommands": [
                "set substitute-path /cygdrive/c/ c:\\\\",
                "monitor reset halt",
                "load"
            ],
            "showDevDebugOutput": "raw"
        }
    ]
}

I found the gdb breaks at the right location C:/.../hello_world/src/hello_world.c:17, but the next text shows file="C:/.../hello_world/src/hello_world.c" and fullname="/cygdrive/c/.../hello_world/src/hello_world.c". Maybe vscode processes breakpoint by fullname, and andes toolchain(Cygwin) always parse absolute path with prefix /cygdrive/c/....

I have tried with cpptools, the set substitute-path command doesn't work but sourceFileMap setting works well.

Is there any update? @haneefdm