Skip to content

Commit f72faec

Browse files
[3.14] Fix miscellaneous issues in the 'Configure Python' docs (GH-158679) (#161487)
(cherry picked from commit d138fd9) Co-authored-by: Stan Ulbrych <stan@python.org>
1 parent dcb687c commit f72faec

3 files changed

Lines changed: 94 additions & 99 deletions

File tree

‎Doc/tools/extensions/pyspecific.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
import re
1313

14+
from docutils import nodes
1415
from sphinx import addnodes
1516
from sphinx.domains.python import PyFunction, PyMethod
1617

@@ -78,6 +79,13 @@ def parse_pdb_command(env, sig, signode):
7879
return fullname
7980

8081

82+
def parse_make_target(env, sig, signode):
83+
"""Transform a make target signature into RST nodes."""
84+
signode += addnodes.desc_name(sig, sig)
85+
signode['ids'].append(nodes.make_id(sig))
86+
return sig
87+
88+
8189
def parse_monitoring_event(env, sig, signode):
8290
"""Transform a monitoring event signature into RST nodes."""
8391
signode += addnodes.desc_addname('sys.monitoring.events.', 'sys.monitoring.events.')
@@ -113,6 +121,7 @@ def setup(app):
113121
app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
114122
app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)
115123
app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event)
124+
app.add_object_type('make-target', 'make-target', '%s (make target)', parse_make_target)
116125
app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
117126
app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
118127
app.connect('env-check-consistency', patch_pairindextypes)

‎Doc/using/configure.rst‎

Lines changed: 84 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Configure Python
77

88
.. _build-requirements:
99

10-
Build Requirements
10+
Build requirements
1111
==================
1212

1313
To build CPython, you will need:
@@ -164,6 +164,8 @@ platform-specific modules like :mod:`winreg` are not listed here.
164164
SQLite 3.15.2 is now required for :mod:`sqlite3`.
165165

166166

167+
.. _generated-files:
168+
167169
Generated files
168170
===============
169171

@@ -174,9 +176,11 @@ files. Commands to regenerate all generated files::
174176
make regen-stdlib-module-names
175177
make regen-limited-abi
176178
make regen-configure
179+
make regen-sbom
180+
make regen-unicodedata
177181

178-
The ``Makefile.pre.in`` file documents generated files, their inputs, and tools used
179-
to regenerate them. Search for ``regen-*`` make targets.
182+
The :source:`Makefile.pre.in` file documents generated files, their inputs, and
183+
tools used to regenerate them. Search for ``regen-*`` make targets.
180184

