src/debugAdapter: add substitutePath config for debugging

This change adds a new configuration option to both launch and
attach requests. substituePath takes an array that maps from string to string
that is used to translate paths passed to the debugger and then
back to the client.

This allows users to translate their symlinked directories to the
files that were actually used to build the binary. In addition this
can also be used for remote debugging, and when the location of the
files has moved since the program was built.

Update #622

Change-Id: I71b081d17a29655c14cd20093dc9f88867fbcc69
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/270017
Trust: Suzy Mueller <[email protected]>
Trust: Hyang-Ah Hana Kim <[email protected]>
Run-TryBot: Suzy Mueller <[email protected]>
TryBot-Result: kokoro <[email protected]>
Reviewed-by: Polina Sokolova <[email protected]>
Reviewed-by: Hyang-Ah Hana Kim <[email protected]>

Author: suzmue

Diff for: docs/debugging.md

@@ -110,7 +110,8 @@ args       | Array of command-line arguments to pass to the program being debugg
 showLog    | If `true`, Delve logs will be printed in the Debug Console panel.
 logOutput  | Comma-separated list of Delve components (`debugger`, `gdbwire`, `lldbout`, `debuglineerr`, `rpc`) that should produce debug output when `showLog` is `true`.
 buildFlags | Build flags to pass to the Go compiler.
