github.com/cnboonhan/delve@v0.0.0-20230908061759-363f2388c2fb/Documentation/faq.md (about)

     1  ## Frequently Asked Questions
     2  
     3  <!-- BEGIN TOC -->
     4  * [I'm getting an error while compiling Delve / unsupported architectures and OSs](#unsupportedplatforms)
     5  * [How do I use Delve with Docker?](#docker)
     6  * [How can I use Delve to debug a CLI application?](#ttydebug)
     7  * [How can I use Delve for remote debugging?](#remote)
     8  * [Can not set breakpoints or see source listing in a complicated debugging environment](#substpath)
     9  * [Using Delve to debug the Go runtime](#runtime)
    10  <!-- END TOC -->
    11  
    12  ### <a name="unsupportedplatforms"></a> I'm getting an error while compiling Delve / unsupported architectures and OSs
    13  
    14  The most likely cause of this is that you are running an unsupported Operating System or architecture.
    15  Currently Delve supports (GOOS / GOARCH):
    16  * linux / amd64 (86x64)
    17  * linux / arm64 (AARCH64)
    18  * linux / 386
    19  * windows / amd64
    20  * darwin (macOS) / amd64
    21  
    22  There is no planned ETA for support of other architectures or operating systems. Bugs tracking requested support are:
    23  
    24  - [32bit ARM support](https://github.com/go-delve/delve/issues/328)
    25  - [PowerPC support](https://github.com/go-delve/delve/issues/1564)
    26  - [OpenBSD](https://github.com/go-delve/delve/issues/1477)
    27  
    28  See also: [backend test health](backend_test_health.md).
    29  
    30  ### <a name="docker"></a> How do I use Delve with Docker?
    31  
    32  When running the container you should pass the `--security-opt=seccomp:unconfined` option to Docker. You can start a headless instance of Delve inside the container like this:
    33  
    34  ```
    35  dlv exec --headless --listen :4040 /path/to/executable
    36  ```
    37  
    38  And then connect to it from outside the container:
    39  
    40  ```
    41  dlv connect :4040
    42  ```
    43  
    44  The program will not start executing until you connect to Delve and send the `continue` command.  If you want the program to start immediately you can do that by passing the `--continue` and `--accept-multiclient` options to Delve:
    45  
    46  ```
    47  dlv exec --headless --continue --listen :4040 --accept-multiclient /path/to/executable
    48  ```
    49  
    50  Note that the connection to Delve is unauthenticated and will allow arbitrary remote code execution: *do not do this in production*.
    51  
    52  ### <a name="ttydebug"></a> How can I use Delve to debug a CLI application?
    53  
    54  There are three good ways to go about this
    55  
    56  1. Run your CLI application in a separate terminal and then attach to it via `dlv attach`. 
    57  
    58  1. Run Delve in headless mode via `dlv debug --headless` and then connect to it from
    59  another terminal. This will place the process in the foreground and allow it to access
    60  the terminal TTY.
    61  
    62  1. Assign the process its own TTY. This can be done on UNIX systems via the `--tty` flag for the 
    63  `dlv debug` and `dlv exec` commands. For the best experience, you should create your own PTY and 
    64  assign it as the TTY. This can be done via [ptyme](https://github.com/derekparker/ptyme).
    65  
    66  ### <a name="remote"></a> How can I use Delve for remote debugging?
    67  
    68  It is best not to use remote debugging on a public network. If you have to do this, we recommend using ssh tunnels or a vpn connection.  
    69  
    70  ##### ```Example ``` 
    71  
    72  Remote server:
    73  ```
    74  dlv exec --headless --listen localhost:4040 /path/to/executable
    75  ```
    76  
    77  Local client:
    78  1. connect to the server and start a local port forward
    79  
    80  ```
    81  ssh -NL 4040:localhost:4040 user@remote.ip
    82  ```
    83  
    84  2. connect local port
    85  ```
    86  dlv connect :4040
    87  ```
    88  
    89  ### <a name="substpath"></a> Can not set breakpoints or see source listing in a complicated debugging environment
    90  
    91  This problem manifests when one or more of these things happen:
    92  
    93  * Can not see source code when the program stops at a breakpoint
    94  * Setting a breakpoint using full path, or through an IDE, does not work
    95  
    96  While doing one of the following things:
    97  
    98  * **The program is built and run inside a container** and Delve (or an IDE) is remotely connecting to it
    99  * Generally, every time the build environment (VM, container, computer...) differs from the environment where Delve's front-end (dlv or a IDE) runs 
   100  * Using `-trimpath` or `-gcflags=-trimpath`
   101  * Using a build system other than `go build` (eg. bazel)
   102  * Using symlinks in your source tree
   103  
   104  If you are affected by this problem then the `list main.main` command (in the command line interface) will have this result:
   105  
   106  ```
   107  (dlv) list main.main
   108  Showing /path/to/the/mainfile.go:42 (PC: 0x47dfca)
   109  Command failed: open /path/to/the/mainfile.go: no such file or directory
   110  (dlv)
   111  ```
   112  
   113  This is not a bug. The Go compiler embeds the paths of source files into the executable so that debuggers, including Delve, can use them. Doing any of the things listed above will prevent this feature from working seamlessly.
   114  
   115  The substitute-path feature can be used to solve this problem, see `help config` or the `substitutePath` option in launch.json.
   116  
   117  The `sources` command could also be useful in troubleshooting this problem, it shows the list of file paths that has been embedded by the compiler into the executable.
   118  
   119  For more informations on path substitution see [path substitution](cli/substitutepath.md).
   120  
   121  If you still think this is a bug in Delve and not a configuration problem, open an [issue](https://github.com/go-delve/delve/issues), filling the issue template and including the logs produced by delve with the options `--log --log-output=rpc,dap`.
   122  
   123  ### <a name="runtime"></a> Using Delve to debug the Go runtime
   124  
   125  It's possible to use Delve to debug the Go runtime, however there are some caveats to keep in mind
   126  
   127  * The `runtime` package is always compiled with optimizations and inlining, all of the caveats that apply to debugging optimized binaries apply to the runtime package. In particular some variables could be unavailable or have stale values and it could expose some bugs with the compiler assigning line numbers to instructions.
   128  
   129  * Next, step and stepout try to follow the current goroutine, if you debug one of the functions in the runtime that modify the curg pointer they will get confused. The 'step-instruction' command should be used instead.
   130   
   131  * When executing a stacktrace from g0 Delve will return the top frame and then immediately switch to the goroutine stack. If you want to see the g0 stacktrace use `stack -mode simple`.
   132  
   133  * The step command only steps into private runtime functions if it is already inside a runtime function. To step inside a private runtime function inserted into user code by the compiler set a breakpoint and then use `runtime.curg.goid == <current goroutine id>` as condition.