181185
configure script
182186
----------------
@@ -207,7 +211,7 @@ and `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ 1.8.1.
207211

208212
.. _configure-options:
209213

210-
Configure Options
214+
Configure options
211215
=================
212216

213217
List all :file:`configure` script options using::
@@ -216,7 +220,7 @@ List all :file:`configure` script options using::
216220

217221
See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution.
218222

219-
General Options
223+
General options
220224
---------------
221225

222226
.. option:: --enable-loadable-sqlite-extensions
@@ -579,7 +583,7 @@ Options for third-party dependencies
579583
overriding ``pkg-config``.
580584

581585

582-
WebAssembly Options
586+
WebAssembly options
583587
-------------------
584588

585589
.. option:: --enable-wasm-dynamic-linking
@@ -598,7 +602,7 @@ WebAssembly Options
598602
.. versionadded:: 3.11
599603

600604

601-
Install Options
605+
Install options
602606
---------------
603607

604608
.. option:: --prefix=PREFIX
@@ -810,7 +814,7 @@ also be used to improve performance.
810814

811815
.. _debug-build:
812816

813-
Python Debug Build
817+
Python debug build
814818
------------------
815819

816820
A debug build is Python built with the :option:`--with-pydebug` configure
@@ -1039,7 +1043,7 @@ Libraries options
10391043
.. versionadded:: 3.10
10401044

10411045

1042-
Security Options
1046+
Security options
10431047
----------------
10441048

10451049
.. option:: --with-hash-algorithm=[fnv|siphash13|siphash24]
@@ -1117,7 +1121,7 @@ Security Options
11171121
.. versionadded:: 3.14
11181122

11191123

1120-
macOS Options
1124+
macOS options
11211125
-------------
11221126

11231127
See :source:`Mac/README.rst`.
@@ -1172,7 +1176,7 @@ See :source:`Mac/README.rst`.
11721176

11731177
.. versionadded:: 3.13
11741178

1175-
iOS Options
1179+
iOS options
11761180
-----------
11771181

11781182
See :source:`iOS/README.rst`.
@@ -1187,7 +1191,7 @@ See :source:`iOS/README.rst`.
11871191
Specify the name for the framework (default: ``Python``).
11881192

11891193

1190-
Cross Compiling Options
1194+
Cross compiling options
11911195
-----------------------
11921196

11931197
Cross compiling, also known as cross building, can be used to build Python
@@ -1237,7 +1241,7 @@ Cross compiling example::
12371241
--with-build-python=../x86_64/python
12381242

12391243

1240-
Python Build System
1244+
Python build system
12411245
===================
12421246

12431247
Main files of the build system
@@ -1261,107 +1265,88 @@ Main build steps
12611265
Main Makefile targets
12621266
---------------------
12631267

1264-
make
1265-
^^^^
1266-
1267-
For the most part, when rebuilding after editing some code or
1268-
refreshing your checkout from upstream, all you need to do is execute
1269-
``make``, which (per Make's semantics) builds the default target, the
1270-
first one defined in the Makefile. By tradition (including in the
1271-
CPython project) this is usually the ``all`` target. The
1272-
``configure`` script expands an ``autoconf`` variable,
1273-
``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
1274-
all`` will build. The three choices are:
1275-
1276-
* ``profile-opt`` (configured with ``--enable-optimizations``)
1277-
* ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*`` or
1278-
``wasm32-emscripten``)
1279-
* ``build_all`` (configured without explicitly using either of the others)
1280-
1281-
Depending on the most recent source file changes, Make will rebuild
1282-
any targets (object files and executables) deemed out-of-date,
1283-
including running ``configure`` again if necessary. Source/target
1284-
dependencies are many and maintained manually however, so Make
1285-
sometimes doesn't have all the information necessary to correctly
1286-
detect all targets which need to be rebuilt. Depending on which
1287-
targets aren't rebuilt, you might experience a number of problems. If
1288-
you have build or test problems which you can't otherwise explain,
1289-
``make clean && make`` should work around most dependency problems, at
1290-
the expense of longer build times.
1291-
1292-
1293-
make platform
1294-
^^^^^^^^^^^^^
1268+
.. make-target:: make
12951269

1296-
Build the ``python`` program, but don't build the standard library
1297-
extension modules. This generates a file named ``platform`` which
1298-
contains a single line describing the details of the build platform,
1299-
e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
1270+
For the most part, when rebuilding after editing some code or
1271+
refreshing your checkout from upstream, all you need to do is execute
1272+
``make``, which (per Make's semantics) builds the default target, the
1273+
first one defined in the Makefile. By tradition (including in the
1274+
CPython project) this is usually the ``all`` target. The
1275+
``configure`` script expands an ``autoconf`` variable,
1276+
``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
1277+
all`` will build. The choices are:
13001278

1279+
* ``profile-opt`` (configured with ``--enable-optimizations``)
1280+
* ``bolt-opt`` (configured with ``--enable-bolt``)
1281+
* ``build_emscripten`` (chosen if the host platform matches
1282+
``wasm32-emscripten``)
1283+
* ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*``)
1284+
* ``build_all`` (configured without explicitly using any of the others)
13011285

1302-
make profile-opt
1303-
^^^^^^^^^^^^^^^^
1286+
Depending on the most recent source file changes, Make will rebuild
1287+
any targets (object files and executables) deemed out-of-date,
1288+
including running ``configure`` again if necessary. Source/target
1289+
dependencies are many and maintained manually however, so Make
1290+
sometimes doesn't have all the information necessary to correctly
1291+
detect all targets which need to be rebuilt. Depending on which
1292+
targets aren't rebuilt, you might experience a number of problems. If
1293+
you have build or test problems which you can't otherwise explain,
1294+
``make clean && make`` should work around most dependency problems, at
1295+
the expense of longer build times.
13041296

1305-
Build Python using profile-guided optimization (PGO). You can use the
1306-
configure :option:`--enable-optimizations` option to make this the
1307-
default target of the ``make`` command (``make all`` or just
1308-
``make``).
1297+
.. make-target:: make platform
13091298

1299+
Build the ``python`` program, but don't build the standard library
1300+
extension modules. This generates a file named ``platform`` which
1301+
contains a single line describing the details of the build platform,
1302+
for example, ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
13101303

1304+
.. make-target:: make profile-opt
13111305

1312-
make clean
1313-
^^^^^^^^^^
1306+
Build Python using profile-guided optimization (PGO). You can use the
1307+
configure :option:`--enable-optimizations` option to make this the
1308+
default target of the ``make`` command (``make all`` or just
1309+
``make``).
13141310

1315-
Remove built files.
1311+
.. make-target:: make clean
13161312

1313+
Remove built files.
13171314

1318-
make distclean
1319-
^^^^^^^^^^^^^^
1315+
.. make-target:: make distclean
13201316

1321-
In addition to the work done by ``make clean``, remove files
1322-
created by the configure script. ``configure`` will have to be run
1323-
before building again. [#]_
1317+
In addition to the work done by ``make clean``, remove files
1318+
created by the configure script. ``configure`` will have to be run
1319+
before building again. [#]_
13241320

1321+
.. make-target:: make install
13251322

1326-
make install
1327-
^^^^^^^^^^^^
1323+
Build the ``all`` target and install Python.
13281324

1329-
Build the ``all`` target and install Python.
1325+
.. make-target:: make test
13301326

1327+
Build the ``all`` target and run the Python test suite with the
1328+
``--fast-ci`` option without GUI tests. Variables:
13311329

1332-
make test
1333-
^^^^^^^^^
1330+
* ``TESTOPTS``: additional regrtest command-line options.
1331+
* ``TESTPYTHONOPTS``: additional Python command-line options.
1332+
* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
13341333

1335-
Build the ``all`` target and run the Python test suite with the
1336-
``--fast-ci`` option without GUI tests. Variables:
1334+
.. make-target:: make ci
13371335

1338-
* ``TESTOPTS``: additional regrtest command-line options.
1339-
* ``TESTPYTHONOPTS``: additional Python command-line options.
1340-
* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
1336+
This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests.
13411337

1338+
.. versionadded:: 3.14
13421339

1343-
make ci
1344-
^^^^^^^
1345-
1346-
This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests.
1347-
1348-
.. versionadded:: 3.14
1349-
1350-
1351-
make buildbottest
1352-
^^^^^^^^^^^^^^^^^
1353-
1354-
This is similar to ``make test``, but uses the ``--slow-ci``
1355-
option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
1340+
.. make-target:: make buildbottest
13561341

1342+
This is similar to ``make test``, but uses the ``--slow-ci``
1343+
option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
13571344

1358-
make regen-all
1359-
^^^^^^^^^^^^^^
1345+
.. make-target:: make regen-all
13601346

1361-
Regenerate (almost) all generated files. These include (but are not
1362-
limited to) bytecode cases, and parser generator file.
1363-
``make regen-stdlib-module-names`` and ``autoconf`` must be run
1364-
separately for the remaining `generated files <#generated-files>`_.
1347+
Regenerate (almost) all generated files. These include (but are not
1348+
limited to) bytecode cases, and parser generator files. See
1349+
:ref:`generated-files` for the targets that must be run separately.
13651350

