From fc5d01fe12cd9d379676ccb4a976314623f79b7b Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 3 Oct 2026 20:00:28 +0100 Subject: [PATCH 1/2] Add `.. make-target::` directive for make targets, for easier viewing than the current titles. --- Doc/tools/extensions/pyspecific.py | 9 ++ Doc/using/configure.rst | 136 ++++++++++++----------------- 2 files changed, 67 insertions(+), 78 deletions(-) diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 9b335f2976a2fa3..ac956d66efd423a 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 5b1676e504a6283..a1b149c8cbd9b5e 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -1434,107 +1434,87 @@ Main build steps Main Makefile targets --------------------- -make -^^^^ +.. make-target:: 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: + 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) + * ``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. + 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-target:: make platform -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, + e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``. -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``. +.. make-target:: make profile-opt + 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 profile-opt -^^^^^^^^^^^^^^^^ +.. make-target:: 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 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. [#]_ -make clean -^^^^^^^^^^ +.. make-target:: make install -Remove built files. + Build the ``all`` target and install Python. +.. make-target:: make test -make distclean -^^^^^^^^^^^^^^ + Build the ``all`` target and run the Python test suite with the + ``--fast-ci`` option without GUI tests. Variables: -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. [#]_ + * ``TESTOPTS``: additional regrtest command-line options. + * ``TESTPYTHONOPTS``: additional Python command-line options. + * ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes). +.. make-target:: make ci -make install -^^^^^^^^^^^^ + This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests. -Build the ``all`` target and install Python. - - -make test -^^^^^^^^^ - -Build the ``all`` target and run the Python test suite with the -``--fast-ci`` option without GUI tests. Variables: - -* ``TESTOPTS``: additional regrtest command-line options. -* ``TESTPYTHONOPTS``: additional Python command-line options. -* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes). - - -make ci -^^^^^^^ - -This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests. - -.. versionadded:: 3.14 - - -make buildbottest -^^^^^^^^^^^^^^^^^ + .. versionadded:: 3.14 -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 file. + ``make regen-stdlib-module-names`` and ``autoconf`` must be run + separately for the remaining `generated files <#generated-files>`_. C extensions From 426bf03b5a84906df6bd190c731c43067414fef9 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 3 Oct 2026 20:25:25 +0100 Subject: [PATCH 2/2] Additional updates, and fix titles --- Doc/using/configure.rst | 58 +++++++++++++++++++++++------------------ Makefile.pre.in | 1 + 2 files changed, 33 insertions(+), 26 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index a1b149c8cbd9b5e..433a563be046c9f 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: @@ -181,9 +181,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 +216,7 @@ and `pkg-config `_ 1.8.1. .. _configure-options: -Configure Options +Configure options ================= List all :file:`configure` script options using:: @@ -223,7 +225,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 +630,7 @@ Options for third-party dependencies overriding ``pkg-config``. -WebAssembly Options +WebAssembly options ------------------- .. option:: --enable-wasm-dynamic-linking @@ -647,7 +649,7 @@ WebAssembly Options .. versionadded:: 3.11 -Install Options +Install options --------------- .. option:: --prefix=PREFIX @@ -911,7 +913,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 @@ -1202,7 +1204,7 @@ Libraries options .. versionadded:: 3.10 -Security Options +Security options ---------------- .. option:: --with-hash-algorithm=[fnv|siphash13|siphash24] @@ -1280,7 +1282,7 @@ Security Options .. versionadded:: 3.14 -macOS Options +macOS options ------------- See :source:`Mac/README.rst`. @@ -1335,7 +1337,7 @@ See :source:`Mac/README.rst`. .. versionadded:: 3.13 -iOS Options +iOS options ----------- See :source:`Platforms/Apple/iOS/README.md`. @@ -1360,7 +1362,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 @@ -1410,7 +1412,7 @@ Cross compiling example:: --with-build-python=../x86_64/python -Python Build System +Python build system =================== Main files of the build system @@ -1443,12 +1445,14 @@ Main Makefile targets 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: + all`` will build. The choices are: * ``profile-opt`` (configured with ``--enable-optimizations``) - * ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*`` or + * ``bolt-opt`` (configured with ``--enable-bolt``) + * ``build_emscripten`` (chosen if the host platform matches ``wasm32-emscripten``) - * ``build_all`` (configured without explicitly using either of the others) + * ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*``) + * ``build_all`` (configured without explicitly using any of the others) Depending on the most recent source file changes, Make will rebuild any targets (object files and executables) deemed out-of-date, @@ -1466,7 +1470,7 @@ Main Makefile targets 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 example, ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``. .. make-target:: make profile-opt @@ -1513,7 +1517,9 @@ Main Makefile targets 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 + ``make regen-stdlib-module-names``, ``make regen-limited-abi``, + ``make regen-configure``, ``make regen-sbom`` and + ``make regen-unicodedata`` must be run separately for the remaining `generated files <#generated-files>`_. @@ -1534,23 +1540,23 @@ Built-in modules have no ``__file__`` attribute: File "", line 1, in 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 - - >>> _asyncio.__file__ - '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so' + >>> import _zoneinfo + >>> _zoneinfo + + >>> _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 42480f28ad7f315..7ac01664c59c913 100644 --- a/Makefile.pre.in +++ b/Makefile.pre.in @@ -1855,6 +1855,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 \