debugging.rst 9.28 KB
Newer Older
1 2 3 4 5 6 7 8
.. highlight:: cython

.. _debugging:

**********************************
Debugging your Cython program
**********************************

9
Cython comes with an extension for the GNU Debugger that helps users debug
10
Cython code. To use this functionality, you will need to install gdb 7.2 or
11
higher, built with Python support (linked to Python 2.6 or higher).
12 13
The debugger supports debuggees with versions 2.6 and higher. For Python 3,
code should be built with Python 3 and the debugger should be run with
14
Python 2 (or at least it should be able to find the Python 2 Cython
15 16 17 18 19 20 21 22
installation). Note that in recent versions of Ubuntu, for instance, ``gdb``
installed with ``apt-get`` is configured with Python 3. On such systems, the
proper configuration of ``gdb`` can be obtained by downloading the ``gdb``
source, and then running::

    ./configure --with-python=python2
    make
    sudo make install
23 24

The debugger will need debug information that the Cython compiler can export.
25 26
This can be achieved from within the setup script by passing ``gdb_debug=True``
to ``cythonize()``::
27

Aditya Bhosale's avatar
Aditya Bhosale committed
28
    from distutils.core import setup
29
    from distutils.extension import Extension
30

31
    extensions = [Extension('source', ['source.pyx'])]
32

33
    setup(..., ext_modules=cythonize(extensions, gdb_debug=True))
34

35 36 37
For development it's often helpful to pass the ``--inplace`` flag to
the ``setup.py`` script, which makes distutils build your project
"in place", i.e., not in a separate `build` directory.
38 39

When invoking Cython from the command line directly you can have it write
40
debug information using the ``--gdb`` flag::
41

42
    cython --gdb myfile.pyx
43 44 45 46 47

Running the Debugger
=====================
.. highlight:: bash

48
To run the Cython debugger and have it import the debug information exported
49 50
by Cython, run ``cygdb`` in the build directory::

51
    $ python setup.py build_ext --inplace
52 53 54 55 56 57 58
    $ cygdb
    GNU gdb (GDB) 7.2
    ...
    (gdb)

When using the Cython debugger, it's preferable that you build and run your code
with an interpreter that is compiled with debugging symbols (i.e. configured
59
with ``--with-pydebug`` or compiled with the ``-g`` CFLAG). If your Python is
60
installed and managed by your package manager you probably need to install debug
61
support separately. If using NumPy then you also need to install numpy debugging, or you'll
62
see an `import error for multiarray <https://bugzilla.redhat.com/show_bug.cgi?id=1030830>`_.
63
E.G. for ubuntu::
64

65
    $ sudo apt-get install python-dbg python-numpy-dbg
66
    $ python-dbg setup.py build_ext --inplace
67

68 69 70 71
Then you need to run your script with ``python-dbg`` also. Ensure that when
building your package with debug symbols that cython extensions are re-compiled
if they had been previously compiled. If your package is version controlled, you
might want to perform ``git clean -fxd`` or ``hg purge --all`` before building.
72 73 74 75 76 77

You can also pass additional arguments to gdb::

    $ cygdb /path/to/build/directory/ GDBARGS

i.e.::
78

79
    $ cygdb . -- --args python-dbg mainscript.py
80 81 82 83 84 85

To tell cygdb not to import any debug information, supply ``--`` as the first
argument::

    $ cygdb --

86

87 88 89 90 91 92 93
Using the Debugger
===================
The Cython debugger comes with a set of commands that support breakpoints,
stack inspection, source code listing, stepping, stepping over, etc. Most
of these commands are analogous to their respective gdb command.

.. function:: cy break breakpoints...
94

95 96 97 98 99 100 101 102 103 104
    Break in a Python, Cython or C function. First it will look for a Cython
    function with that name, if cygdb doesn't know about a function (or method)
    with that name, it will set a (pending) C breakpoint. The ``-p`` option can
    be used to specify a Python breakpoint.

    Breakpoints can be set for either the function or method name, or they can
    be fully "qualified", which means that the entire "path" to a function is
    given::

        (gdb) cy break cython_function_or_method
Joon Ro's avatar
Joon Ro committed
105 106
        (gdb) cy break packagename.cython_module.cython_function
        (gdb) cy break packagename.cython_module.ClassName.cython_method
107 108 109 110 111
        (gdb) cy break c_function

    You can also break on Cython line numbers::

        (gdb) cy break :14
Joon Ro's avatar
Joon Ro committed
112 113
        (gdb) cy break cython_module:14
        (gdb) cy break packagename.cython_module:14
114 115 116 117

    Python breakpoints currently support names of the module (not the entire
    package path) and the function or method::

Joon Ro's avatar
Joon Ro committed
118
        (gdb) cy break -p python_module.python_function_or_method
119 120
        (gdb) cy break -p python_function_or_method

121 122
.. note:: Python breakpoints only work in Python builds where the Python frame
          information can be read from the debugger. To ensure this, use a
123
          Python debug build or a non-stripped build compiled with debug
124 125
          support.

126 127 128 129 130 131 132 133 134 135 136
.. function:: cy step

    Step through Python, Cython or C code. Python, Cython and C functions
    called directly from Cython code are considered relevant and will be
    stepped into.