13661351

13671352
C extensions
@@ -1381,23 +1366,23 @@ Built-in modules have no ``__file__`` attribute:
13811366
File "<stdin>", line 1, in <module>
13821367
AttributeError: module 'sys' has no attribute '__file__'
13831368
1384-
Other C extensions are built as dynamic libraries, like the ``_asyncio`` module.
1369+
Other C extensions are built as dynamic libraries, like the ``_zoneinfo`` module.
13851370
They are built with the ``Py_BUILD_CORE_MODULE`` macro defined.
1386-
Example on Linux x86-64:
1371+
For example on Linux x86-64:
13871372

13881373
.. code-block:: pycon
13891374
1390-
>>> import _asyncio
1391-
>>> _asyncio
1392-
<module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
1393-
>>> _asyncio.__file__
1394-
'/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'
1375+
>>> import _zoneinfo
1376+
>>> _zoneinfo
1377+
<module '_zoneinfo' from '/.../lib.linux-x86_64-3.16/_zoneinfo.cpython-316d-x86_64-linux-gnu.so'>
1378+
>>> _zoneinfo.__file__
1379+
'/.../lib.linux-x86_64-3.16/_zoneinfo.cpython-316d-x86_64-linux-gnu.so'
13951380
13961381
:file:`Modules/Setup` is used to generate Makefile targets to build C extensions.
13971382
At the beginning of the files, C extensions are built as built-in modules.
13981383
Extensions defined after the ``*shared*`` marker are built as dynamic libraries.
13991384

1400-
The :c:macro:`!PyAPI_FUNC()`, :c:macro:`!PyAPI_DATA()` and
1385+
The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_DATA()` and
14011386
:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/exports.h` are defined
14021387
differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:
14031388

‎Makefile.pre.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1904,6 +1904,7 @@ regen-unicodedata:
19041904
# Regenerate all generated files
19051905

19061906
# "clinic" is regenerated implicitly via "regen-global-objects".
1907+
# Keep the list of targets to run manually in sync with Doc/using/configure.rst.
19071908
.PHONY: regen-all
19081909
regen-all: regen-cases regen-typeslots \
19091910
regen-token regen-ast regen-keyword regen-sre regen-frozen \

0 commit comments

Comments
 (0)