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

5 files changed, 12 insertions, 11 deletions

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 453a1b4..d690463 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -1365,9 +1365,10 @@ New Features
   to simulate.
   (Contributed by Antoine Pitrou in :issue:`43356`.)
 
-* The limited C API is now supported if Python is built in debug mode (if the
-  ``Py_DEBUG`` macro is defined). In the limited C API, the :c:func:`Py_INCREF`
-  and :c:func:`Py_DECREF` functions are now implemented as opaque function
+* The limited C API is now supported if :ref:`Python is built in debug mode
+  <debug-build>` (if the ``Py_DEBUG`` macro is defined). In the limited C API,
+  the :c:func:`Py_INCREF` and :c:func:`Py_DECREF` functions are now implemented
+  as opaque function
   calls, rather than accessing directly the :c:member:`PyObject.ob_refcnt`
   member, if Python is built in debug mode and the ``Py_LIMITED_API`` macro
   targets Python 3.10 or newer. It became possible to support the limited C API
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index 03a877a..d7884ea 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -722,8 +722,8 @@ for the following events in the interpreter:
 * line of code executed.
 
 This can be used to instrument running interpreters in production,
-without the need to recompile specific debug builds or providing
-application-specific profiling/debugging code.
+without the need to recompile specific :ref:`debug builds <debug-build>` or
+providing application-specific profiling/debugging code.
 
 More details in :ref:`instrumentation`.
 
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index 75e1973..1199535 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -1588,8 +1588,8 @@ The initialization of the default warnings filters has changed as follows:
        for the new ``-X dev`` mode)
      * any implicit filters defined directly by the warnings machinery
 
-* in CPython debug builds, all warnings are now displayed by default (the
-  implicit filter list is empty)
+* in :ref:`CPython debug builds <debug-build>`, all warnings are now displayed
+  by default (the implicit filter list is empty)
 
 (Contributed by Nick Coghlan and Victor Stinner in :issue:`20361`,
 :issue:`32043`, and :issue:`32230`.)
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 91afffb..b1ecaae 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -211,7 +211,7 @@ Python now uses the same ABI whether it's built in release or debug mode. On
 Unix, when Python is built in debug mode, it is now possible to load C
 extensions built in release mode and C extensions built using the stable ABI.
 
-Release builds and debug builds are now ABI compatible: defining the
+Release builds and :ref:`debug builds <debug-build>` are now ABI compatible: defining the
 ``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`
@@ -904,7 +904,7 @@ for :func:`property`, :func:`classmethod`, and :func:`staticmethod`::
 io
 --
 
-In development mode (:option:`-X` ``env``) and in debug build, the
+In development mode (:option:`-X` ``env``) and in :ref:`debug build <debug-build>`, the
 :class:`io.IOBase` finalizer now logs the exception if the ``close()`` method
 fails. The exception is ignored silently by default in release build.
 (Contributed by Victor Stinner in :issue:`18748`.)
@@ -2246,4 +2246,4 @@ separator key, with ``&`` as the default.  This change also affects
 :func:`cgi.parse` and :func:`cgi.parse_multipart` as they use the affected
 functions internally. For more details, please see their respective
 documentation.
-(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.)
\ No newline at end of file
+(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.)
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index 24c72ee..c16b9a7 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -231,7 +231,7 @@ Other Language Changes
   absolute path for :mod:`__main__` module frames in this case.
   (Contributed by Victor Stinner in :issue:`20443`.)
 
-* In the :ref:`Python Development Mode <devmode>` and in debug build, the
+* In the :ref:`Python Development Mode <devmode>` and in :ref:`debug build <debug-build>`, the
   *encoding* and *errors* arguments are now checked for string encoding and
   decoding operations. Examples: :func:`open`, :meth:`str.encode` and
   :meth:`bytes.decode`.