Home » Support » Index of All Documentation » Wing IDE Reference Manual » Advanced Debugging Topics »

11.5. Debugging Extension Modules on Linux/Unix

Gdb can be used as a tool to aid in debugging C/C++ extension modules written for Python, although doing so can be a bit tricky and prone to problems. The following text contains hints to make this easier.

Note that this section assumes you are already familiar with gdb; for more information on gdb commands, please refer to the gdb documentation.

The first step in debugging C/C++ modules with gdb is to make sure that you are using a version of Python that was compiled with debug symbols. To do this, you need a source distribution of Python and you need to configure the distribution as described in the accompanying README file.

In most cases, this can be done as follows: (1) Type ./configure, (2) type make OPT=-g or edit the Makefile to add OPT=-g, (3) type make, and (4) once the build is complete, install it with make install (but see the README first if you don't want to install into /usr/local/lib/python).

If you are building an extension module that you are compiling into the Python interpreter, you can now just run Python within gdb, set a breakpoint at the desired location in your extension module, and execute your Python test program.

In most cases, however, the extension module is not compiled into Python but is instead loaded dynamically at runtime. In order to get your extension module to load, it must be on the PYTHONPATH or within the same directory where the module is import-ed into Python source.

Gdb additionally requires setting LD_LIBRARY_PATH to include the directory where the dynamically loaded module is located. A common problem in doing this is that gdb will reread .cshrc each time that it runs, so setting LD_LIBRARY_PATH before invoking gdb has no effect if you also set LD_LIBRARY_PATH in .cshrc. To work around this, set LD_LIBRARY_PATH in .profile instead. This file is read only once at login time.

Next you may want to set up your ~/.gdbinit file by copying the contents of the file Misc/gdbinit from the Python source distribution. This contains some useful macros for inspecting Python code from gdb (for example pystack will print the Python stack)

Then start Python as follows:

myhost> gdb
(gdb) file python
(gdb) run yourprogram.py yourargs

Note that breakpoints in a shared library cannot be set until after the shared library is loaded. If running your program triggers loading of your extension module library, you can use ^C^C to interrupt the debug program, set breakpoints, and then continue.

Otherwise, you must continue running your program until the extension module is loaded. When in doubt, add a print statement at point of import, or you can set a breakpoint at PyImport_AddModule (this can be set after file python and before running since this call is not in a shared library).

Unfortunately, even if you take all of the above steps, some older versions of gdb will often get confused if you load and unload shared libraries repeatedly during a single debug session. You can usually re-run Python 5-10 times but subsequently may see crashing, failure to stop at breakpoints, or other odd behaviors. When this occurs, there is no alternative but to exit and restart gdb. This appears to be fixed in more recent versions of gdb, at least on some architectures.

Finally a hint for viewing Python data from the C/C++ side when using gdb. The following gdb command will print out the contents of a PyObject * called obj as if you had issued the command print obj from within the Python language:

(gdb) p PyObject_Print (obj, stderr, 0)

For more information see Debugging with Gdb in the Python wiki.