From 62f8e03db2e4be7a97b4c23c02b6c489372a7987 Mon Sep 17 00:00:00 2001
From: Jake Vanderplas <jakevdp@yahoo.com>
Date: Thu, 26 Jan 2012 10:02:54 -0800
Subject: [PATCH] add info about valgrind to dev documents
---
doc/developers/debugging.rst | 44 ++++++++++++++++++++++++++++++++++++
doc/index.rst | 1 +
2 files changed, 45 insertions(+)
create mode 100644 doc/developers/debugging.rst
diff --git a/doc/developers/debugging.rst b/doc/developers/debugging.rst
new file mode 100644
index 0000000000..832eb3d4b7
--- /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 958c46b4a6..b15f3e5e09 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -187,4 +187,5 @@ Development
developers/index
developers/performance
developers/utilities
+ developers/debugging
about
--
GitLab