Delve Debugger for Go

Delve provides several different modes of operation depending on whether you are starting a new process, attaching to an existing one, or examining a crash dump. Key modes include:

• dlv debug: Compiles and begins debugging the main package in the current directory (or a specified package).
• dlv exec: Executes a precompiled binary and begins a debug session.
• dlv attach: Attaches to a currently running process.
• dlv test: Compiles a test binary and begins debugging the program.
• dlv core: Examines a core dump file.
• dlv connect: Connects to a headless debug server using a terminal client.
• dlv dap: Starts a headless TCP server communicating via the Debug Adaptor Protocol (DAP).
• dlv replay: Replays an rr trace.
• dlv trace: Compiles and begins tracing a program.

Delve supports a subset of the Go expression language for evaluation during debugging. Supported features include:

• Arithmetic/Logic: All binary and unary operators on basic types (except <-, ++, and --).
• Comparison: Comparison operators on any type.
• Type Casting:
  • Between numeric types.
  • Integer constants to/from any pointer type.
  • Between string, []byte, and []rune.
• Accessors: Struct member access (somevar.memberfield), slicing/indexing for arrays, slices, and strings, and map access.
• Pointers: Pointer dereferencing.
• Built-in Functions: cap, len, complex, imag, and real.
• Interfaces: Type assertion on interface variables (e.g., somevar.(concretetype)).

Delve's API is implemented using the JSON-RPC 1.0 specification. The methods of the service/rpc2.RPCServer are exposed through this connection.

Every request follows a pattern where you provide args (the input) and receive out (the result). For example, to create a breakpoint, you wrap a CreateBreakpointIn object into a JSON-RPC envelope and send it to the RPCServer.CreateBreakpoint method.

{
  "method": "RPCServer.CreateBreakpoint",
  "params": [
    {
      "Breakpoint": {
        "file": "/User/you/some/file.go",
        "line": 16
      }
    }
  ],
  "id": 27
}

Delve supports cross-platform core file reading (e.g., reading a Linux/arm64 core file on Windows/amd64). Because of this, using runtime.GOOS, runtime.GOARCH, or standard build tags is generally forbidden outside of pkg/proc/native and test files.

When writing code for other packages, use these abstractions instead:

• OS: Use proc.BinaryInfo.GOOS instead of runtime.GOOS.
• Architecture: Use proc.BinaryInfo.Arch.Name instead of runtime.GOARCH.
• Pointer Size: Use proc.BinaryInfo.Arch.PtrSize() instead of unsafe.Sizeof.
• Addresses: Use uint64 for address-sized integers instead of uintptr.
• File Naming: Use amd64_filename.go instead of the build tag version filename_amd64.go.

Debugging the Go runtime is possible but has specific limitations:

• Optimizations: The runtime package is compiled with optimizations and inlining. Variables may be unavailable or stale, and line numbers may occasionally be inaccurate.
• Stepping through runtime functions: Standard next, step, and stepout commands may fail if the runtime function modifies the curg pointer. Use the step-instruction command instead.
• Viewing g0 stacktraces: When executing a stacktrace from g0, Delve may automatically switch to the goroutine stack. To see the g0 stacktrace specifically, use stack -mode simple.
• Stepping into private runtime functions: To step into a private runtime function inserted by the compiler into user code, set a breakpoint and use the condition: runtime.curg.goid == <current goroutine id>.

You can define custom commands in Starlark by defining functions with the prefix command_.

Argument Handling:

• Single Argument: If your function takes one argument (e.g., def command_echo(args):), args is received as a single Starlark string containing all arguments passed from the CLI.
• Expression Arguments: If your function defines multiple parameters (e.g., def command_echo_expr(a, b, c):), Delve will parse the CLI arguments as Starlark expressions, allowing you to pass math or logic (like 2+2) directly.

To use your commands, load your script using the source command.

# Single string argument
def command_echo(args):
	print(args)

# Multiple expression arguments
def command_echo_expr(a, b, c):
	print("a", a, "b", b, "c", c)

Because of Go's concurrency, multiple goroutines may hit breakpoints at the same time.

Best Practices for Clients:

• Signal all hits: Do not just signal the first breakpoint. Iterate through the Threads array in the DebuggerState and identify all threads where the Breakpoint member is non-nil.
• Identify the Selected Goroutine: When multiple breakpoints are hit, Delve chooses a SelectedGoroutine randomly among those stopped.
• Prefer SelectedGoroutine: Always use the SelectedGoroutine field from DebuggerState to identify the active goroutine. Ignore CurrentThread unless SelectedGoroutine is nil.

When resuming execution in a Starlark script, you have two options:

1. dlv_command("command"): Equivalent to typing the command directly into the (dlv) prompt. This is generally preferred as it behaves as expected for standard Delve commands like continue.
2. raw_command("command"): Maps directly to the underlying RPC Command API. Use this only if you need behavior that diverges from the standard command-line interface.

# Preferred way to continue execution
dlv_command("continue")

# Alternative (direct API call)
raw_command("continue", ...)

Delve provides two primary API interfaces to allow external frontends (such as IDEs and editors) to interact with the debugger programmatically. The core debugging logic is abstracted from these transport implementations.

Supported interfaces:

• JSON-RPC: Used by the built-in terminal client. This interface is updated in lockstep with new Delve features.
• DAP (Debug Adapter Protocol): A generic, industry-standard protocol used by many modern development tools.