How do I debug a program written in the Go language?

Question

How do I debug a Go program? I have been using the Gedit Go IDE, but it doesn't have debugging. Is there a way to step though my code and inspect memory? Or am I stuck with print statements? Can I use OutputDebugString?

Answer 1

Update: There is now an official page in the docs on Debugging Go Code with GDB. Much has changed since this answer was written, and several of the limitations listed below have been removed. I'm leaving the rest of this answer for posterity, but if you want to debug Go code, follow the link above.

The Go linkers now emit DWARF debugging symbols that can be interpreted by gdb version 7.x.

Highlight from the blog post linked above:

You can...

• load a Go program in GDB version 7.x
• list all Go, C, and assembly source files by line (parts of the Go runtime are written in C and assembly),
• set breakpoints by line and step through the code,
• print stack traces and inspect stack frames, and
• find the addresses and print the contents of most variables.

There are still some inconveniences:

• The emitted DWARF code is unreadable by the GDB version 6.x that ships with Mac OS X. We would gladly accept patches to make the DWARF output compatible with the standard OS X GDB, but until that’s fixed you’ll need to download, build, and install GDB 7.x to use it under OS X. The source can be found at http://sourceware.org/gdb/download/. Due to the particulars of OS X you’ll need to install the binary on a local file system with chgrp procmod and chmod g+s.
• Names are qualified with a package name and, as GDB doesn't understand Go packages, you must reference each item by its full name. For example, the variable named v in package main must be referred to as 'main.v', in single quotes. A consequence of this is that tab completion of variable and function names does not work.
• Lexical scoping information is somewhat obfuscated. If there are multiple variables of the same name, the nth instance will have a suffix of the form ‘#n’. We plan to fix this, but it will require some changes to the data exchanged between the compiler and linker.
• Slice and string variables are represented as their underlying structure in the runtime library. They will look something like {data = 0x2aaaaab3e320, len = 1, cap = 1}. For slices, you must dereference the data pointer to inspect the elements.

Some things don't work:

• Channel, function, interface, and map variables cannot be inspected.
• Only Go variables are annotated with type information; the runtime's C variables are not.
• Windows and ARM binaries do not contain DWARF debugging information and, as such, cannot be inspected with GDB.

Answer 2

New initiative (started May 2014): derekparker/delve, now (2021): go-delve/delve:

Delve is a Go debugger, written in Go.
(mainly for Linux though, OsX support is coming, Windows support unknown supported in 2016)

Features

• Attach to an already running process

• Launch a process and begin debug session
• Set breakpoints, single step, step over functions, print variable contents

Usage

The debugger can be launched in three ways:

Compile, run, and attach in one step:

$ dlv -run 

Provide the name of the program you want to debug, and the debugger will launch it for you.

$ dlv -proc path/to/program 

Provide the pid of a currently running process, and the debugger will attach and begin the session.

$ sudo dlv -pid 44839 

Breakpoints

Delve can insert breakpoints via the breakpoint command once inside a debug session, however for ease of debugging, you can also call runtime.Breakpoint() and Delve will handle the breakpoint and stop the program at the next source line.