[vscode-go] docs/debugging.md: instruction for `console` and debugging as root
Hyang-Ah Hana Kim (Gerrit)
Hyang-Ah Hana Kim has uploaded this change for review.
docs/debugging.md: instruction for `console` and debugging as root
Fixes golang/vscode-go#124
Fixes golang/vscode-go#558
Updates golang/vscode-go#1424
Change-Id: Ic2a32657c30e4a8ca238239c2200f870cf949732
---
M docs/debugging.md
1 file changed, 100 insertions(+), 0 deletions(-)
diff --git a/docs/debugging.md b/docs/debugging.md
index 4856e81..8b76fa2 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -343,6 +343,93 @@
For information on debugging using the legacy debug adapter, please see the old [Debugging Documentation](https://github.com/golang/vscode-go/blob/master/docs/debugging.md). Note that many new or enhanced features discussed in this document may not be available with the legacy debug adapter.
+### Handling STDIN
+
+The Go extension and the `dlv` started as a subprocess of the extension do not have access to `tty`. The Go extension captures and forwards STDOUT/STDERR of the debug program to VS Code, so they can appear in `DEBUG OUTPUT` panel. But this arrangement does not handle STDIN.
+
+When the target program needs to read from STDIN or access terminals (`tty`), use the `"console"` launch option that controls where the `dlv` debugger and the target process run:
+
+* `integratedTerminal` for the terminal inside VS Code
+* `externalTerminal` for the terminal outside VS Code
+
+The Go extension delegates interaction with terminals to VS Code [using Debug Adapter Protocol's `RunInTerminal` functionality](https://github.com/golang/vscode-go/discussions/1626). For configuring VS Code's terminal related behavior, see VS Code's [documentation](https://code.visualstudio.com/docs/editor/integrated-terminal).
+
+### Debugging a program as root
+
+In order to run and debug a program running as root, the debugger (`dlv`) requires to run with root privilege, too. You can start the debug session with root privilege utilizing the `"asRoot"` AND `"console"` launch options. This is currently supported only on Linux and Mac.
+
+When `asRoot` is true, the Go extension will use the `sudo` command to run `dlv`. Since `sudo` may ask you to enter password, the debug session needs [terminal access](#handling-stdin) so needs `"console": "integratedTerminal"` or `"console": "externalTerminal"` configuration.
+
+For example, the following launch configuration will start the `myprogram` and debug it by running `sudo dlv dap` command in the integrated terminal.
+
+```json
+{
+ "name": "Launch as Root",
+ "request": "launch",
+ "mode": "exec",
+ "asRoot": true,
+ "program": "${workspaceRoot}/myprogram",
+ "console": "integratedTerminal",
+ ...
+}
+```
+
+The `asRoot` setting can be used with `auto`/`test`/`debug` launch modes that **builds** the target binary to debug. That means the `go` command to compile the binary will be invoked as root, too. This can cause issues:
+
+* by default, `sudo` does not preserve the user's current environment variables (see documentations about sudo's `--preserve-env` option). For example, `PATH` or library paths required for build may be different.
+* Go environment variable settings usually associated in the home directory are different.
+* Module cache and build cache can be different.
+
+Instead, you can arrange the `exec` launch mode to work with a pre-launch [task](https://code.visualstudio.com/docs/editor/tasks).
+
+First, configure a debug build task to compile the target binary.
+
+In `.vscode/tasks.json`:
+```json
+{
+ ...
+ "tasks": [
+ {
+ "label": "go: build (debug)",
+ "command": "go",
+ "args": [
+ "build",
+ "-gcflags=all=-N -l",
+ "-o",
+ "${fileDirname}/__debug_bin"
+ ],
+ "options": {
+ "cwd": "${fileDirname}"
+ }
+ ...
+ }
+ ]
+}
+```
+
+The `-gcflags=all=-N -l` flag tells the `go build` command to preserve the debug information. The `-o` flag causes the compiled binary to be placed in `"${fileDirname}/__debug_bin"`. Extra build flags and environment variables *used for build* should be configured here as `args` or `options`'s `env` settings.
+
+Then, configure the launch config to run the task before starting debugging.
+
+In `.vscode/launch.json`:
+```json
+ ...
+ "configurations": [
+ {
+ "name": "Launch Package as root",
+ "type": "go",
+ "request": "launch",
+ "mode": "exec",
+ "asRoot": true,
+ "console": "integratedTerminal",
+ "program": "${fileDirname}/__debug_bin",
+ "preLaunchTask": "go: build (debug)",
+ }
+ ]
+```
+
+Settings (`args`, `cwd`, `env`, ...) configured in the above `launch.json` apply only when *running* the compiled binary, not when building the binary.
+
### Manually installing `dlv`
On rare occasions, you may want to install `dlv` by yourself instead of letting the extension handle its installation.
To view, visit change 406295. To unsubscribe, or for help writing mail filters, visit settings.
Hyang-Ah Hana Kim (Gerrit)
Attention is currently required from: Suzy Mueller.
Patch set 1:Run-TryBot +1
kokoro (Gerrit)
Attention is currently required from: Hyang-Ah Hana Kim, Suzy Mueller.
Kokoro presubmit build finished with status: FAILURE
Logs at: https://source.cloud.google.com/results/invocations/130b8a6e-2899-4cd4-9a0e-469e1546e653
Patch set 1:TryBot-Result -1
Hyang-Ah Hana Kim (Gerrit)
Attention is currently required from: Suzy Mueller.
Patch set 2:Run-TryBot +1
kokoro (Gerrit)
Attention is currently required from: Suzy Mueller.
Kokoro presubmit build finished with status: SUCCESS
Logs at: https://source.cloud.google.com/results/invocations/6afa2490-13c8-4e24-ad5c-ad71c031f952
Patch set 2:TryBot-Result +1
Suzy Mueller (Gerrit)
Attention is currently required from: Hyang-Ah Hana Kim.
9 comments:
Patchset:
Thanks for adding this documentation!!
File docs/debugging.md:
Patch Set #2, Line 348:
the `dlv`remove "the"
Patch Set #2, Line 359:
requires toreplace with "must"
Patch Set #2, Line 361:
needs `"console": "integratedTerminal"` or `"console": "externalTerminal"` configuration.set `"console": "integratedTerminal"` or `"console": "externalTerminal"` in the launch configuration.
remove "the"
Patch Set #2, Line 377:
buildsbuild
Patch Set #2, Line 377:
That means the `go` command to compile the binary will be invoked as root, tooThat means the `go` command will be invoked as root to compile the binary, too.
may
Patch Set #2, Line 431:
apply onlywill only apply
To view, visit change 406295. To unsubscribe, or for help writing mail filters, visit settings.
Hyang-Ah Hana Kim (Gerrit)
Attention is currently required from: Hyang-Ah Hana Kim.
Hyang-Ah Hana Kim uploaded patch set #3 to this change.
The following approvals got outdated and were removed: Run-TryBot+1 by Hyang-Ah Hana Kim, TryBot-Result+1 by kokoro
docs/debugging.md: instruction for `console` and debugging as root
Fixes golang/vscode-go#124
Fixes golang/vscode-go#558
Updates golang/vscode-go#1424
Change-Id: Ic2a32657c30e4a8ca238239c2200f870cf949732
---
M docs/debugging.md
1 file changed, 100 insertions(+), 0 deletions(-)
To view, visit change 406295. To unsubscribe, or for help writing mail filters, visit settings.
Hyang-Ah Hana Kim (Gerrit)
Attention is currently required from: Suzy Mueller.
8 comments:
File docs/debugging.md:
Patch Set #2, Line 348:
the `dlv`remove "the"
Done
Patch Set #2, Line 359:
requires toreplace with "must"
Done
Patch Set #2, Line 361:
needs `"console": "integratedTerminal"` or `"console": "externalTerminal"` configuration.
set `"console": "integratedTerminal"` or `"console": "externalTerminal"` in the launch configuration […]
Done
remove "the"
Done
Patch Set #2, Line 377:
That means the `go` command to compile the binary will be invoked as root, tooThat means the `go` command will be invoked as root to compile the binary, too.
much better!
Patch Set #2, Line 377:
buildsbuild
Done
may
Done
Patch Set #2, Line 431:
apply onlywill only apply
Done
To view, visit change 406295. To unsubscribe, or for help writing mail filters, visit settings.
Suzy Mueller (Gerrit)
Attention is currently required from: Hyang-Ah Hana Kim.
Patch set 3:Code-Review +2
Hyang-Ah Hana Kim (Gerrit)
Hyang-Ah Hana Kim submitted this change.
docs/debugging.md: instruction for `console` and debugging as root
Fixes golang/vscode-go#124
Fixes golang/vscode-go#558
Updates golang/vscode-go#1424
Change-Id: Ic2a32657c30e4a8ca238239c2200f870cf949732
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/406295
Reviewed-by: Suzy Mueller <suz...@golang.org>
---
M docs/debugging.md
1 file changed, 102 insertions(+), 0 deletions(-)
diff --git a/docs/debugging.md b/docs/debugging.md
index 4856e81..86d01fc 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -343,6 +343,93 @@
For information on debugging using the legacy debug adapter, please see the old [Debugging Documentation](https://github.com/golang/vscode-go/blob/master/docs/debugging.md). Note that many new or enhanced features discussed in this document may not be available with the legacy debug adapter.
+### Handling STDIN
+
+The Go extension and `dlv` started as a subprocess of the extension do not have access to `tty`. The Go extension captures and forwards STDOUT/STDERR of the debug program to VS Code, so they can appear in `DEBUG OUTPUT` panel. But this arrangement does not handle STDIN.
+
+When the target program needs to read from STDIN or access terminals (`tty`), use the `"console"` launch option that controls where the `dlv` debugger and the target process run:
+
+* `integratedTerminal` for the terminal inside VS Code
+* `externalTerminal` for the terminal outside VS Code
+
+The Go extension delegates interaction with terminals to VS Code [using Debug Adapter Protocol's `RunInTerminal` functionality](https://github.com/golang/vscode-go/discussions/1626). For configuring VS Code's terminal related behavior, see VS Code's [documentation](https://code.visualstudio.com/docs/editor/integrated-terminal).
+
+### Debugging a program as root
+
+In order to run and debug a program running as root, the debugger (`dlv`) must run with root privilege, too. You can start the debug session with root privilege utilizing the `"asRoot"` AND `"console"` launch options. This is currently supported only on Linux and Mac.
+
+When `asRoot` is true, the Go extension will use the `sudo` command to run `dlv`. Since `sudo` may ask you to enter password, the debug session needs [terminal access](#handling-stdin) so set `"console": "integratedTerminal"` or `"console": "externalTerminal"` in the launch configuration.
+
+For example, the following launch configuration will start `myprogram` and debug it by running `sudo dlv dap` command in the integrated terminal.
+
+```json
+{
+ "name": "Launch as Root",
+ "request": "launch",
+ "mode": "exec",
+ "asRoot": true,
+ "program": "${workspaceRoot}/myprogram",
+ "console": "integratedTerminal",
+ ...
+}
+```
+
+The `asRoot` setting can be used with `auto`/`test`/`debug` launch modes that **build** the target binary to debug. That means the `go` command will be invoked as root to compile the binary, too. This can cause issues:
+
+* by default, `sudo` does not preserve the user's current environment variables (see documentations about sudo's `--preserve-env` option). For example, `PATH` or library paths required for build may be different.
+* Go environment variable settings usually associated in the home directory are different.
+* Module/build caches used during build as root may be different from the caches used in your normal build. If they are the same, you may encounter permission errors due to cache data written to the caches as root.+Settings (`args`, `cwd`, `env`, ...) configured in the above `launch.json` will only apply when *running* the compiled binary, not when building the binary.
+
### Manually installing `dlv`
On rare occasions, you may want to install `dlv` by yourself instead of letting the extension handle its installation.
To view, visit change 406295. To unsubscribe, or for help writing mail filters, visit settings.