bpo-43774: Document configure options (GH-25283)

Add Doc/using/configure.rst documentation to document configure,
preprocessor, compiler and linker options.

Add a new section about the "Python debug build".

Author: vstinner

Doc/c-api/init_config.rst

@@ -241,8 +241,9 @@ PyPreConfig
       * ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc
         memory allocator <pymalloc>` with debug hooks
 
-      ``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG``
-      are not supported if Python is configured using ``--without-pymalloc``
+      ``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are
+      not supported if Python is :option:`configured using --without-pymalloc
+      <--without-pymalloc>`.
 
       See :ref:`Memory Management <memory>`.
 
@@ -636,7 +637,8 @@ PyConfig
 
       Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable.
 
-      Need a special build of Python with the ``Py_TRACE_REFS`` macro defined.
+      Need a special build of Python with the ``Py_TRACE_REFS`` macro defined:
+      see :option:`configure --with-trace-refs <--with-trace-refs>`.
 
       Default: ``0``.
 
@@ -817,7 +819,8 @@ PyConfig
 
       Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable.
 
-      The option is ignored if Python is built using ``--without-pymalloc``.
+      The option is ignored if Python is :option:`configured using
+      --without-pymalloc <--without-pymalloc>`.
 
       Default: ``0``.
 
@@ -827,8 +830,9 @@ PyConfig
 
       Set by the :envvar:`PYTHONPLATLIBDIR` environment variable.
 
-      Default: value of the ``PLATLIBDIR`` macro which is set at configure time
-      by ``--with-platlibdir`` (default: ``"lib"``).
+      Default: value of the ``PLATLIBDIR`` macro which is set by the
+      :option`configure --with-platlibdir option <--with-platlibdir>` (default:
+      ``"lib"``).
 
       Part of the :ref:`Python Path Configuration <init-path-config>` input.
 
@@ -1016,7 +1020,8 @@ PyConfig
 
       Set to 1 by :option:`-X showrefcount <-X>` command line option.
 
-      Need a debug build of Python (``Py_REF_DEBUG`` macro must be defined).
+      Need a :ref:`debug build of Python <debug-build>` (the ``Py_REF_DEBUG``
+      macro must be defined).
 
       Default: ``0``.
 

Doc/c-api/intro.rst

@@ -742,9 +742,10 @@ 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 :c:macro:`Py_DEBUG` macro defined produces
-what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
-enabled in the Unix build by adding ``--with-pydebug`` to the
-:file:`./configure` command.  It is also implied by the presence of the
+what is generally meant by :ref:`a debug build of Python <debug-build>`.
+:c:macro:`Py_DEBUG` is enabled in the Unix build by adding
+:option:`--with-pydebug` to the :file:`./configure` command.
+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.
 
@@ -778,7 +779,7 @@ 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.)  Implied by :c:macro:`Py_DEBUG`.
+after every statement run by the interpreter.)
 
 Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
 for more detailed information.

Doc/c-api/memory.rst

@@ -385,11 +385,12 @@ Debug build, without pymalloc    ``"malloc_debug"``    ``malloc`` + debug  ``mal
 
 Legend:
 
-* Name: value for :envvar:`PYTHONMALLOC` environment variable
+* Name: value for :envvar:`PYTHONMALLOC` environment variable.
 * ``malloc``: system allocators from the standard C library, C functions:
-  :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`
-* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`
-* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`
+  :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.
+* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`.
+* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`.
+* "Debug build": :ref:`Python build in debug mode <debug-build>`.
 
 .. _customize-memory-allocators:
 
@@ -500,8 +501,8 @@ Customize Memory Allocators
    memory block was traced.
 
    These hooks are :ref:`installed by default <default-memory-allocators>` if
-   Python is compiled in debug
-   mode. The :envvar:`PYTHONMALLOC` environment variable can be used to install
+   :ref:`Python is built in debug mode <debug-build>`.
+   The :envvar:`PYTHONMALLOC` environment variable can be used to install
    debug hooks on a Python compiled in release mode.
 
    .. versionchanged:: 3.6

Doc/extending/newtypes.rst

@@ -12,7 +12,7 @@ This section aims to give a quick fly-by on the various type methods you can
 implement and what they do.
 
 Here is the definition of :c:type:`PyTypeObject`, with some fields only used in
-debug builds omitted:
+:ref:`debug builds <debug-build>` omitted:
 
 .. literalinclude:: ../includes/typestruct.h
 

Doc/extending/newtypes_tutorial.rst

@@ -69,7 +69,8 @@ at the start of each object struct and defines a field called ``ob_base``
 of type :c:type:`PyObject`, containing a pointer to a type object and a
 reference count (these can be accessed using the macros :c:macro:`Py_REFCNT`
 and :c:macro:`Py_TYPE` respectively).  The reason for the macro is to
