Delve (dlv) Debugger Cheatsheet

Bugs are known since the 1870s; at least, the term “bug” was coined at that time, referring to mechanical defects in machinery. Today, we have to fight bugs in software or else our users would lose trust in our apps. Software can become quite complicated, and hence, the art of debugging relies on (1) experience as well as (2) choosing the right debugging tools.

For the latter, I wrote a blog article about debugging techniques. (And if you just came here from the article, don't click the link, or you might enter an infinite loop.)

While the article focuses on techniques besides using a debugger, I decided to do the opposite in this Spotlight and entirely focus on using a debugger—Delve in particular.

Keep a link to this Spotlight for later, or why not just grab a repo and try out all the commands as they come!

Installation

Refer to your OS's package manager to install an auto-upgradeable dlv command. Mac users, for example, could run brew install delve. The following command installs the latest version of Delve in an OS-independent way (albeit without automatic upgrades):

go install github.com/go-delve/delve/cmd/dlv@latest

If you use Delve on macOS, ensure to check out the macOS considerations from the Delve documentation.

Getting Started

Delve can start an app from source for debugging, debug unit tests, attach to a running process, or debug an already compiled binary:

dlv debug                    # Debug current package
dlv debug ./path/to/package  # Debug specific package
dlv test                     # Debug tests in current package
dlv attach <pid>             # Attach to running process
dlv exec ./binary            # Debug compiled binary

Basic Commands

Once Delve has started, or attached to, a process, it presents a run-eval-print loop (REPL). A lot of useful commands are available at Delve's internal prompt; here are the basic ones to get started:

help (h)                     # List available commands
break (b) main.go:15         # Set breakpoint at line 15
breakpoints (bp)             # List breakpoints
clear 1                      # Remove breakpoint #1
clearall                     # Remove all breakpoints
continue (c)                 # Run until next breakpoint
next (n)                     # Step over to next line
step (s)                     # Step into function
stepout (so)                 # Step out of current function
restart (r)                  # Restart debugging session
exit (q)                     # Quit debugger

Inspecting Variables

When Delve stops at a breakpoint, you can inspect variables and process arguments, to see how data is processed:

print (p) variableName       # Print variable value
locals                       # Show local variables
args                         # Show function arguments
vars                         # Show package variables
whatis variableName          # Show variable type
set variableName = value     # Change variable value

Call Stack & Goroutines

Examine the context of the current code line: its call stack as well as the current goroutine and other goroutines:

stack (bt)                   # Show call stack trace
frame 2                      # Select stack frame #2
goroutine (gr)               # Show current goroutine
goroutines (grs)             # List all goroutines
goroutine n                  # Switch to goroutine n
up                           # Move up the stack
down                         # Move down the stack

Function Navigation

You can also put your focus on functions rather than code lines:

funcs regexp                 # List functions matching regexp
list (l)                     # Show source code at current position
list main.main               # Show source for specific function

Building for Debug

To optimally prepare a program for debugging, disable optimizations (-N) and inlining of functions (-l) for all packages:

go build -gcflags="all=-N -l" 

Have fun with debugging, but don't blame me if you spend the next hour playing with Delve!