DOC: expand docs on debugging with gdb

2 files changed, 50 insertions, 9 deletions

diff --git a/doc/source/dev/development_advanced_debugging.rst b/doc/source/dev/development_advanced_debugging.rst
index efd78cfad..735ff7328 100644
--- a/doc/source/dev/development_advanced_debugging.rst
+++ b/doc/source/dev/development_advanced_debugging.rst
@@ -1,3 +1,5 @@
+.. _advanced_debugging:
+
 ========================
 Advanced debugging tools
 ========================
@@ -39,12 +41,33 @@ and means you do not have to worry about making reference counting errors,
 which can be intimidating.
 
 
-Python debug build for finding memory leaks
-===========================================
+Python debug build
+==================
+
+Debug builds of Python are easily available for example via the system package
+manager on Linux systems, but are also available on other platforms, possibly in
+a less convenient format. If you cannot easily install a debug build of Python
+from a system package manager, you can build one yourself using `pyenv
+<https://github.com/pyenv/pyenv>`_. For example, to install and globally
+activate a debug build of Python 3.10.8, one would do::
+
+    pyenv install -g 3.10.8
+    pyenv global 3.10.8
 
-Debug builds of Python are easily available for example on ``debian`` systems,
-and can be used on all platforms.
-Running a test or terminal is usually as easy as::
+Note that ``pyenv install`` builds Python from source, so you must ensure that
+Python's dependencies are installed before building, see the pyenv documentation
+for platform-specific installation instructions. You can use ``pip`` to install
+Python dependencies you may need for your debugging session. If there is no
+debug wheel available on `pypi,` you will need to build the dependencies from
+source and ensure that your dependencies are also compiled as debug builds.
+
+Often debug builds of Python name the Python executable ``pythond`` instead of
+``python``. To check if you have a debug build of Python installed, you can run
+e.g. ``pythond -m sysconfig`` to get the build configuration for the Python
+executable. A debug build will be built with debug compiler options in
+``CFLAGS`` (e.g. ``-g -Og``).
+
+Running the Numpy tests or an interactive terminal is usually as easy as::
 
     python3.8d runtests.py
     # or
@@ -63,6 +86,8 @@ A Python debug build will help:
     sys.gettotalrefcount()
     sys.getallocatedblocks()
 
+- Python debug builds allow easier debugging with gdb and other C debuggers.
+
 
 Use together with ``pytest``
 ----------------------------
diff --git a/doc/source/dev/development_environment.rst b/doc/source/dev/development_environment.rst
index 4772366d2..0ac02271d 100644
--- a/doc/source/dev/development_environment.rst
+++ b/doc/source/dev/development_environment.rst
@@ -267,6 +267,10 @@ Python is running inside gdb to verify your setup::
     >end
     sys.version_info(major=3, minor=7, micro=0, releaselevel='final', serial=0)
 
+Most python builds do not include debug symbols and are built with compiler
+optimizations enabled. To get the best debugging experience using a debug build
+of Python is encouraged, see :ref:`advanced_debugging`.
+
 Next you need to write a Python script that invokes the C code whose execution
 you want to debug. For instance ``mytest.py``::
 
@@ -285,14 +289,28 @@ And then in the debugger::
 
 The execution will now stop at the corresponding C function and you can step
 through it as usual. A number of useful Python-specific commands are available.
-For example to see where in the Python code you are, use ``py-list``.  For more
-details, see `DebuggingWithGdb`_. Here are some commonly used commands:
+For example to see where in the Python code you are, use ``py-list``, to see the
+python traceback, use ``py-bt``.  For more details, see
+`DebuggingWithGdb`_. Here are some commonly used commands:
 
    - ``list``: List specified function or line.
    - ``next``: Step program, proceeding through subroutine calls.
    - ``step``: Continue program being debugged, after signal or breakpoint.
    - ``print``: Print value of expression EXP.
 
+Rich support for Python debugging requires that the ``python-gdb.py`` script
+distributed with Python is installed in a path where gdb can find it. If you
+installed your Python build from your system package manager, you likely do
+not need to manually do anything. However, if you built Python from source,
+you will likely need to create a ``.gdbinit`` file in your home directory
+pointing gdb at the location of your Python installation. For example, a
+version of python installed via `pyenv <https://github.com/pyenv/pyenv>`_
+needs a ``.gdbinit`` file with the following contents:
+
+.. code-block:: text
+
+    add-auto-load-safe-path ~/.pyenv
+
 Instead of plain ``gdb`` you can of course use your favourite
 alternative debugger; run it on the python binary with arguments
 ``runtests.py -g --python mytest.py``.
@@ -300,8 +318,6 @@ alternative debugger; run it on the python binary with arguments
 Building NumPy with a Python built with debug support (on Linux distributions
 typically packaged as ``python-dbg``) is highly recommended.
 
-
-
 .. _DebuggingWithGdb: https://wiki.python.org/moin/DebuggingWithGdb
 .. _tox: https://tox.readthedocs.io/
 .. _virtualenv: http://www.virtualenv.org/