-abstract away the layout and to enable additional fields in debug builds.
+abstract away the layout and to enable additional fields in :ref:`debug builds
+<debug-build>`.
 
 .. note::
    There is no semicolon above after the :c:macro:`PyObject_HEAD` macro.

Doc/howto/instrumentation.rst

@@ -266,7 +266,7 @@ should instead read:
 
    probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") {
 
-(assuming a debug build of CPython 3.6)
+(assuming a :ref:`debug build <debug-build>` of CPython 3.6)
 
 
 Available static markers

Doc/library/decimal.rst

@@ -1484,7 +1484,8 @@ are also included in the pure Python version for compatibility.
 
 .. data:: HAVE_CONTEXTVAR
 
-   The default value is ``True``. If Python is compiled ``--without-decimal-contextvar``,
+   The default value is ``True``. If Python is :option:`configured with
+   --without-decimal-contextvar <--without-decimal-contextvar>`,
    the C version uses a thread-local rather than a coroutine-local context and the value
    is ``False``.  This is slightly faster in some nested context scenarios.
 

Doc/library/devmode.rst

@@ -13,6 +13,8 @@ detected.
 It can be enabled using the :option:`-X dev <-X>` command line option or by
 setting the :envvar:`PYTHONDEVMODE` environment variable to ``1``.
 
+See also :ref:`Python debug build <debug-build>`.
+
 Effects of the Python Development Mode
 ======================================
 

Doc/library/stdtypes.rst

@@ -1581,13 +1581,15 @@ expression support in the :mod:`re` module).
 
    By default, the *errors* argument is not checked for best performances, but
    only used at the first encoding error. Enable the :ref:`Python Development
-   Mode <devmode>`, or use a debug build to check *errors*.
+   Mode <devmode>`, or use a :ref:`debug build <debug-build>` to check
+   *errors*.
 
    .. versionchanged:: 3.1
       Support for keyword arguments added.
 
    .. versionchanged:: 3.9
-      The *errors* is now checked in development mode and in debug mode.
+      The *errors* is now checked in development mode and
+      in :ref:`debug mode <debug-build>`.
 
 
 .. method:: str.endswith(suffix[, start[, end]])
@@ -2710,7 +2712,7 @@ arbitrary binary data.
 
    By default, the *errors* argument is not checked for best performances, but
    only used at the first decoding error. Enable the :ref:`Python Development
-   Mode <devmode>`, or use a debug build to check *errors*.
+   Mode <devmode>`, or use a :ref:`debug build <debug-build>` to check *errors*.
 
    .. note::
 
@@ -2722,7 +2724,8 @@ arbitrary binary data.
       Added support for keyword arguments.
 
    .. versionchanged:: 3.9
-      The *errors* is now checked in development mode and in debug mode.
+      The *errors* is now checked in development mode and
+      in :ref:`debug mode <debug-build>`.
 
 
 .. method:: bytes.endswith(suffix[, start[, end]])

Doc/library/sys.rst

@@ -250,8 +250,8 @@ always available.
    Print low-level information to stderr about the state of CPython's memory
    allocator.
 
-   If Python is configured --with-pydebug, it also performs some expensive
-   internal consistency checks.
+   If Python is :option:`configured --with-pydebug <--with-pydebug>`, it also
+   performs some expensive internal consistency checks.
 
    .. versionadded:: 3.3
 

Doc/library/warnings.rst

@@ -229,7 +229,7 @@ In regular release builds, the default warning filter has the following entries
     ignore::ImportWarning
     ignore::ResourceWarning
 
-In debug builds, the list of default warning filters is empty.
+In a :ref:`debug build <debug-build>`, the list of default warning filters is empty.
 
 .. versionchanged:: 3.2
    :exc:`DeprecationWarning` is now ignored by default in addition to

Doc/using/cmdline.rst

@@ -433,7 +433,8 @@ Miscellaneous options
    * ``-X faulthandler`` to enable :mod:`faulthandler`;
    * ``-X showrefcount`` to output the total reference count and number of used
      memory blocks when the program finishes or after each statement in the
-     interactive interpreter. This only works on debug builds.
+     interactive interpreter. This only works on :ref:`debug builds
+     <debug-build>`.
    * ``-X tracemalloc`` to start tracing Python memory allocations using the
      :mod:`tracemalloc` module. By default, only the most recent frame is
      stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start
@@ -926,18 +927,16 @@ conflict.
 Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~
 
-Setting these variables only has an effect in a debug build of Python.
-
 .. envvar:: PYTHONTHREADDEBUG
 
    If set, Python will print threading debug info.
 
-   Need Python configured with the ``--with-pydebug`` build option.
+   Need a :ref:`debug build of Python <debug-build>`.
 
 
 .. envvar:: PYTHONDUMPREFS
 
    If set, Python will dump objects and reference counts still alive after
    shutting down the interpreter.
 
-   Need Python configured with the ``--with-trace-refs`` build option.
+   Need Python configured with the :option:`--with-trace-refs` build option.