Skip to content

DOC: Remove and Update out of date Docker Image issue with #61511 #61550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+25 −25
Open

DOC: Remove and Update out of date Docker Image issue with #61511 #61550

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da63f3e
Replaced stale "Using Docker" subsection with conscie "Using cygdb di…
jacksnnn Jun 4, 2025
1b5013b
Pre-commit
jacksnnn Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 25 additions & 25 deletions doc/source/development/debugging_extensions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,31 +27,31 @@ By default building pandas from source will generate a release build. To generat

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.

Using Docker
------------

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.

You can then mount your pandas repository into this image via:

.. code-block:: sh

docker run --rm -it -w /data -v ${PWD}:/data pandas/pandas-debug

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:

.. code-block:: sh

python -m pip install -ve . --no-build-isolation -Cbuilddir="debug" -Csetup-args="-Dbuildtype=debug"

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.

.. code-block:: sh

cd debug
cygdb

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.
+Using ``cygdb`` directly (recommended)
+--------------------------------------
+
+The previously advertised Docker image (``pandas/pandas-debug``) is **no longer
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove any references to the previously documented approach and just keep this as reflecting the current best practice

+maintained**; outdated versions of *pip* and *meson* inside the container lead
+to build errors. Instead, create a local debug build and run the Cython GDB
+helpers straight from your host environment.
+
+1. Build pandas in *debug* mode (see the command in :ref:`Debugging locally
+ <debugging_c_extensions>`).
+2. Install the helpers::
+
+ pip install cython cython-gdb
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need this? Shouldn't the environment users have already set up for development already provide this?

+
+3. Change to the build directory and start a Cython-aware GDB session::
+
+ cd debug
+ cygdb
+
+Inside ``cygdb`` you can set breakpoints, step through Cython code, and inspect
+variables with the commands documented in the `Cython debugging guide
+<https://docs.cython.org/en/latest/src/userguide/debugging.html#using-the-debugger>`_.
+
+If you need a full system debugger, ensure *gdb* (or *lldb* on macOS) is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aren't these required to use cygdb in the first place?

+installed and on your ``PATH``.

Editor support
--------------
Expand Down
Loading