https://github.com/python/cpython/commit/d138fd9c613ecd82e58653e9ab544fbed95ac239
commit: d138fd9c613ecd82e58653e9ab544fbed95ac239
branch: main
author: Stan Ulbrych <[email protected]>
committer: StanFromIreland <[email protected]>
date: 2026-11-06T12:33:29Z
summary:
Fix miscellaneous issues in the 'Configure Python' docs (#158679)
files:
M Doc/tools/extensions/pyspecific.py
M Doc/using/configure.rst
M Makefile.pre.in
diff --git a/Doc/tools/extensions/pyspecific.py
b/Doc/tools/extensions/pyspecific.py
index 9b335f2976a2fa..ac956d66efd423 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -11,6 +11,7 @@
import re
+from docutils import nodes
from sphinx import addnodes
from sphinx.domains.python import PyFunction, PyMethod
@@ -78,6 +79,13 @@ def parse_pdb_command(env, sig, signode):
return fullname
+def parse_make_target(env, sig, signode):
+ """Transform a make target signature into RST nodes."""
+ signode += addnodes.desc_name(sig, sig)
+ signode['ids'].append(nodes.make_id(sig))
+ return sig
+
+
def parse_monitoring_event(env, sig, signode):
"""Transform a monitoring event signature into RST nodes."""
signode += addnodes.desc_addname('sys.monitoring.events.',
'sys.monitoring.events.')
@@ -113,6 +121,7 @@ def setup(app):
app.add_object_type('opcode', 'opcode', '%s (opcode)',
parse_opcode_signature)
app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)',
parse_pdb_command)
app.add_object_type('monitoring-event', 'monitoring-event', '%s
(monitoring event)', parse_monitoring_event)
+ app.add_object_type('make-target', 'make-target', '%s (make target)',
parse_make_target)
app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
app.connect('env-check-consistency', patch_pairindextypes)
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 602cf9fb6f082d..ea608394b8eb10 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -7,7 +7,7 @@ Configure Python
.. _build-requirements:
-Build Requirements
+Build requirements
==================
To build CPython, you will need:
@@ -171,6 +171,8 @@ platform-specific modules like :mod:`winreg` are not listed
here.
SQLite 3.15.2 is now required for :mod:`sqlite3`.
+.. _generated-files:
+
Generated files
===============
@@ -181,9 +183,11 @@ files. Commands to regenerate all generated files::
make regen-stdlib-module-names
make regen-limited-abi
make regen-configure
+ make regen-sbom
+ make regen-unicodedata
-The ``Makefile.pre.in`` file documents generated files, their inputs, and
tools used
-to regenerate them. Search for ``regen-*`` make targets.
+The :source:`Makefile.pre.in` file documents generated files, their inputs, and
+tools used to regenerate them. Search for ``regen-*`` make targets.
configure script
----------------
@@ -214,7 +218,7 @@ and `pkg-config
<https://www.freedesktop.org/wiki/Software/pkg-config/>`_ 1.8.1.
.. _configure-options:
-Configure Options
+Configure options
=================
List all :file:`configure` script options using::
@@ -223,7 +227,7 @@ List all :file:`configure` script options using::
See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution.
-General Options
+General options
---------------
.. option:: --enable-loadable-sqlite-extensions
@@ -628,7 +632,7 @@ Options for third-party dependencies
overriding ``pkg-config``.
-WebAssembly Options
+WebAssembly options
-------------------
.. option:: --enable-wasm-dynamic-linking
@@ -647,7 +651,7 @@ WebAssembly Options
.. versionadded:: 3.11
-Install Options
+Install options
---------------
.. option:: --prefix=PREFIX
@@ -934,7 +938,7 @@ also be used to improve performance.
.. _debug-build:
-Python Debug Build
+Python debug build
------------------
A debug build is Python built with the :option:`--with-pydebug` configure
@@ -1248,7 +1252,7 @@ Libraries options
.. versionadded:: 3.10
-Security Options
+Security options
----------------
.. option:: --with-hash-algorithm=[fnv|siphash13|siphash24]
@@ -1326,7 +1330,7 @@ Security Options
.. versionadded:: 3.14
-macOS Options
+macOS options
-------------
See :source:`Mac/README.rst`.
@@ -1381,7 +1385,7 @@ See :source:`Mac/README.rst`.
.. versionadded:: 3.13
-iOS Options
+iOS options
-----------
See :source:`Platforms/Apple/iOS/README.md`.
@@ -1406,7 +1410,7 @@ rejects :option:`--enable-shared`. See
iOS builds may be configured without a framework.
-Cross Compiling Options
+Cross compiling options
-----------------------
Cross compiling, also known as cross building, can be used to build Python
@@ -1456,7 +1460,7 @@ Cross compiling example::
--with-build-python=../x86_64/python
-Python Build System
+Python build system
===================
Main files of the build system
@@ -1480,107 +1484,88 @@ Main build steps
Main Makefile targets
---------------------
-make
-^^^^
-
-For the most part, when rebuilding after editing some code or
-refreshing your checkout from upstream, all you need to do is execute
-``make``, which (per Make's semantics) builds the default target, the
-first one defined in the Makefile. By tradition (including in the
-CPython project) this is usually the ``all`` target. The
-``configure`` script expands an ``autoconf`` variable,
-``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
-all`` will build. The three choices are:
-
-* ``profile-opt`` (configured with ``--enable-optimizations``)
-* ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*`` or
- ``wasm32-emscripten``)
-* ``build_all`` (configured without explicitly using either of the others)
-
-Depending on the most recent source file changes, Make will rebuild
-any targets (object files and executables) deemed out-of-date,
-including running ``configure`` again if necessary. Source/target
-dependencies are many and maintained manually however, so Make
-sometimes doesn't have all the information necessary to correctly
-detect all targets which need to be rebuilt. Depending on which
-targets aren't rebuilt, you might experience a number of problems. If
-you have build or test problems which you can't otherwise explain,
-``make clean && make`` should work around most dependency problems, at
-the expense of longer build times.
-
-
-make platform
-^^^^^^^^^^^^^
+.. make-target:: make
-Build the ``python`` program, but don't build the standard library
-extension modules. This generates a file named ``platform`` which
-contains a single line describing the details of the build platform,
-e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
+ For the most part, when rebuilding after editing some code or
+ refreshing your checkout from upstream, all you need to do is execute
+ ``make``, which (per Make's semantics) builds the default target, the
+ first one defined in the Makefile. By tradition (including in the
+ CPython project) this is usually the ``all`` target. The
+ ``configure`` script expands an ``autoconf`` variable,
+ ``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
+ all`` will build. The choices are:
+ * ``profile-opt`` (configured with ``--enable-optimizations``)
+ * ``bolt-opt`` (configured with ``--enable-bolt``)
+ * ``build_emscripten`` (chosen if the host platform matches
+ ``wasm32-emscripten``)
+ * ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*``)
+ * ``build_all`` (configured without explicitly using any of the others)
-make profile-opt
-^^^^^^^^^^^^^^^^
+ Depending on the most recent source file changes, Make will rebuild
+ any targets (object files and executables) deemed out-of-date,
+ including running ``configure`` again if necessary. Source/target
+ dependencies are many and maintained manually however, so Make
+ sometimes doesn't have all the information necessary to correctly
+ detect all targets which need to be rebuilt. Depending on which
+ targets aren't rebuilt, you might experience a number of problems. If
+ you have build or test problems which you can't otherwise explain,
+ ``make clean && make`` should work around most dependency problems, at
+ the expense of longer build times.
-Build Python using profile-guided optimization (PGO). You can use the
-configure :option:`--enable-optimizations` option to make this the
-default target of the ``make`` command (``make all`` or just
-``make``).
+.. make-target:: make platform
+ Build the ``python`` program, but don't build the standard library
+ extension modules. This generates a file named ``platform`` which
+ contains a single line describing the details of the build platform,
+ for example, ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
+.. make-target:: make profile-opt
-make clean
-^^^^^^^^^^
+ Build Python using profile-guided optimization (PGO). You can use the
+ configure :option:`--enable-optimizations` option to make this the
+ default target of the ``make`` command (``make all`` or just
+ ``make``).
-Remove built files.
+.. make-target:: make clean
+ Remove built files.
-make distclean
-^^^^^^^^^^^^^^
+.. make-target:: make distclean
-In addition to the work done by ``make clean``, remove files
-created by the configure script. ``configure`` will have to be run
-before building again. [#]_
+ In addition to the work done by ``make clean``, remove files
+ created by the configure script. ``configure`` will have to be run
+ before building again. [#]_
+.. make-target:: make install
-make install
-^^^^^^^^^^^^
+ Build the ``all`` target and install Python.
-Build the ``all`` target and install Python.
+.. make-target:: make test
+ Build the ``all`` target and run the Python test suite with the
+ ``--fast-ci`` option without GUI tests. Variables:
-make test
-^^^^^^^^^
+ * ``TESTOPTS``: additional regrtest command-line options.
+ * ``TESTPYTHONOPTS``: additional Python command-line options.
+ * ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
-Build the ``all`` target and run the Python test suite with the
-``--fast-ci`` option without GUI tests. Variables:
+.. make-target:: make ci
-* ``TESTOPTS``: additional regrtest command-line options.
-* ``TESTPYTHONOPTS``: additional Python command-line options.
-* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
+ This is similar to ``make test``, but uses the ``-ugui`` to also run GUI
tests.
+ .. versionadded:: 3.14
-make ci
-^^^^^^^
-
-This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests.
-
-.. versionadded:: 3.14
-
-
-make buildbottest
-^^^^^^^^^^^^^^^^^
-
-This is similar to ``make test``, but uses the ``--slow-ci``
-option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
+.. make-target:: make buildbottest
+ This is similar to ``make test``, but uses the ``--slow-ci``
+ option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
-make regen-all
-^^^^^^^^^^^^^^
+.. make-target:: make regen-all
-Regenerate (almost) all generated files. These include (but are not
-limited to) bytecode cases, and parser generator file.
-``make regen-stdlib-module-names`` and ``autoconf`` must be run
-separately for the remaining `generated files <#generated-files>`_.
+ Regenerate (almost) all generated files. These include (but are not
+ limited to) bytecode cases, and parser generator files. See
+ :ref:`generated-files` for the targets that must be run separately.
C extensions
@@ -1600,23 +1585,23 @@ Built-in modules have no ``__file__`` attribute:
File "<stdin>", line 1, in <module>
AttributeError: module 'sys' has no attribute '__file__'
-Other C extensions are built as dynamic libraries, like the ``_asyncio``
module.
+Other C extensions are built as dynamic libraries, like the ``_zoneinfo``
module.
They are built with the ``Py_BUILD_CORE_MODULE`` macro defined.
-Example on Linux x86-64:
+For example on Linux x86-64:
.. code-block:: pycon
- >>> import _asyncio
- >>> _asyncio
- <module '_asyncio' from
'/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
- >>> _asyncio.__file__
- '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'
+ >>> import _zoneinfo
+ >>> _zoneinfo
+ <module '_zoneinfo' from
'/.../lib.linux-x86_64-3.16/_zoneinfo.cpython-316d-x86_64-linux-gnu.so'>
+ >>> _zoneinfo.__file__
+ '/.../lib.linux-x86_64-3.16/_zoneinfo.cpython-316d-x86_64-linux-gnu.so'
:file:`Modules/Setup` is used to generate Makefile targets to build C
extensions.
At the beginning of the files, C extensions are built as built-in modules.
Extensions defined after the ``*shared*`` marker are built as dynamic
libraries.
-The :c:macro:`!PyAPI_FUNC()`, :c:macro:`!PyAPI_DATA()` and
+The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_DATA()` and
:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/exports.h` are defined
differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:
diff --git a/Makefile.pre.in b/Makefile.pre.in
index e74deee353488f..f1b5eb3bba34fd 100644
--- a/Makefile.pre.in
+++ b/Makefile.pre.in
@@ -1915,6 +1915,7 @@ regen-unicodedata:
# Regenerate all generated files
# "clinic" is regenerated implicitly via "regen-global-objects".
+# Keep the list of targets to run manually in sync with
Doc/using/configure.rst.
.PHONY: regen-all
regen-all: regen-cases regen-slots \
regen-token regen-ast regen-keyword regen-sre regen-frozen \
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
