Add a GDB tips section to Advanced Tools (#977)

smontanaro · hugovk · erlend-aasland · web-flow · commit 61218b4c7cd1 · 2022-11-04T11:04:23.000+01:00
Co-authored-by: Hugo van Kemenade &lt;hugovk@users.noreply.github.com&gt;
Co-authored-by: Erlend E. Aasland &lt;erlend.aasland@protonmail.com&gt;
Co-authored-by: Ezio Melotti &lt;ezio.melotti@gmail.com&gt;
diff --git a/advanced-tools/gdb.rst b/advanced-tools/gdb.rst
@@ -1,7 +1,7 @@
 .. _gdb:
 
 ===========
-GDB Support
+GDB support
 ===========
 
 .. highlight:: none
@@ -17,7 +17,7 @@ or what type or value has a given Python object represented by a standard
 limitation.
 
 
-gdb 7 and later
+GDB 7 and later
 ===============
 
 In gdb 7, support for `extending gdb with Python
@@ -300,7 +300,7 @@ thread is doing at the Python level::
 .. note:: This is only available for Python 2.7, 3.2 and higher.
 
 
-gdb 6 and earlier
+GDB 6 and earlier
 =================
 
 The file at ``Misc/gdbinit`` contains a gdb configuration file which provides
@@ -324,3 +324,49 @@ auto-load safe. One way to achieve this is to add a line like the following
 to ``~/.gdbinit`` (edit the specific list of paths as appropriate)::
 
     add-auto-load-safe-path ~/devel/py3k:~/devel/py32:~/devel/py27
+
+
+GDB tips
+========
+
+Learning to use GDB effectively improves your chances of successfully
+debugging problems with Python's internals.
+
+Saving and loading breakpoints
+------------------------------
+
+With extended exposure to particular parts of the Python runtime, you
+might find it helpful to define a routine set of breakpoints and
+commands to execute when they are hit.
+For convenience, save your breakpoints to a file and load them in future
+sessions using the ``save breakpoints`` command::
+
+   (gdb) save breakpoints python.brk
+
+You can edit the file to your heart's content, then load it in a later
+session::
+
+   (gdb) source python.brk
+
+
+Breaking at labels
+------------------
+
+You will most often set breakpoints at the start of functions, but
+this approach is less helpful when debugging the runtime virtual
+machine, since the main interpreter loop function,
+``_PyEval_EvalFrameDefault``, is well over 4,000 lines long as of Python 3.12.
+Fortunately, among the `many ways to set breakpoints
+<https://sourceware.org/gdb/onlinedocs/gdb/Specify-Location.html>`_,
+you can break at C labels, such as those generated for computed gotos.
+If you are debugging an interpreter compiled with computed goto support
+(generally true, certainly when using GCC), each instruction will be
+prefaced with a label named ``TARGET_<instruction>``, e.g.,
+``TARGET_LOAD_CONST``.  You can then set a breakpoint with a command
+like::
+
+   (gdb) break ceval.c:_PyEval_EvalFrameDefault:TARGET_LOAD_CONST
+
+Add commands, save to a file, then reload in future sessions without
+worrying that the starting line number of individual instructions
+change over time.
