mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-01 15:43:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[Patch #1490989 from Skip Montanaro] Mention debugging builds in the API documentation. I've changed Skip's patch to point to Misc/SpecialBuilds and fiddled with the markup a bit.

Browse source
This commit is contained in:
Andrew M. Kuchling 2006-07-29 19:24:04 +00:00
parent 897afc43ad
commit a40191c305
2 changed files with 56 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

5
Doc/api/api.tex
View file

@ -48,11 +48,6 @@ code releases.}
\input{newtypes}
% \chapter{Debugging \label{debugging}}
%
% XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
\appendix
\chapter{Reporting Bugs}
\input{reportingbugs}

56
Doc/api/intro.tex
View file

@ -580,3 +580,59 @@ information about these functions is given in a later chapter.
Notice that \cfunction{Py_Finalize} does \emph{not} free all memory
allocated by the Python interpreter, e.g. memory allocated by extension
modules currently cannot be released.
\section{Debugging Builds \label{debugging}}
Python can be built with several macros to enable extra checks of the
interpreter and extension modules. These checks tend to add a large
amount of overhead to the runtime so they are not enabled by default.
A full list of the various types of debugging builds is in the file
\file{Misc/SpecialBuilds.txt} in the Python source distribution.
Builds are available that support tracing of reference counts,
debugging the memory allocator, or low-level profiling of the main
interpreter loop. Only the most frequently-used builds will be
described in the remainder of this section.
Compiling the interpreter with the \csimplemacro{Py_DEBUG} macro
defined produces what is generally meant by "a debug build" of Python.
\csimplemacro{Py_DEBUG} is enabled in the Unix build by adding
\longprogramopt{with-pydebug} to the \file{configure} command. It is also
implied by the presence of the not-Python-specific
\csimplemacro{_DEBUG} macro. When \csimplemacro{Py_DEBUG} is enabled
in the Unix build, compiler optimization is disabled.
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 of information.
\item A number of assertions are added to the dictionary and set
implementations. In addition, the set object acquires a
\method{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}
There may be additional checks not mentioned here.
Defining \csimplemacro{Py_TRACE_REFS} enables reference tracing. When
defined, a circular doubly linked list of active objects is maintained
by adding two extra fields to every \ctype{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 \csimplemacro{Py_DEBUG}.
Please refer to \file{Misc/SpecialBuilds.txt} in the Python source
distribution for more detailed information.