Skip to content

Commit da63f3e

Browse files
committed
Replaced stale "Using Docker" subsection with conscie "Using cygdb directly" subsection
1 parent 25e6462 commit da63f3e

File tree

1 file changed

+25
-25
lines changed

1 file changed

+25
-25
lines changed

doc/source/development/debugging_extensions.rst

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -27,31 +27,31 @@ By default building pandas from source will generate a release build. To generat
2727

2828
By specifying ``builddir="debug"`` all of the targets will be built and placed in the debug directory relative to the project root. This helps to keep your debug and release artifacts separate; you are of course able to choose a different directory name or omit altogether if you do not care to separate build types.
2929

30-
Using Docker
31-
------------
32-
33-
To simplify the debugging process, pandas has created a Docker image with a debug build of Python and the gdb/Cython debuggers pre-installed. You may either ``docker pull pandas/pandas-debug`` to get access to this image or build it from the ``tooling/debug`` folder locally.
34-
35-
You can then mount your pandas repository into this image via:
36-
37-
.. code-block:: sh
38-
39-
docker run --rm -it -w /data -v ${PWD}:/data pandas/pandas-debug
40-
41-
Inside the image, you can use meson to build/install pandas and place the build artifacts into a ``debug`` folder using a command as follows:
42-
43-
.. code-block:: sh
44-
45-
python -m pip install -ve . --no-build-isolation -Cbuilddir="debug" -Csetup-args="-Dbuildtype=debug"
46-
47-
If planning to use cygdb, the files required by that application are placed within the build folder. So you have to first ``cd`` to the build folder, then start that application.
48-
49-
.. code-block:: sh
50-
51-
cd debug
52-
cygdb
53-
54-
Within the debugger you can use `cygdb commands <https://docs.cython.org/en/latest/src/userguide/debugging.html#using-the-debugger>`_ to navigate cython extensions.
30+
+Using ``cygdb`` directly (recommended)
31+
+--------------------------------------
32+
+
33+
+The previously advertised Docker image (``pandas/pandas-debug``) is **no longer
34+
+maintained**; outdated versions of *pip* and *meson* inside the container lead
35+
+to build errors. Instead, create a local debug build and run the Cython GDB
36+
+helpers straight from your host environment.
37+
+
38+
+1. Build pandas in *debug* mode (see the command in :ref:`Debugging locally
39+
+ <debugging_c_extensions>`).
40+
+2. Install the helpers::
41+
+
42+
+ pip install cython cython-gdb
43+
+
44+
+3. Change to the build directory and start a Cython-aware GDB session::
45+
+
46+
+ cd debug
47+
+ cygdb
48+
+
49+
+Inside ``cygdb`` you can set breakpoints, step through Cython code, and inspect
50+
+variables with the commands documented in the `Cython debugging guide
51+
+<https://docs.cython.org/en/latest/src/userguide/debugging.html#using-the-debugger>`_.
52+
+
53+
+If you need a full system debugger, ensure *gdb* (or *lldb* on macOS) is
54+
+installed and on your ``PATH``.
5555

5656
Editor support
5757
--------------

0 commit comments

Comments
 (0)