debug: auto-path mapping can be confused with compound launch config

[hyangah]

In the go-guestbook sample, there are two go programs (frontend/main.go and backend/main.go).
They will start in separate containers - each of which builds main.go by copying the code into a work directory and running go build there. The frontend and the backend happen to be in different modules in this sample.

VS Code supports debugging two binaries together - a user can set breakpoints in both frontend/main.go and backend/main.go. VS Code by design sends breakpoint requests for all the files to all the debug adapters.

Since we cannot make any assumption on where the source code is copied in the remote container (i.e. in the sample, frontend/main.go is copied to /app/frontend/main.go, but it's also possible that the user just copy the source code to /app and build the binary from /app), the debug adapter tries to find the best match by doing some sort of longest suffix matching.

So, this longest suffix matching will end up associating /app/frontend/main.go on the remote frontend container with both frontend/main.go and backend/main.go in this specific example. As a result, the breakpoints set in backend/main.go will apply to the frontend/main.go.

@quoctruong proposed a workaround that compares the module names and rejects the breakpoints if they don't belong to the module name of debugee. (PR606).

After offline discussion (@polinasok @quoctruong @hyangah), we concluded this is a rare edge case where explicit mapping through configuration works better than adding extra complexity. Remaining tasks:

• File an issue for bookkeeping purpose
• Document our decision in the change and close (@quoctruong)
• Add the documentation

[polinasok]

What is the best place for adding documentation to flag this corner case to the users to let them know how to configure things? https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging? Do we have any other doc dedicated to path inference?

[hyangah]

@polinasok We don't have other doc. The remote debugging section seems to be the right place to discuss the path mapping. #45 is left open waiting for documentation to be done, and the current documentation references this issue.

The remote debugging section is currently surprisingly short considering the complexity.

[suzmue]

The mapping for a case like this can now be done through the substitutePath configuration.

For a project set up locally as:
/frontend/main.go
/backend/main.go

and remotely:
/app/main.go (containing source for /frontend/main.go)

The launch configuration would contain:

{
    "substitutePath": [
        { "from": "/frontend", "to": "/app" }
    ]
}