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".

3 files changed, 24 insertions, 17 deletions

diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 29fbb68..7ececeb 100644
--- a/Doc/c-api/init_config.rst
+++ b/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``.
 
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index bae5ce1..1223059 100644
--- a/Doc/c-api/intro.rst
+++ b/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.
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index d2d212b..b945429 100644
--- a/Doc/c-api/memory.rst
+++ b/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