From: Rob Pike <r@golang.org>
Date: Sat, 26 Apr 2014 16:18:17 +0000 (-0600)
Subject: doc/debugging_with_gdb.html: add introductory disclaimer
X-Git-Tag: go1.3beta2~189
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=2674efbdf414ce97a542e557224fca0b978a7fa5;p=gostls13.git

doc/debugging_with_gdb.html: add introductory disclaimer
The instructions in this document are useful but not reliable.
Explain the situation up top.

Fixes #7471.

LGTM=josharian, iant
R=golang-codereviews, josharian, iant
CC=golang-codereviews
https://golang.org/cl/96830045
---

diff --git a/doc/debugging_with_gdb.html b/doc/debugging_with_gdb.html
index 3d2e4af07c..afaedf74ca 100644
--- a/doc/debugging_with_gdb.html
+++ b/doc/debugging_with_gdb.html
@@ -9,6 +9,23 @@ Besides this overview you might want to consult the
 <a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
 </i></p>
 
+<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.
+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.
+</p>
+
+<p>
+In time, a more Go-centric debugging architecture may be required.
+</p>
+
 <h2 id="Introduction">Introduction</h2>
 
 <p>