.. function:: cy next

    Step over Python, Cython or C code.

.. function:: cy run
137

138 139
    Run the program. The default interpreter is the interpreter that was used
    to build your extensions with, or the interpreter ``cygdb`` is run with
140
    in case the "don't import debug information" option was in effect.
141
    The interpreter can be overridden using gdb's ``file`` command.
142 143 144 145 146 147 148 149 150 151

.. function:: cy cont

    Continue the program.

.. function:: cy up
              cy down

    Go up and down the stack to what is considered a relevant frame.

152 153
.. function:: cy finish

154
    Execute until an upward relevant frame is met or something halts
155 156
    execution.

157 158 159 160 161 162
.. function:: cy bt
              cy backtrace

    Print a traceback of all frames considered relevant. The ``-a`` option
    makes it print the full traceback (all C frames).

163 164 165 166 167 168
.. function:: cy select

    Select a stack frame by number as listed by ``cy backtrace``. This
    command is introduced because ``cy backtrace`` prints a reversed stack
    trace, so frame numbers differ from gdb's ``bt``.

169 170
.. function:: cy print varname

171
    Print a local or global Cython, Python or C variable (depending on the
172 173 174 175 176 177
    context). Variables may also be dereferenced::

        (gdb) cy print x
        x = 1
        (gdb) cy print *x
        *x = (PyObject) {
178 179 180
            _ob_next = 0x93efd8,
            _ob_prev = 0x93ef88,
            ob_refcnt = 65,
181 182
            ob_type = 0x83a3e0
        }
183 184 185 186 187

.. function:: cy set cython_variable = value

    Set a Cython variable on the Cython stack to value.

188 189 190 191 192 193 194 195 196 197 198 199 200 201
.. function:: cy list

    List the source code surrounding the current line.

.. function:: cy locals
              cy globals

    Print all the local and global variables and their values.

.. function:: cy import FILE...

    Import debug information from files given as arguments. The easiest way to
    import debug information is to use the cygdb command line tool.

Mark Florisson's avatar
Mark Florisson committed
202 203 204
.. function:: cy exec code

    Execute code in the current Python or Cython frame. This works like
205
    Python's interactive interpreter.
Mark Florisson's avatar
Mark Florisson committed
206 207 208 209 210 211

    For Python frames it uses the globals and locals from the Python frame,
    for Cython frames it uses the dict of globals used on the Cython module
    and a new dict filled with the local Cython variables.

.. note:: ``cy exec`` modifies state and executes code in the debuggee and is
212
          therefore potentially dangerous.
Mark Florisson's avatar
Mark Florisson committed
213 214 215 216 217 218 219 220 221 222 223 224 225

Example::

    (gdb) cy exec x + 1
    2
    (gdb) cy exec import sys; print sys.version_info
    (2, 6, 5, 'final', 0)
    (gdb) cy exec
    >global foo
    >
    >foo = 'something'
    >end

226 227 228 229 230 231 232 233 234 235 236 237 238 239
Convenience functions
=====================
The following functions are gdb functions, which means they can be used in a
gdb expression.

.. function:: cy_cname(varname)

    Returns the C variable name of a Cython variable. For global
    variables this may not be actually valid.

.. function:: cy_cvalue(varname)

    Returns the value of a Cython variable.

240 241 242 243 244 245
.. function:: cy_eval(expression)

    Evaluates Python code in the nearest Python or Cython frame and returns
    the result of the expression as a gdb value. This gives a new reference
    if successful, NULL on error.

246 247 248 249 250 251 252 253 254 255
.. function:: cy_lineno()

    Returns the current line number in the selected Cython frame.

Example::

    (gdb) print $cy_cname("x")
    $1 = "__pyx_v_x"
    (gdb) watch $cy_cvalue("x")
    Hardware watchpoint 13: $cy_cvalue("x")
256
    (gdb) cy set my_cython_variable = $cy_eval("{'spam': 'ham'}")
257 258 259
    (gdb) print $cy_lineno()
    $2 = 12

260

261 262
Configuring the Debugger
========================
263 264
A few aspects of the debugger are configurable with gdb parameters. For
instance, colors can be disabled, the terminal background color
265 266 267
and breakpoint autocompletion can be configured.

.. c:macro:: cy_complete_unqualified
268

269 270 271 272 273 274 275 276 277 278 279 280 281 282 283
    Tells the Cython debugger whether ``cy break`` should also complete
    plain function names, i.e. not prefixed by their module name.
    E.g. if you have a function named ``spam``,
    in module ``M``, it tells whether to only complete ``M.spam`` or also just
    ``spam``.

    The default is true.

.. c:macro:: cy_colorize_code

    Tells the debugger whether to colorize source code. The default is true.

.. c:macro:: cy_terminal_background_color

    Tells the debugger about the terminal background color, which affects
284
    source code coloring. The default is "dark", another valid option is
285 286 287 288 289 290 291
    "light".

This is how these parameters can be used::

    (gdb) set cy_complete_unqualified off
    (gdb) set cy_terminal_background_color light
    (gdb) show cy_colorize_code