-remotePath | If remote debugging (`mode`: `remote`), this should be the absolute path to the package being debugged on the remote machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant.
+remotePath | If remote debugging (`mode`: `remote`), this should be the absolute path to the package being debugged on the remote machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant. Becomes the first mapping in substitutePath.
+substitutePath | An array of mappings from an absolute local path to an absolute remote path that is used by the debuggee. The debug adapter will replace the local path with the remote path in all of the calls. The mappings are applied in order, and the first matching mapping is used. This can be used to map files that have moved since the program was built, different remote paths, and symlinked files or directories. This is intended to be equivalent to the [substitute-path]((https://github.com/go-delve/delve/tree/master/Documentation/cli#config)(https://github.com/go-delve/delve/tree/master/Documentation/cli#config)) configuration, and will eventually configure substitute-path in Delve directly.
 cwd | The working directory to be used in running the program. If remote debugging (`mode`: `remote`), this should be the absolute path to the working directory being debugged on the local machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant.
 processId  | This is the process ID of the executable you want to debug. Applicable only when using the `attach` request in `local` mode.
 
@@ -308,7 +309,27 @@ Then, create a remote debug configuration in your `launch.json`.
 
 In the example, the VS Code debugger will run on the same machine as the headless `dlv` server. Make sure to update the `port` and `host` settings to point to your remote machine.
 
-`remotePath` should point to the absolute path of the program being debugged in the remote machine. `cwd` should point to the absolute path of the working directory of the program being debugged on your local machine. This should be the counterpart of the folder in `remotePath`. See [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) for updates regarding `remotePath` and `cwd`.
+`remotePath` should point to the absolute path of the program being debugged in the remote machine. `cwd` should point to the absolute path of the working directory of the program being debugged on your local machine. This should be the counterpart of the folder in `remotePath`. See [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) for updates regarding `remotePath` and `cwd`. You can also use the equivalent `substitutePath` configuration.
+
+```json5
+{
+    "name": "Launch remote",
+    "type": "go",
+    "request": "attach",
+    "mode": "remote",
+    "substitutePath": [
+		{
+			"from": "/absolute/path/dir/on/local/machine",
+			"to": "/absolute/path/dir/on/remote/machine",
+		},
+	],
+    "port": 2345,
+    "host": "127.0.0.1",
+    "cwd": "/absolute/path/dir/on/local/machine",
+}
+```
+
+If you do not set, `remotePath` or `substitutePath`, then the debug adapter will attempt to infer the path mappings. See [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) for more information.
 
 When you run the `Launch remote` target, VS Code will send debugging commands to the `dlv` server you started, instead of launching it's own `dlv` instance against your program.
 
@@ -405,9 +426,25 @@ This error can show up for Mac users using Delve versions 0.12.2 and above. `xco
 
 ### Debugging symlink directories
 
-This extension does not provide support for debugging projects containing symlinks. Make sure that you are setting breakpoints in the files that Go will use to compile your program.
+Since the debugger and go compiler use the actual filenames, extra configuration is required to debug symlinked directories. Use the `substitutePath` property to tell the debugAdapter how to properly translate the paths. For example, if your project lives in `/path/to/actual/helloWorld`, but the project is open in vscode under the linked folder `/path/to/hello`, you can add the following to your config to set breakpoints in the files in `/path/to/hello`:
+
+```json5
+{
+    "name": "Launch remote",
+    "type": "go",
+    "request": "launch",
+    "mode": "auto",
+    "program": "/path/to/hello",
+    "substitutePath": [
+		{
+			"from": "/path/to/hello",
+			"to": "/path/to/actual/helloWorld",
+		},
+	],
+}
+```
 
-For updates to symlink support reference [golang/vscode-go#622](https://github.com/golang/vscode-go/issues/622).
+This extension does not provide general support for debugging projects containing symlinks. If `substitutePath` does not meet your needs, please consider commenting on this issue that contains updates to symlink support reference [golang/vscode-go#622](https://github.com/golang/vscode-go/issues/622).
 
 [Delve]: https://github.com/go-delve/delve
 [VS Code variables]: https://code.visualstudio.com/docs/editor/variables-reference

Diff for: package.json

@@ -522,6 +522,26 @@
                 "description": "Environment variables passed to the program.",
                 "default": {}
               },
+              "substitutePath": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "from": {
+                      "type": "string",
+                      "description": "The absolute local path to be replaced when passing paths to the debugger",
+                      "default": ""
+                    },
+                    "to": {
+                      "type": "string",
+                      "description": "The absolute remote path to be replaced when passing paths back to the client",
+                      "default": ""
+                    }
+                  }
+                },
+                "description": "An array of mappings from a local path to the remote path that is used by the debuggee. The debug adapter will replace the local path with the remote path in all of the calls. Overriden by remotePath.",
+                "default": []
+              },
               "buildFlags": {
                 "type": "string",
                 "description": "Build flags, to be passed to the Go compiler.",
@@ -534,7 +554,7 @@
               },
               "remotePath": {
                 "type": "string",
-                "description": "Absolute path to the file being debugged on the remote machine in case of remote debugging.",
+                "description": "Absolute path to the file being debugged on the remote machine in case of remote debugging. If specified, becomes the first entry in substitutePath.",
                 "default": ""
               },
               "port": {
@@ -680,7 +700,7 @@
               },
               "remotePath": {
                 "type": "string",
-                "description": "If remote debugging, the path to the source code on the remote machine, if different from the local machine.",
+                "description": "If remote debugging, the path to the source code on the remote machine, if different from the local machine. If specified, becomes the first entry in substitutePath.",
                 "default": ""
               },
               "port": {
@@ -693,6 +713,26 @@
                 "description": "The host name of the machine the delve debugger will be listening on.",
                 "default": "127.0.0.1"
               },
+              "substitutePath": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "from": {
+                      "type": "string",
+                      "description": "The absolute local path to be replaced when passing paths to the debugger",
+                      "default": ""
+                    },
+                    "to": {
+                      "type": "string",
+                      "description": "The absolute remote path to be replaced when passing paths back to the client",
+                      "default": ""
+                    }
+                  }
+                },
+                "description": "An array of mappings from a local path to the remote path that is used by the debuggee. The debug adapter will replace the local path with the remote path in all of the calls.",
+                "default": []
+              },
               "trace": {
                 "type": "string",
                 "enum": [
@@ -1063,7 +1103,7 @@
               },
               "remotePath": {
                 "type": "string",
-                "description": "If remote debugging, the path to the source code on the remote machine, if different from the local machine.",
+                "description": "If remote debugging, the path to the source code on the remote machine, if different from the local machine. If specified, becomes the first entry in substitutePath.",
                 "default": ""
               },
               "port": {

Diff for: src/debugAdapter/goDebug.ts

@@ -276,6 +276,7 @@ interface LaunchRequestArguments extends DebugProtocol.LaunchRequestArguments {
 	trace?: 'verbose' | 'log' | 'error';
 	backend?: string;
 	output?: string;
+	substitutePath?: {from: string, to: string}[];
 	/** Delve LoadConfig parameters */
 	dlvLoadConfig?: LoadConfig;
 	dlvToolPath: string;
@@ -307,6 +308,7 @@ interface AttachRequestArguments extends DebugProtocol.AttachRequestArguments {
 	host?: string;
 	trace?: 'verbose' | 'log' | 'error';
 	backend?: string;
+	substitutePath?: {from: string, to: string}[];
 	/** Delve LoadConfig parameters */
 	dlvLoadConfig?: LoadConfig;
 	dlvToolPath: string;
@@ -369,6 +371,10 @@ function normalizePath(filePath: string) {
 	return filePath;
 }
 
+function normalizeSeparators(filePath: string): string {
+	return filePath.replace(/\/|\\/g, '/');
+}
+
 function getBaseName(filePath: string) {
 	return filePath.includes('/') ? path.basename(filePath) : path.win32.basename(filePath);
 }
@@ -853,6 +859,9 @@ export class GoDebugSession extends LoggingDebugSession {
 	private localToRemotePathMapping = new Map<string, string>();
 	private remoteToLocalPathMapping = new Map<string, string>();
 
+	// TODO(suzmue): Use delve's implementation of substitute-path.
+	private substitutePath: {from: string, to: string}[];
+
 	private showGlobalVariables: boolean = false;
 
 	private continueEpoch = 0;
@@ -1038,7 +1047,7 @@ export class GoDebugSession extends LoggingDebugSession {
 	}
 
 	protected async toDebuggerPath(filePath: string): Promise<string> {
-		if (this.delve.remotePath.length === 0) {
+		if (this.substitutePath.length === 0) {
 			if (this.delve.isRemoteDebugging) {
 				// The user trusts us to infer the remote path mapping!
 				await this.initializeRemotePackagesAndSources();
@@ -1047,14 +1056,28 @@ export class GoDebugSession extends LoggingDebugSession {
 					return matchedRemoteFile;
 				}
 			}
+
 			return this.convertClientPathToDebugger(filePath);
 		}
 
 		// The filePath may have a different path separator than the localPath
-		// So, update it to use the same separator as the remote path to ease
-		// in replacing the local path in it with remote path
-		filePath = filePath.replace(/\/|\\/g, this.remotePathSeparator);
-		return filePath.replace(this.delve.program.replace(/\/|\\/g, this.remotePathSeparator), this.delve.remotePath);
+		// So, update it to use the same separator for ease in path replacement.
+		filePath = normalizeSeparators(filePath);
+		let substitutedPath = filePath;
+		let substituteRule: {from: string, to: string};
+		this.substitutePath.forEach((value) => {
+			if (filePath.startsWith(value.from)) {
+				if (!!substituteRule) {
+					log(`Substitutition rule ${value.from}:${value.to} applies to local path ${filePath} but it was already mapped to debugger path using rule ${substituteRule.from}:${substituteRule.to}`);
+					return;
+				}
+				substitutedPath = filePath.replace(value.from, value.to);
+				substituteRule = {from: value.from, to: value.to};
+			}
+		});
+		filePath = substitutedPath;
+
+		return filePath = filePath.replace(/\/|\\/g, this.remotePathSeparator);
 	}
 
 	/**
@@ -1203,19 +1226,36 @@ export class GoDebugSession extends LoggingDebugSession {
 	 * have been initialized.
 	 */
 	protected toLocalPath(pathToConvert: string): string {
-		if (this.delve.remotePath.length === 0) {
+		if (this.substitutePath.length === 0) {
 			// User trusts use to infer the path
 			if (this.delve.isRemoteDebugging) {
 				const inferredPath = this.inferLocalPathFromRemotePath(pathToConvert);
 				if (inferredPath) {
 					return inferredPath;
 				}
 			}
+
 			return this.convertDebuggerPathToClient(pathToConvert);
 		}
 
+		// If there is a substitutePath mapping, then we replace the path.
+		pathToConvert = normalizeSeparators(pathToConvert);
+		let substitutedPath = pathToConvert;
+		let substituteRule: {from: string, to: string};
+		this.substitutePath.forEach((value) => {
+			if (pathToConvert.startsWith(value.to)) {
+				if (!!substituteRule) {
+					log(`Substitutition rule ${value.from}:${value.to} applies to debugger path ${pathToConvert} but it was already mapped to local path using rule ${substituteRule.from}:${substituteRule.to}`);
+					return;
+				}
+				substitutedPath = pathToConvert.replace(value.to, value.from);
+				substituteRule = {from: value.from, to: value.to};
+			}
+		});
+		pathToConvert = substitutedPath;
+
 		// When the pathToConvert is under GOROOT or Go module cache, replace path appropriately
-		if (!pathToConvert.startsWith(this.delve.remotePath)) {
+		if (!substituteRule) {
 			// Fix for https://github.com/Microsoft/vscode-go/issues/1178
 			const index = pathToConvert.indexOf(`${this.remotePathSeparator}src${this.remotePathSeparator}`);
 			const goroot = this.getGOROOT();
@@ -1239,7 +1279,6 @@ export class GoDebugSession extends LoggingDebugSession {
 			}
 		}
 		return pathToConvert
-			.replace(this.delve.remotePath, this.delve.program)
 			.split(this.remotePathSeparator)
 			.join(this.localPathSeparator);
 	}
@@ -1835,6 +1874,7 @@ export class GoDebugSession extends LoggingDebugSession {
 		}
 
 		this.localPathSeparator = findPathSeparator(localPath);
+		this.substitutePath = [];
 		if (args.remotePath.length > 0) {
 			this.remotePathSeparator = findPathSeparator(args.remotePath);
 
@@ -1857,6 +1897,25 @@ export class GoDebugSession extends LoggingDebugSession {
 			) {
 				args.remotePath = args.remotePath.substring(0, args.remotePath.length - 1);
 			}
+
+			// Make the remotePath mapping the first one in substitutePath
+			// so that it will take precedence over the other mappings.
+			this.substitutePath.push({
+				from: normalizeSeparators(localPath),
+				to: normalizeSeparators(args.remotePath)
+			});
+		}
+
+		if (!!args.substitutePath) {
+			args.substitutePath.forEach((value) => {
+				if (!this.remotePathSeparator) {
+					this.remotePathSeparator = findPathSeparator(value.to);
+				}
+				this.substitutePath.push({
+					from: normalizeSeparators(value.from),
+					to: normalizeSeparators(value.to)
+				});
+			});
 		}
 
 		// Launch the Delve debugger on the program