Index: api.tex =================================================================== --- api.tex (revision 46040) +++ api.tex (working copy) @@ -46,13 +46,8 @@ \input{init} \input{memory} \input{newtypes} +\input{debugging} - -% \chapter{Debugging \label{debugging}} -% -% XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. - - \appendix \chapter{Reporting Bugs} \input{reportingbugs} Index: debugging.tex =================================================================== --- debugging.tex (revision 0) +++ debugging.tex (revision 0) @@ -0,0 +1,50 @@ +% -*- latex -*- +\chapter{Debugging \label{debugging}} + +Python can be built with several macros to enable extra checks of the +interpreter and extension modules. They tend to add a large amount of +overhead to the runtime so they are not enabled by default. + +\begin{description} + \item[\code{Py_DEBUG}] + Enable a number of debugging operations. In addition to the + reference count debugging described below, the following extra + checks are performed: + \begin{itemize} + \item Extra checks are added to the object allocator. + \item Extra checks are added to the parser and compiler. + \item Downcasts from wide types to narrow types are checked for + loss if information. + \item A number of assertions are added to the dictionary and set + implementations. In addition, the set object acquires a + test_c_api method. + \item Sanity checks of the input arguments are added to frame + creation. + \item The storage for long ints is initialized with a known + invalid pattern to catch reference to uninitialized + digits. + \item Low-level tracing and extra exception checking are added + to the runtime virtual machine. + \item Extra checks are added to the memory arena implementation. + \item Extra debugging is added to the thread module. + \end{itemize} + + \code{Py_DEBUG} is enabled in the Unix build by adding + \code{--with-pydebug} to the configure command. It is also + implied by the presence of the not-Python-specific \code{_DEBUG} macro. + When \code{Py_DEBUG} is enabled in the Unix build, compiler + optimization is disabled. + + \item[\code{Py_TRACE_REFS}] + Enable reference tracing. When defined, a circular doubly linked + list of active objects is maintained by the addition of two extra + fields to every \var{PyObject}. Total allocations are tracked as + well. Upon exit, all existing references are printed. (In + interactive mode this happens after every statement run by the + interpreter.) Implied by \code{Py_DEBUG}. + + \item[\code{Py_REF_DEBUG}] + Enable various reference debugging checks. Implied by + \code{Py_TRACE_REFS}. + +\end{description}