diff --git a/advanced-tools/gdb.rst b/advanced-tools/gdb.rst index df4d71e73..1ce4049f4 100644 --- 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 +`_, +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_``, 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.