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".
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 @@
* ``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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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