diff --git a/doc/source/development/debugging_extensions.rst b/doc/source/development/debugging_extensions.rst index c8127e0cc2996..74dd4df8b8ab8 100644 --- a/doc/source/development/debugging_extensions.rst +++ b/doc/source/development/debugging_extensions.rst @@ -10,9 +10,9 @@ pandas uses Cython and C/C++ `extension modules `_ -2. `Fundamental Python Debugging Part 2 - Python Extensions `_ -3. `Fundamental Python Debugging Part 3 - Cython Extensions `_ +1. `Fundamental Python Debugging Part 1 - Python `_ +2. `Fundamental Python Debugging Part 2 - Python Extensions `_ +3. `Fundamental Python Debugging Part 3 - Cython Extensions `_ Debugging locally ----------------- @@ -22,29 +22,16 @@ By default building pandas from source will generate a release build. To generat pip install -ve . --no-build-isolation -Cbuilddir="debug" -Csetup-args="-Dbuildtype=debug" .. note:: - conda environments update CFLAGS/CPPFLAGS with flags that are geared towards generating releases, and may work counter towards usage in a development environment. If using conda, you should unset these environment variables via ``export CFLAGS=`` and ``export CPPFLAGS=`` 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 +Using cygdb for Cython debugging +--------------------------------- - python -m pip install -ve . --no-build-isolation -Cbuilddir="debug" -Csetup-args="-Dbuildtype=debug" +For debugging Cython extensions, ``cygdb`` is the recommended approach. The ``cygdb`` debugger comes pre-installed with Cython, so if you have Cython installed in your development environment, you should already have access to it. -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. +After building pandas with debug symbols (as shown above), you can use cygdb by navigating to the build folder and starting the debugger: .. code-block:: sh