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.

Doc/c-api/intro.rst

@@ -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
+In addition to the reference count debugging described below, extra checks are
-extra checks are performed:
+performed, see :ref:`Python Debug Build <debug-build>`.
 
-* Extra checks are added to the object allocator.
+Defining :c:macro:`Py_TRACE_REFS` enables reference tracing
-
+(see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
-* Extra checks are added to the parser and compiler.
+When defined, a circular doubly linked list of active objects is maintained by adding two extra
-
-* 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
 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.)

Doc/c-api/typeobj.rst

@@ -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
 -----------------
 

Doc/using/configure.rst

@@ -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 :ref:`debug hooks on memory allocators <default-memory-allocators>`
-* Install debug hooks on memory allocators to detect buffer overflow and other
+  to detect buffer overflow and other memory errors.
-  memory errors: see :c:func:`PyMem_SetupDebugHooks`.
+* Define ``Py_DEBUG`` and ``Py_REF_DEBUG`` macros.
-* Build Python with assertions (don't set ``NDEBUG`` macro):
+* Add runtime checks: code surroundeded by ``#ifdef Py_DEBUG`` and ``#endif``.
-  ``assert(...);`` and ``_PyObject_ASSERT(...);``.
+  Enable ``assert(...)`` and ``_PyObject_ASSERT(...)`` assertions: don't set
-  See also the :option:`--with-assertions` configure option.
+  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 help detecting uninitialized bytes.
+    to detect usage of uninitialized objects.
-* Many functions ensure that are not called with an exception raised, since
+  * Ensure that functions which can clear or replace the current exception are
-  they can clear or replace the current exception.
+    not called with an exception raised.
-* The garbage collector (:func:`gc.collect` function) runs some basic checks on
+  * The garbage collector (:func:`gc.collect` function) runs some basic checks
-  objects consistency.
+    on objects consistency.
-* More generally, add runtime checks, code surroundeded by ``#ifdef Py_DEBUG``
+  * The :c:macro:`Py_SAFE_DOWNCAST()` macro checks for integer underflow and
-  and ``#endif``.
+    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
+   ``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro (see the
-   introduces the only ABI incompatibility.
+   :option:`--with-trace-refs` option), which introduces the only ABI
+   incompatibility.
 
 
 Debug options

Doc/whatsnew/3.8.rst

@@ -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``
+environment variable, can be set using the new :option:`./configure
-build option.
+--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