Debugging Go Code with GDB - The Go Programming Language
Documentation Debugging Go Code with GDB Debugging Go Code with GDB The following instructions apply to the standard toolchain (the gc Go compiler and tools). Gccgo has native gdb support. Note that Delve is a better alternative to GDB when debugging Go programs built with the standard toolchain. It understands the Go runtime, data structures, and expressions better than GDB. Delve currently supports Linux, OSX, and Windows on amd64 .
For the most up-to-date list of supported platforms, please see the Delve documentation . GDB does not understand Go programs well. The stack management, threading, and runtime contain aspects that differ enough from the execution model GDB expects that they can confuse the debugger and cause incorrect results even when the program is compiled with gccgo. As a consequence, although GDB can be useful in some situations (e.g., debugging Cgo code, or debugging the runtime itself), it is not a reliable debugger for Go programs, particularly heavily concurrent ones.
Moreover, it is not a priority for the Go project to address these issues, which are difficult. In short, the instructions below should be taken only as a guide to how to use GDB when it works, not as a guarantee of success. Besides this overview you might want to consult the GDB manual . Introduction When you compile and link your Go programs with the gc toolchain on Linux, macOS, FreeBSD or NetBSD, the resulting binaries contain DWARFv4 debugging information that recent versions (≥7.5) of the GDB debugger can use to inspect a live process or a core dump.
Pass the '-w' flag to the linker to omit the debug information (for example, go build -ldflags=-w prog.go ). The code generated by the gc compiler includes inlining of function invocations and registerization of variables. These optimizations can sometimes make debugging with gdb harder. If you find that you need to disable these optimizations, build your program using go build -gcflags=all="-N -l" . If you want to use gdb to inspect a core dump, you can trigger a dump on a program crash, on systems that permit it, by setting GOTRACEBACK=crash in the environment (see the runtime package documentation for more info).
Common Operations Show file and line number for code, set breakpoints and disassemble: (gdb) list (gdb) list line (gdb) list file.go : line (gdb) break line (gdb) break file.go : line (gdb) disas Show backtraces and unwind stack frames: (gdb) bt (gdb) frame n Show the name, type and location on the stack frame of local variables, arguments and return values: (gdb) info locals (gdb) info args (gdb) p variable (gdb) whatis variable Show the name, type and location of global variables: (gdb) info variables regexp Go Extensions A recent extension mechanism to GDB allows it to load extension scripts for a given binary.
The toolchain uses this to extend GDB with a handful of commands to inspect internals of the runtime code (such as goroutines) and to pretty print the built-in map, slice and channel types. Pretty printing a string, slice, map, channel or interface: (gdb) p var A $len() and $cap() function for strings, slices and maps: (gdb) p $len( var ) A function to cast interfaces to their dynamic types: (gdb) p $dtype( var ) (gdb) iface var Known issue: GDB can’t automatically find the dynamic type of an interface value if its long name differs from its short name (annoying when printing stacktraces, the pretty printer falls back to printing the short type name and a pointer).
Inspecting goroutines: (gdb) info goroutines (gdb) goroutine n cmd (gdb) help goroutine For example: (gdb) goroutine 12 bt You can inspect all goroutines by passing all instead of a specific goroutine's ID. For example: (gdb) goroutine all bt If you'd like to see how this works, or want to extend it, take a look at src/runtime/runtime-gdb.py in the Go source distribution. It depends on some special magic types ( hash<T,U> ) and variables ( runtime.m and runtime.g ) that the linker ( src/cmd/link/internal/ld/dwarf.go ) ensures are described in the DWARF code.
If you're interested in what the debugging information looks like, run objdump -W a.out and browse through the .debug_* sections. Known Issues String pretty printing only triggers for type string, not for types derived from it. Type information is missing for the C parts of the runtime library. GDB does not understand Go’s name qualifications and treats "fmt.Print" as an unstructured literal with a "." that needs to be quoted.
It objects even more strongly to method names of the form pkg.(*MyType).Meth . As of Go 1.11, debug information is compressed by default. Older versions of gdb, such as the one available by default on MacOS, do not understand the compression. You can generate uncompressed debug information by using go build -ldflags=-compressdwarf=false . (For convenience you can put the -ldflags option in the GOFLAGS environment variable so that you don't have to specify it each time.) Tutorial In this tutorial we will inspect the binary of the regexp package's unit tests.
To build the binary, change to $GOROOT/src/regexp and run go test -c . This should produce an executable file named regexp.test . Getting Started Launch GDB, debugging regexp.test : $ gdb regexp.test GNU gdb (GDB) 7.2-gg8 Copyright (C) 2010 Free Software Foundation, Inc. License GPLv 3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> Type "show copying" and "show warranty" for licensing/warranty details.
This GDB was configured as "x86_64-linux". Reading symbols from /home/user/go/src/regexp/regexp.test... done. Loading Go Runtime support. (gdb) The message "Loading Go Runtime support" means that GDB loaded the extension from $GOROOT/src/runtime/runtime-gdb.py . To help GDB find the Go runtime sources and the accompanying support script, pass your $GOROOT with the '-d' flag: $ gdb regexp.test -d $GOROOT If for some reason GDB still can't find that directory or that script, you can load it by hand by telling gdb (assuming you have the go sources in ~/go/ ): (gdb) source ~/go/src/runtime/runtime-gdb.py Loading Go Runtime support.
Inspecting the source Use the "l" or "list" command to inspect source code. (gdb) l List a specific part of the source parameterizing "list" with a function name (it must be qualified with its package name). (gdb) l main.main List a specific file and line number: (gdb) l regexp.go:1 (gdb) # Hit enter to repeat last command. Here, this lists next 10 lines. Naming Variable and function names must be qualified with the name of the packages they belong to.
The Compile function from the regexp package is known to GDB as 'regexp.Compile' . Methods must be qualified with the name of their receiver types. For example, the *Regexp type’s String method is known as 'regexp.(*Regexp).String' . Variables that shadow other variables are magically suffixed with a number in the debug info. Variables referenced by closures will appear as pointers magically prefixed with '&'. Setting breakpoints Set a breakpoint at the TestFind function: (gdb) b 'regexp.TestFind' Breakpoint 1 at 0x424908: file /home/user/go/src/regexp/find_test.go, line 148.
Run the program: (gdb) run Starting program: /home/user/go/src/regexp/regexp.test Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148 148 func TestFind(t *testing.T) { Execution has paused at the breakpoint. See which goroutines are running, and what they're doing: (gdb) info goroutines 1 waiting runtime.gosched * 13 running runtime.goexit the one marked with the * is the current goroutine.
Inspecting the stack Look at the stack trace for where we’ve paused the program: (gdb) bt # backtrace #0 regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148 #1 0x000000000042f60b in testing.tRunner (t=0xf8404a89c0, test=0x573720) at /home/user/go/src/testing/testing.go:156 #2 0x000000000040df64 in runtime.initdone () at /home/user/go/src/runtime/proc.c:242 #3 0x000000f8404a89c0
The rest of this page is on the live site.