diff --git a/doc/developers/debugging.rst b/doc/developers/debugging.rst new file mode 100644 index 0000000000000000000000000000000000000000..832eb3d4b7a5b4bfa0d2c02077a4e3806e578934 --- /dev/null +++ b/doc/developers/debugging.rst @@ -0,0 +1,44 @@ +.. _developers-debugging: + +============================== +Developers' Tips for Debugging +============================== + +Memory errors: debugging Cython with valgrind +============================================= +While python/numpy's built-in memory management is relatively robust, it can +lead to performance penalties for some routines. For this reason, much of +the high-performance code in scikit-learn in written in cython. This +performance gain comes with a tradeoff, however: it is very easy for memory +bugs to crop up in cython code, especially in situations where that code +relies heavily on pointer arithmetic. + +Memory errors can manifest themselves a number of ways. The easiest ones to +debug are often segmentation faults and related glibc errors. Uninitialized +variables can lead to unexpected behavior that is difficult to track down. +A very useful tool when debugging these sorts of errors is +`valgrind <http://valgrind.org>`_. + +Valgrind is a command-line tool that can trace memory errors in a variety of +code. Follow these steps: + + 1. Install valgrind from `valgrind.org <http://valgrind.org>`_. + 2 Download the python valgrind suppression file: `valgrind-python.supp <http://svn.python.org/projects/python/trunk/Misc/valgrind-python.supp>`_. + + 3. Download the valgrind/python readme file: + `README.valgrind <http://svn.python.org/projects/python/trunk/Misc/README.valgrind>`_. + + 4. Follow the directions in the README file to set up your python + suppressions. + 5. Run valgrind as follows:: + + $> valgrind -v --suppressions=valgrind-python.supp python my_test_script.py + +The result will be a list of all the memory-related errors, which reference +lines in the C-code generated by cython from your .pyx file. If you examine +the referenced lines in the .c file, you will see comments which indicate the +corresponding location in your .pyx source file. Hopefully the output will +give you clues as to the source of your memory error. + +For more information on valgrind and the array of options it has, see the +tutorials and documentation on the `valgrind web site <http://valgrind.org>`_. \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 958c46b4a6c240df8d1a71ab0426a8f4fa426f1e..b15f3e5e096659b501f25b52a5e074d55826178f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -187,4 +187,5 @@ Development developers/index developers/performance developers/utilities + developers/debugging about