Skip to content

Fix miscellaneous issues in the 'Configure Python' docs #158679

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StanFromIreland wants to merge 2 commits into
base: main
Choose a base branch
from
+95 −99
Open

Fix miscellaneous issues in the 'Configure Python' docs #158679

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fc5d01f
Add `.. make-target::` directive for make targets, for easier viewing…
StanFromIreland Oct 3, 2026
426bf03
Additional updates, and fix titles
StanFromIreland Oct 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions Doc/tools/extensions/pyspecific.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

import re

from docutils import nodes
from sphinx import addnodes
from sphinx.domains.python import PyFunction, PyMethod

Expand Down Expand Up @@ -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.')
Expand Down Expand Up @@ -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)
Expand Down
184 changes: 85 additions & 99 deletions Doc/using/configure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Configure Python

.. _build-requirements:

Build Requirements
Build requirements
==================

To build CPython, you will need:
Expand Down Expand Up @@ -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
----------------
Expand Down Expand Up @@ -214,7 +216,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::
Expand All @@ -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
Expand Down Expand Up @@ -628,7 +630,7 @@ Options for third-party dependencies
overriding ``pkg-config``.


WebAssembly Options
WebAssembly options
-------------------

.. option:: --enable-wasm-dynamic-linking
Expand All @@ -647,7 +649,7 @@ WebAssembly Options
.. versionadded:: 3.11


Install Options
Install options
---------------

.. option:: --prefix=PREFIX
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1202,7 +1204,7 @@ Libraries options
.. versionadded:: 3.10


Security Options
Security options
----------------

.. option:: --with-hash-algorithm=[fnv|siphash13|siphash24]
Expand Down Expand Up @@ -1280,7 +1282,7 @@ Security Options
.. versionadded:: 3.14


macOS Options
macOS options
-------------

See :source:`Mac/README.rst`.
Expand Down Expand Up @@ -1335,7 +1337,7 @@ See :source:`Mac/README.rst`.

.. versionadded:: 3.13

iOS Options
iOS options
-----------

See :source:`Platforms/Apple/iOS/README.md`.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -1434,107 +1436,91 @@ 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 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``)
* ``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)

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,
for example, ``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``, ``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>`_.


C extensions
Expand All @@ -1554,23 +1540,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:

Expand Down
1 change: 1 addition & 0 deletions Makefile.pre.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
Loading