doc/debugging_with_gdb: mention delve as an alternative.

Fixes #23108

Change-Id: I9b3d0f0c399c0b4cb488adaf3c002bc55d5d21d9
Reviewed-on: https://go-review.googlesource.com/84795
Reviewed-by: Heschi Kreinick <heschi@google.com>

1 files changed, 31 insertions, 12 deletions

diff --git a/doc/debugging_with_gdb.html b/doc/debugging_with_gdb.html
index dc8147806b..f3333fe894 100644
--- a/doc/debugging_with_gdb.html
+++ b/doc/debugging_with_gdb.html
@@ -3,28 +3,47 @@
 	"Path": "/doc/gdb"
 }-->
 
-<p><i>
-This applies to the standard toolchain (the <code>gc</code> Go
-compiler and tools). Gccgo has native gdb support.
-Besides this overview you might want to consult the
-<a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
-</i></p>
+<i>
+<p>
+The following instructions apply to the standard toolchain
+(the <code>gc</code> Go compiler and tools).
+Gccgo has native gdb support.
+</p>
+<p>
+Note that 
+<a href="https://github.com/derekparker/delve">Delve</a> is a better 
+alternative to GDB when debugging Go programs built with the standard
+tool chain. It understands the Go runtime, data structures, and
+expressions better than GDB. Delve currently supports Linux, OSX,
+and Windows on <code>amd64</code>.
+For the most up-to-date list of supported platforms, please see
+<a href="https://github.com/derekparker/delve/tree/master/Documentation/installation">
+ the Delve documentation</a>.
+</p>
+</i>
 
 <p>
 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, even when the program is compiled with gccgo.
-As a consequence, although GDB can be useful in some situations, 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.
+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.
+</p>
+
+<p>
 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
+<a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
 </p>
 
 <p>
-In time, a more Go-centric debugging architecture may be required.
 </p>
 
 <h2 id="Introduction">Introduction</h2>