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

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``
+      ``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are
-      are not supported if Python is configured using ``--without-pymalloc``
+      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
+      Default: value of the ``PLATLIBDIR`` macro which is set by the
-      by ``--with-platlibdir`` (default: ``"lib"``).
+      :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
+what is generally meant by :ref:`a debug build of Python <debug-build>`.
-enabled in the Unix build by adding ``--with-pydebug`` to the
+:c:macro:`Py_DEBUG` is enabled in the Unix build by adding
-:file:`./configure` command.  It is also implied by the presence of the
+: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`
+  :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.
-* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`
+* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`.
-* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`
+* "+ 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
+   :ref:`Python is built in debug mode <debug-build>`.
-   mode. The :envvar:`PYTHONMALLOC` environment variable can be used to install
+   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
+   If Python is :option:`configured --with-pydebug <--with-pydebug>`, it also
-   internal consistency checks.
+   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,13 +927,11 @@ 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
@@ -940,4 +939,4 @@ Setting these variables only has an effect in a debug build of Python.
    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.

Doc/using/configure.rst

@@ -0,0 +1,616 @@
+****************
+Configure Python
+****************
+
+.. _configure-options:
+
+Configure Options
+=================
+
+List all ``./configure`` script options using::
+
+    ./configure --help
+
+See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution.
+
+General Options
+---------------
+
+.. cmdoption:: --enable-loadable-sqlite-extensions
+
+   Support loadable extensions in the :mod:`_sqlite` extension module (default
+   is no), see the :mod:`sqlite3` module.
+
+   .. versionadded:: 3.6
+
+.. cmdoption:: --disable-ipv6
+
+   Disable IPv6 support (enabled by default if supported), see the
+   :mod:`socket` module.
+
+.. cmdoption:: --enable-big-digits[=15|30]
+
+   Use big digits (15 or 30 bits) for Python :class:`int` numbers (default is
+   system-dependent).
+
+   See :data:`sys.int_info.bits_per_digit <sys.int_info>`.
+
+.. cmdoption:: --with-cxx-main[=COMPILER]
+
+   Compile the Python ``main()`` function and link Python executable with C++
+   compiler specified in *COMPILER* (default is ``$CXX``).
+
+.. cmdoption:: --with-suffix=SUFFIX
+
+   Set executable suffix to *SUFFIX* (default is ``.exe``).
+
+.. cmdoption:: --with-tzpath=<list of absolute paths separated by pathsep>
+
+   Select the default time zone search path for :data:`zoneinfo.TZPATH`,
+   see the :mod:`zoneinfo` module.
+
+   .. versionadded:: 3.9
+
+.. cmdoption:: --without-decimal-contextvar
+
+   Build the ``_decimal`` extension module using a thread-local context rather
+   than a coroutine-local context (default), see the :mod:`decimal` module.
+
+   See :data:`decimal.HAVE_CONTEXTVAR`.
+
+   .. versionadded:: 3.9
+
+.. cmdoption:: --with-dbmliborder=db1:db2:...
+
+   Override order to check db backends for the :mod:`dbm` module
+
+   A valid value is a colon separated string with the backend names:
+
+   * ``ndbm``;
+   * ``gdbm``;
+   * ``bdb``.
+
+.. cmdoption:: --with-c-locale-coercion
+
+   Enable C locale coercion to a UTF-8 based locale (default is yes).
+
+   See :envvar:`PYTHONCOERCECLOCALE` and the :pep:`538`.
+
+.. cmdoption:: --with-platlibdir=DIRNAME
+
+   Python library directory name (default is ``lib``).
+
+   Fedora and SuSE use ``lib64`` on 64-bit platforms.
+
+   See :data:`sys.platlibdir`.
+
+   .. versionadded:: 3.9
+
+.. cmdoption:: --with-wheel-pkg-dir=PATH
+
+   Directory of wheel packages used by the :mod:`ensurepip` module
+   (none by default).
+
+   Some Linux distribution packaging policies recommend against bundling
+   dependencies. For example, Fedora installs wheel packages in the
+   ``/usr/share/python-wheels/`` directory and don't install the
+   :mod:`ensurepip._bundled` package.
+
+   .. versionadded:: 3.10
+
+
+Install Options
+---------------
+
+.. cmdoption:: --disable-test-modules
+
+   Don't build nor install test modules, like the :mod:`test` package or the
+   :mod:`_testcapi` extension module (built and installed by default).
+
+   .. versionadded:: 3.10
+
+.. cmdoption:: --with-ensurepip[=install|upgrade|no]
+
+   ``install`` or ``upgrade`` using bundled pip of the :mod:`ensurepip` module,
+   when installing Python (default is ``upgrade``).
+
+   .. versionadded:: 3.6
+
+
+Performance options
+-------------------
+
+Configuring Python using ``--enable-optimizations --with-lto`` (PGO + LTO) is
+recommended for best performance.
+
+.. cmdoption:: --enable-optimizations
+
+   Enable Profile Guided Optimization (PGO) using :envvar:`PROFILE_TASK`
+   (disabled by default).
+
+   Disable also semantic interposition in libpython if ``--enable-shared`` and
+   GCC is used: add ``-fno-semantic-interposition`` to the compiler and linker
+   flags.
+
+   .. versionadded:: 3.6
+
+   .. versionchanged:: 3.10
+      Use ``-fno-semantic-interposition`` on GCC.
+
+.. envvar:: PROFILE_TASK
+
+   Environment variable used in the Makefile: Python command line arguments for
+   the PGO generation task.
+
+   Default: ``-m test --pgo --timeout=$(TESTTIMEOUT)``.
+
+   .. versionadded:: 3.8
+
+.. cmdoption:: --with-lto
+
+   Enable Link Time Optimization (LTO) in any build (disabled by default).
+
+   .. versionadded:: 3.6
+
+.. cmdoption:: --with-computed-gotos
+
+   Enable computed gotos in evaluation loop (enabled by default on supported
+   compilers).
+
+.. cmdoption:: --without-pymalloc
+
+   Disable the specialized Python memory allocator :ref:`pymalloc <pymalloc>`
+   (enabled by default).
+
+   See also :envvar:`PYTHONMALLOC` environment variable.
+
+.. cmdoption:: --without-doc-strings
+
+   Disable static documentation strings to reduce the memory footprint (enabled
+   by default). Documentation strings defined in Python are not affected.
+
+   If used, the ``WITH_DOC_STRINGS`` macro is not defined. See the
+   ``PyDoc_STRVAR()`` macro.
+
+.. cmdoption:: --enable-profiling
+
+   Enable C-level code profiling with ``gprof`` (disabled by default).
+
+
+.. _debug-build:
+
+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.
+* Add ``d`` to :data:`sys.abiflags`.
+* Add :func:`sys.gettotalrefcount` function.
+* Add :option:`-X showrefcount <-X>` command line option.
+* Add :envvar:`PYTHONTHREADDEBUG` environment variable.
+* The list of default warning filters is empty in the :mod:`warnings` module.
+* Install debug hooks on memory allocators to detect buffer overflow and other
+  memory errors: see :c:func:`PyMem_SetupDebugHooks`.
+* Build Python with assertions (don't set ``NDEBUG`` macro):
+  ``assert(...);`` and ``_PyObject_ASSERT(...);`` are removed.
+  See also the :option:`--with-assertions` configure option.
+* Add runtime checks, code surroundeded by ``#ifdef Py_DEBUG`` and ``#endif``.
+* Unicode and int objects are created with their memory filled with a pattern
+  to help detecting uninitialized bytes.
+* Many functions ensure that are not called with an exception raised, since
+  they can clear or replace the current exception.
+* The garbage collector (:func:`gc.collect` function) runs some quick checks on
+  consistency.
+* Add support for the ``__ltrace__`` variable: enable low-level tracing in the
+  bytecode evaluation loop if the variable is defined.
+
+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
+   introduces the only ABI incompatibility.
+
+
+Debug options
+-------------
+
+.. cmdoption:: --with-pydebug
+
+   :ref:`Build Python in debug mode <debug-build>` (disabled by default).
+
+.. cmdoption:: --with-trace-refs
+
+   Enable tracing references for debugging purpose (disabled by default).
+
+   Effects:
+
+   * Define the ``Py_TRACE_REFS`` macro.
+   * Add :func:`sys.getobjects` function.
+   * Add :envvar:`PYTHONDUMPREFS` environment variable.
+
+   This build is not ABI compatible with release build (default build) or debug
+   build (``Py_DEBUG`` macro).
+
+   .. versionadded:: 3.8
+
+.. cmdoption:: --with-assertions
+
+   Build with C assertions enabled (default is no).
+
+   If set, the ``NDEBUG`` macro is not defined in the :envvar:`OPT` compiler
+   variable.
+
+   See also the :option:`--with-pydebug` option (:ref:`debug build
+   <debug-build>`) which also enables assertions.
+
+   .. versionadded:: 3.6
+
+.. cmdoption:: --with-valgrind
+
+   Enable Valgrind support (default is no).
+
+.. cmdoption:: --with-dtrace
+
+   Enable DTrace support (default is no).
+
+   .. versionadded:: 3.6
+
+.. cmdoption:: --with-address-sanitizer
+
+   Enable AddressSanitizer memory error detector, 'asan' (default is no).
+
+   .. versionadded:: 3.6
+
+.. cmdoption:: --with-memory-sanitizer
+
+   Enable MemorySanitizer allocation error detector, 'msan' (default is no).
+
+   .. versionadded:: 3.6
+
+.. cmdoption:: --with-undefined-behavior-sanitizer
+
+   Enable UndefinedBehaviorSanitizer undefined behaviour detector, 'ubsan'
+   (default is no).
+
+   .. versionadded:: 3.6
+
+
+Linker options
+--------------
+
+.. cmdoption:: --enable-shared
+
+   Enable building a shared Python library: "libpython" (default is no).
+
+.. cmdoption:: --without-static-libpython
+
+   Do not build ``libpythonMAJOR.MINOR.a`` and do not install ``python.o``
+   (built and enabled by default).
+
+   .. versionadded:: 3.10
+
+
+Libraries options
+-----------------
+
+.. cmdoption:: --with-libs='lib1 ...'
+
+   Link against additional libraries (default is no).
+
+.. cmdoption:: --with-system-expat
+
+   Build the :mod:`pyexpat` module using an installed ``expat`` library
+   (default is no).
+
+.. cmdoption:: --with-system-ffi
+
+   Build the :mod:`_ctypes` extension module using an installed ``ffi``
+   library, see the :mod:`ctypes` module (default is system-dependent).
+
+.. cmdoption:: --with-system-libmpdec
+
+   Build the ``_decimal`` extension module using an installed ``libmpdec``
+   library, see the :mod:`decimal` module (default is no).
+
+   .. versionadded:: 3.3
+
+.. cmdoption:: --with(out)-readline[=editline]
+
+   Use ``editline`` for backend or disable the :mod:`readline` module.
+
+   .. versionadded:: 3.10
+
+.. cmdoption:: --with-tcltk-includes='-I...'
+
+   Override search for Tcl and Tk include files.
+
+.. cmdoption:: --with-tcltk-libs='-L...'
+
+   Override search for Tcl and Tk libraries.
+
+.. cmdoption:: --with-libm=STRING
+
+   Override ``libm`` math library to *STRING* (default is system-dependent).
+
+.. cmdoption:: --with-libc=STRING
+
+   Override ``libc`` C library to *STRING* (default is system-dependent).
+
+.. cmdoption:: --with-openssl=DIR
+
+   Root of the OpenSSL directory.
+
+.. cmdoption:: --with-openssl-rpath=[DIR|auto|no]
+
+   Set runtime library directory (rpath) for OpenSSL libraries:
+
+   * ``no`` (default): don't set rpath;
+   * ``auto``: auto-detect rpath from :option:`--with-openssl` and
+     ``pkg-config``;
+   * *DIR*: set an explicit rpath.
+
+   .. versionadded:: 3.10
+
+
+Security Options
+----------------
+
+.. cmdoption:: --with-hash-algorithm=[fnv|siphash24]
+
+   Select hash algorithm for use in ``Python/pyhash.c``:
+
+   * ``fnv``;
+   * ``siphash24`` (default).
+
+   .. versionadded:: 3.4
+
+.. cmdoption:: --with-builtin-hashlib-hashes=md5,sha1,sha256,sha512,sha3,blake2
+
+   Built-in hash modules:
+
+   * ``md5``;
+   * ``sha1``;
+   * ``sha256``;
+   * ``sha512``;
+   * ``sha3`` (with shake);
+   * ``blake2``.
+
+   .. versionadded:: 3.9
+
+.. cmdoption:: --with-ssl-default-suites=[python|openssl|STRING]
+
+   Override the OpenSSL default cipher suites string:
+
+   * ``python``: use Python's preferred selection (default);
+   * ``openssl``: leave OpenSSL's defaults untouched;
+   * *STRING*: use a custom string, PROTOCOL_SSLv2 ignores the setting.
+
+   See the :mod:`ssl` module.
+
+   .. versionadded:: 3.7
+
+
+macOS Options
+-------------
+
+See ``Mac/README.rst``.
+
+.. cmdoption:: --enable-universalsdk[=SDKDIR]
+
+   Create a universal binary build. *SDKDIR* specifies which macOS SDK should
+   be used to perform the build (default is no).
+
+.. cmdoption:: --enable-framework[=INSTALLDIR]
+
+   Create a Python.framework rather than a traditional Unix install. Optional
+   *INSTALLDIR* specifies the installation path (default is no).
+
+.. cmdoption:: --with-universal-archs=ARCH
+
+   Specify the kind of universal binary that should be created. this option is
+   only valid when :option:`--enable-universalsdk` is set.
+
+   Options are:
+
+   * ``universal2``;
+   * ``32-bit``;
+   * ``64-bit``;
+   * ``3-way``;
+   * ``intel``;
+   * ``intel-32``;
+   * ``intel-64``;
+   * ``all``.
+
+.. cmdoption:: --with-framework-name=FRAMEWORK
+
+   Specify the name for the python framework on macOS only valid when
+   :option:`--enable-framework` is set (default: ``Python``).
+
+
+Compiler and linker flags
+=========================
+
+Options set by the ``./configure`` script, ``Makefile`` and by environment
+variables.
+
+Preprocessor flags
+------------------
+
+.. envvar:: CPP
+
+   C preprocessor.
+
+.. envvar:: CONFIGURE_CPPFLAGS
+
+   .. versionadded:: 3.6
+
+.. envvar:: CPPFLAGS
+
+   (Objective) C/C++ preprocessor flags, e.g. ``-I<include dir>`` if you have
+   headers in a nonstandard directory ``<include dir>``.
+
+   Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's
+   value for setup.py to be able to build extension modules using the
+   directories specified in the environment variables.
+
+.. envvar:: BASECPPFLAGS
+
+   .. versionadded:: 3.4
+
+.. envvar:: MULTIARCH_CPPFLAGS
+
+   .. versionadded:: 3.6
+
+.. envvar:: PY_CPPFLAGS
+
+   Extra preprocessor flags added for building the interpreter object files.
+
+   Default: ``$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)``.
+
+   .. versionadded:: 3.2
+
+Compiler flags
+--------------
+
+.. envvar:: CC
+
+   C compiler command.
+
+.. envvar:: CFLAGS
+
+   C compiler flags.
+
+.. envvar:: CFLAGS_NODIST
+
+   :envvar:`CFLAGS_NODIST` is used for building the interpreter and stdlib C
+   extensions.  Use it when a compiler flag should *not* be part of the
+   distutils :envvar:`CFLAGS` once Python is installed (:issue:`21121`).
+
+   .. versionadded:: 3.5
+
+.. envvar:: EXTRA_CFLAGS
+
+   Extra C compiler flags.
+
+.. envvar:: CONFIGURE_CFLAGS
+
+   .. versionadded:: 3.2
+
+.. envvar:: CONFIGURE_CFLAGS_NODIST
+
+   .. versionadded:: 3.5
+
+.. envvar:: BASECFLAGS
+
+.. envvar:: OPT
+
+   Optimization flags.
+
+.. envvar:: CFLAGS_ALIASING
+
+   Strict or non-strict aliasing flags used to compile ``Python/dtoa.c``.
+
+   .. versionadded:: 3.7
+
+.. envvar:: CFLAGSFORSHARED
+
+   Extra C flags added for building the interpreter object files.
+
+.. envvar:: PY_CFLAGS
+
+   Default: ``$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)``.
+
+.. envvar:: PY_CFLAGS_NODIST
+
+   Default: ``$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal``.
+
+   .. versionadded:: 3.5
+
+.. envvar:: PY_STDMODULE_CFLAGS
+
+   C flags used for building the interpreter object files.
+
+   Default: ``$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)``.
+
+   .. versionadded:: 3.7
+
+.. envvar:: PY_CORE_CFLAGS
+
+   Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE``.
+
+   .. versionadded:: 3.2
+
+.. envvar:: PY_BUILTIN_MODULE_CFLAGS
+
+   Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN``.
+
+   .. versionadded:: 3.8
+
+
+Linker flags
+------------
+
+.. envvar:: CONFIGURE_LDFLAGS
+
+   Avoid assigning :envvar:`CFLAGS`, :envvar:`LDFLAGS`, etc. so users can use
+   them on the command line to append to these values without stomping the
+   pre-set values.
+
+   .. versionadded:: 3.2
+
+.. envvar:: LDFLAGS_NODIST
+
+   :envvar:`LDFLAGS_NODIST` is used in the same manner as
+   :envvar:`CFLAGS_NODIST`.  Use it when a linker flag should *not* be part of
+   the distutils :envvar:`LDFLAGS` once Python is installed (:issue:`35257`).
+
+.. envvar:: CONFIGURE_LDFLAGS_NODIST
+
+   .. versionadded:: 3.8
+
+.. envvar:: LDFLAGS
+
+   Linker flags, e.g. ``-L<lib dir>`` if you have libraries in a nonstandard
+   directory ``<lib dir>``.
+
+   Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's
+   value for setup.py to be able to build extension modules using the
+   directories specified in the environment variables.
+
+.. envvar:: LIBS
+
+   Libraries to pass to the linker, e.g. ``-l<library>``.
+
+.. envvar:: LDSHARED
+
+   Command to build a shared library.
+
+   Default: ``@LDSHARED@ $(PY_LDFLAGS)``.
+
+.. envvar:: BLDSHARED
+
+   Command to build libpython shared library.
+
+   Default: ``@BLDSHARED@ $(PY_CORE_LDFLAGS)``.
+
+.. envvar:: PY_LDFLAGS
+
+   Default: ``$(CONFIGURE_LDFLAGS) $(LDFLAGS)``.
+
+.. envvar:: PY_LDFLAGS_NODIST
+
+   Default: ``$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)``.
+
+   .. versionadded:: 3.8
+
+.. envvar:: PY_CORE_LDFLAGS
+
+   Linker flags used for building the interpreter object files.
+
+   .. versionadded:: 3.8

