mirror of https://github.com/python/cpython
bpo-43774: Enhance debug build documentation (GH-25712)
* Add also references to --with-trace-refs option. * Move _ob_next and _ob_prev at the end, since they don't exist by default and are related to debug.
This commit is contained in:
Victor Stinner
GitHub
parent
8ec2f0dc0c
commit
abfd6388cd
|
|
@ -749,34 +749,12 @@ It is also implied by the presence of the
|
|||
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`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:
|
||||
In addition to the reference count debugging described below, extra checks are
|
||||
performed, see :ref:`Python Debug Build <debug-build>`.
|
||||
|
||||
* Extra checks are added to the object allocator.
|
||||
|
||||
* Extra checks are added to the parser and compiler.
|
||||
|
||||
* Downcasts from wide types to narrow types are checked for loss of information.
|
||||
|
||||
* A number of assertions are added to the dictionary and set implementations.
|
||||
In addition, the set object acquires a :meth:`test_c_api` method.
|
||||
|
||||
* Sanity checks of the input arguments are added to frame creation.
|
||||
|
||||
* The storage for ints is initialized with a known invalid pattern to catch
|
||||
reference to uninitialized digits.
|
||||
|
||||
* Low-level tracing and extra exception checking are added to the runtime
|
||||
virtual machine.
|
||||
|
||||
* Extra checks are added to the memory arena implementation.
|
||||
|
||||
* Extra debugging is added to the thread module.
|
||||
|
||||
There may be additional checks not mentioned here.
|
||||
|
||||
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
|
||||
circular doubly linked list of active objects is maintained by adding two extra
|
||||
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing
|
||||
(see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
|
||||
When defined, a circular doubly linked list of active objects is maintained by adding two extra
|
||||
fields to every :c:type:`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.)
|
||||
|
|
|
|||
|
|
@ -482,27 +482,6 @@ metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that it
|
|||
type objects) *must* have the :attr:`ob_size` field.
|
||||
|
||||
|
||||
.. c:member:: PyObject* PyObject._ob_next
|
||||
PyObject* PyObject._ob_prev
|
||||
|
||||
These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
|
||||
|
||||
Their initialization to ``NULL`` is taken care of by the
|
||||
``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
|
||||
<static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
|
||||
allocated objects <heap-types>`, these two fields are used to link the
|
||||
object into a doubly-linked list of *all* live objects on the heap.
|
||||
|
||||
This could be used for various debugging purposes; currently the only uses
|
||||
are the :func:`sys.getobjects` function and to print the objects that are
|
||||
still alive at the end of a run when the environment variable
|
||||
:envvar:`PYTHONDUMPREFS` is set.
|
||||
|
||||
**Inheritance:**
|
||||
|
||||
These fields are not inherited by subtypes.
|
||||
|
||||
|
||||
.. c:member:: Py_ssize_t PyObject.ob_refcnt
|
||||
|
||||
This is the type object's reference count, initialized to ``1`` by the
|
||||
|
|
@ -540,6 +519,28 @@ type objects) *must* have the :attr:`ob_size` field.
|
|||
This field is inherited by subtypes.
|
||||
|
||||
|
||||
.. c:member:: PyObject* PyObject._ob_next
|
||||
PyObject* PyObject._ob_prev
|
||||
|
||||
These fields are only present when the macro ``Py_TRACE_REFS`` is defined
|
||||
(see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
|
||||
|
||||
Their initialization to ``NULL`` is taken care of by the
|
||||
``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
|
||||
<static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
|
||||
allocated objects <heap-types>`, these two fields are used to link the
|
||||
object into a doubly-linked list of *all* live objects on the heap.
|
||||
|
||||
This could be used for various debugging purposes; currently the only uses
|
||||
are the :func:`sys.getobjects` function and to print the objects that are
|
||||
still alive at the end of a run when the environment variable
|
||||
:envvar:`PYTHONDUMPREFS` is set.
|
||||
|
||||
**Inheritance:**
|
||||
|
||||
These fields are not inherited by subtypes.
|
||||
|
||||
|
||||
PyVarObject Slots
|
||||
-----------------
|
||||
|
||||
|
|
|
|||
|
|
@ -208,43 +208,48 @@ recommended for best performance.
|
|||
|
||||
.. _debug-build:
|
||||
|
||||
Debug build
|
||||
-----------
|
||||
Python Debug Build
|
||||
------------------
|
||||
|
||||
A debug build is Python built with the :option:`--with-pydebug` configure
|
||||
option.
|
||||
|
||||
Effects of a debug build:
|
||||
|
||||
* Define ``Py_DEBUG`` and ``Py_REF_DEBUG`` macros.
|
||||
* Display all warnings by default: the list of default warning filters is empty
|
||||
in the :mod:`warnings` module.
|
||||
* Add ``d`` to :data:`sys.abiflags`.
|
||||
* Add :func:`sys.gettotalrefcount` function.
|
||||
* Add :option:`-X showrefcount <-X>` command line option.
|
||||
* Add :envvar:`PYTHONTHREADDEBUG` environment variable.
|
||||
* Add support for the ``__ltrace__`` variable: enable low-level tracing in the
|
||||
bytecode evaluation loop if the variable is defined.
|
||||
* The list of default warning filters is empty in the :mod:`warnings` module.
|
||||
* Install debug hooks on memory allocators to detect buffer overflow and other
|
||||
memory errors: see :c:func:`PyMem_SetupDebugHooks`.
|
||||
* Build Python with assertions (don't set ``NDEBUG`` macro):
|
||||
``assert(...);`` and ``_PyObject_ASSERT(...);``.
|
||||
See also the :option:`--with-assertions` configure option.
|
||||
* Unicode and int objects are created with their memory filled with a pattern
|
||||
to help detecting uninitialized bytes.
|
||||
* Many functions ensure that are not called with an exception raised, since
|
||||
they can clear or replace the current exception.
|
||||
* The garbage collector (:func:`gc.collect` function) runs some basic checks on
|
||||
objects consistency.
|
||||
* More generally, add runtime checks, code surroundeded by ``#ifdef Py_DEBUG``
|
||||
and ``#endif``.
|
||||
* Install :ref:`debug hooks on memory allocators <default-memory-allocators>`
|
||||
to detect buffer overflow and other memory errors.
|
||||
* Define ``Py_DEBUG`` and ``Py_REF_DEBUG`` macros.
|
||||
* Add runtime checks: code surroundeded by ``#ifdef Py_DEBUG`` and ``#endif``.
|
||||
Enable ``assert(...)`` and ``_PyObject_ASSERT(...)`` assertions: don't set
|
||||
the ``NDEBUG`` macro (see also the :option:`--with-assertions` configure
|
||||
option). Main runtime checks:
|
||||
|
||||
* Add sanity checks on the function arguments.
|
||||
* Unicode and int objects are created with their memory filled with a pattern
|
||||
to detect usage of uninitialized objects.
|
||||
* Ensure that functions which can clear or replace the current exception are
|
||||
not called with an exception raised.
|
||||
* The garbage collector (:func:`gc.collect` function) runs some basic checks
|
||||
on objects consistency.
|
||||
* The :c:macro:`Py_SAFE_DOWNCAST()` macro checks for integer underflow and
|
||||
overflow when downcasting from wide types to narrow types.
|
||||
|
||||
See also the :ref:`Python Development Mode <devmode>` and the
|
||||
:option:`--with-trace-refs` configure option.
|
||||
|
||||
.. versionchanged:: 3.8
|
||||
Release builds and debug builds are now ABI compatible: defining the
|
||||
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which
|
||||
introduces the only ABI incompatibility.
|
||||
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro (see the
|
||||
:option:`--with-trace-refs` option), which introduces the only ABI
|
||||
incompatibility.
|
||||
|
||||
|
||||
Debug options
|
||||
|
|
|
|||
|
|
@ -215,8 +215,8 @@ Release builds and :ref:`debug builds <debug-build>` are now ABI compatible: def
|
|||
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which
|
||||
introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro, which
|
||||
adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS`
|
||||
environment variable, can be set using the new ``./configure --with-trace-refs``
|
||||
build option.
|
||||
environment variable, can be set using the new :option:`./configure
|
||||
--with-trace-refs <--with-trace-refs>` build option.
|
||||
(Contributed by Victor Stinner in :issue:`36465`.)
|
||||
|
||||
On Unix, C extensions are no longer linked to libpython except on Android
|
||||
|
|
|
|||
Loading…
Reference in New Issue