Doc/using/index.rst

@@ -15,6 +15,7 @@ interpreter and things that make working with Python easier.
 
    cmdline.rst
    unix.rst
+   configure.rst
    windows.rst
    mac.rst
    editors.rst

Doc/using/unix.rst

@@ -78,9 +78,9 @@ The build process consists of the usual commands::
    make
    make install
 
-Configuration options and caveats for specific Unix platforms are extensively
+:ref:`Configuration options <configure-options>` and caveats for specific Unix
-documented in the :source:`README.rst` file in the root of the Python source
+platforms are extensively documented in the :source:`README.rst` file in the
-tree.
+root of the Python source tree.
 
 .. warning::
 

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
+* The limited C API is now supported if :ref:`Python is built in debug mode
-  ``Py_DEBUG`` macro is defined). In the limited C API, the :c:func:`Py_INCREF`
+  <debug-build>` (if the ``Py_DEBUG`` macro is defined). In the limited C API,
-  and :c:func:`Py_DECREF` functions are now implemented as opaque function
+  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

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
+without the need to recompile specific :ref:`debug builds <debug-build>` or
-application-specific profiling/debugging code.
+providing application-specific profiling/debugging code.
 
 More details in :ref:`instrumentation`.
 

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
+* in :ref:`CPython debug builds <debug-build>`, all warnings are now displayed
-  implicit filter list is empty)
+  by default (the implicit filter list is empty)
 
 (Contributed by Nick Coghlan and Victor Stinner in :issue:`20361`,
 :issue:`32043`, and :issue:`32230`.)

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`.)

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