| 1 |
**************** |
| 2 |
Configure Python |
| 3 |
**************** |
| 4 |
|
| 5 |
.. highlight:: sh |
| 6 |
|
| 7 |
Build Requirements |
| 8 |
================== |
| 9 |
|
| 10 |
Features and minimum versions required to build CPython: |
| 11 |
|
| 12 |
* A `C11 <https://en.cppreference.com/w/c/11>`_ compiler. `Optional C11 |
| 13 |
features |
| 14 |
<https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features>`_ |
| 15 |
are not required. |
| 16 |
|
| 17 |
* On Windows, Microsoft Visual Studio 2017 or later is required. |
| 18 |
|
| 19 |
* Support for `IEEE 754 <https://en.wikipedia.org/wiki/IEEE_754>`_ |
| 20 |
floating-point numbers and `floating-point Not-a-Number (NaN) |
| 21 |
<https://en.wikipedia.org/wiki/NaN#Floating_point>`_. |
| 22 |
|
| 23 |
* Support for threads. |
| 24 |
|
| 25 |
* OpenSSL 1.1.1 is the minimum version and OpenSSL 3.0.18 is the recommended |
| 26 |
minimum version for the :mod:`ssl` and :mod:`hashlib` extension modules. |
| 27 |
|
| 28 |
* SQLite 3.15.2 for the :mod:`sqlite3` extension module. |
| 29 |
|
| 30 |
* Tcl/Tk 8.5.12 for the :mod:`tkinter` module. |
| 31 |
|
| 32 |
* `libmpdec <https://www.bytereef.org/mpdecimal/doc/libmpdec/>`_ 2.5.0 |
| 33 |
for the :mod:`decimal` module. |
| 34 |
|
| 35 |
* Autoconf 2.71 and aclocal 1.16.5 are required to regenerate the |
| 36 |
:file:`configure` script. |
| 37 |
|
| 38 |
.. versionchanged:: 3.1 |
| 39 |
Tcl/Tk version 8.3.1 is now required. |
| 40 |
|
| 41 |
.. versionchanged:: 3.5 |
| 42 |
On Windows, Visual Studio 2015 or later is now required. |
| 43 |
Tcl/Tk version 8.4 is now required. |
| 44 |
|
| 45 |
.. versionchanged:: 3.6 |
| 46 |
Selected C99 features are now required, like ``<stdint.h>`` and ``static |
| 47 |
inline`` functions. |
| 48 |
|
| 49 |
.. versionchanged:: 3.7 |
| 50 |
Thread support and OpenSSL 1.0.2 are now required. |
| 51 |
|
| 52 |
.. versionchanged:: 3.10 |
| 53 |
OpenSSL 1.1.1 is now required. |
| 54 |
Require SQLite 3.7.15. |
| 55 |
|
| 56 |
.. versionchanged:: 3.11 |
| 57 |
C11 compiler, IEEE 754 and NaN support are now required. |
| 58 |
On Windows, Visual Studio 2017 or later is required. |
| 59 |
Tcl/Tk version 8.5.12 is now required for the :mod:`tkinter` module. |
| 60 |
|
| 61 |
.. versionchanged:: 3.13 |
| 62 |
Autoconf 2.71, aclocal 1.16.5 and SQLite 3.15.2 are now required. |
| 63 |
|
| 64 |
See also :pep:`7` "Style Guide for C Code" and :pep:`11` "CPython platform |
| 65 |
support". |
| 66 |
|
| 67 |
|
| 68 |
Generated files |
| 69 |
=============== |
| 70 |
|
| 71 |
To reduce build dependencies, Python source code contains multiple generated |
| 72 |
files. Commands to regenerate all generated files:: |
| 73 |
|
| 74 |
make regen-all |
| 75 |
make regen-stdlib-module-names |
| 76 |
make regen-limited-abi |
| 77 |
make regen-configure |
| 78 |
|
| 79 |
The ``Makefile.pre.in`` file documents generated files, their inputs, and tools used |
| 80 |
to regenerate them. Search for ``regen-*`` make targets. |
| 81 |
|
| 82 |
configure script |
| 83 |
---------------- |
| 84 |
|
| 85 |
The ``make regen-configure`` command regenerates the ``aclocal.m4`` file and |
| 86 |
the ``configure`` script using the ``Tools/build/regen-configure.sh`` shell |
| 87 |
script which uses an Ubuntu container to get the same tools versions and have a |
| 88 |
reproducible output. |
| 89 |
|
| 90 |
The container is optional, the following command can be run locally:: |
| 91 |
|
| 92 |
autoreconf -ivf -Werror |
| 93 |
|
| 94 |
The generated files can change depending on the exact ``autoconf-archive``, |
| 95 |
``aclocal`` and ``pkg-config`` versions. |
| 96 |
|
| 97 |
|
| 98 |
.. _configure-options: |
| 99 |
|
| 100 |
Configure Options |
| 101 |
================= |
| 102 |
|
| 103 |
List all :file:`configure` script options using:: |
| 104 |
|
| 105 |
./configure --help |
| 106 |
|
| 107 |
See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution. |
| 108 |
|
| 109 |
General Options |
| 110 |
--------------- |
| 111 |
|
| 112 |
.. option:: --enable-loadable-sqlite-extensions |
| 113 |
|
| 114 |
Support loadable extensions in the :mod:`!_sqlite` extension module (default |
| 115 |
is no) of the :mod:`sqlite3` module. |
| 116 |
|
| 117 |
See the :meth:`sqlite3.Connection.enable_load_extension` method of the |
| 118 |
:mod:`sqlite3` module. |
| 119 |
|
| 120 |
.. versionadded:: 3.6 |
| 121 |
|
| 122 |
.. option:: --disable-ipv6 |
| 123 |
|
| 124 |
Disable IPv6 support (enabled by default if supported), see the |
| 125 |
:mod:`socket` module. |
| 126 |
|
| 127 |
.. option:: --enable-big-digits=[15|30] |
| 128 |
|
| 129 |
Define the size in bits of Python :class:`int` digits: 15 or 30 bits. |
| 130 |
|
| 131 |
By default, the digit size is 30. |
| 132 |
|
| 133 |
Define the ``PYLONG_BITS_IN_DIGIT`` to ``15`` or ``30``. |
| 134 |
|
| 135 |
See :data:`sys.int_info.bits_per_digit <sys.int_info>`. |
| 136 |
|
| 137 |
.. option:: --with-suffix=SUFFIX |
| 138 |
|
| 139 |
Set the Python executable suffix to *SUFFIX*. |
| 140 |
|
| 141 |
The default suffix is ``.exe`` on Windows and macOS (``python.exe`` |
| 142 |
executable), ``.js`` on Emscripten node, ``.html`` on Emscripten browser, |
| 143 |
``.wasm`` on WASI, and an empty string on other platforms (``python`` |
| 144 |
executable). |
| 145 |
|
| 146 |
.. versionchanged:: 3.11 |
| 147 |
The default suffix on WASM platform is one of ``.js``, ``.html`` |
| 148 |
or ``.wasm``. |
| 149 |
|
| 150 |
.. option:: --with-tzpath=<list of absolute paths separated by pathsep> |
| 151 |
|
| 152 |
Select the default time zone search path for :const:`zoneinfo.TZPATH`. |
| 153 |
See the :ref:`Compile-time configuration |
| 154 |
<zoneinfo_data_compile_time_config>` of the :mod:`zoneinfo` module. |
| 155 |
|
| 156 |
Default: ``/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo``. |
| 157 |
|
| 158 |
See :data:`os.pathsep` path separator. |
| 159 |
|
| 160 |
.. versionadded:: 3.9 |
| 161 |
|
| 162 |
.. option:: --without-decimal-contextvar |
| 163 |
|
| 164 |
Build the ``_decimal`` extension module using a thread-local context rather |
| 165 |
than a coroutine-local context (default), see the :mod:`decimal` module. |
| 166 |
|
| 167 |
See :const:`decimal.HAVE_CONTEXTVAR` and the :mod:`contextvars` module. |
| 168 |
|
| 169 |
.. versionadded:: 3.9 |
| 170 |
|
| 171 |
.. option:: --with-dbmliborder=<list of backend names> |
| 172 |
|
| 173 |
Override order to check db backends for the :mod:`dbm` module |
| 174 |
|
| 175 |
A valid value is a colon (``:``) separated string with the backend names: |
| 176 |
|
| 177 |
* ``ndbm``; |
| 178 |
* ``gdbm``; |
| 179 |
* ``bdb``. |
| 180 |
|
| 181 |
.. option:: --without-c-locale-coercion |
| 182 |
|
| 183 |
Disable C locale coercion to a UTF-8 based locale (enabled by default). |
| 184 |
|
| 185 |
Don't define the ``PY_COERCE_C_LOCALE`` macro. |
| 186 |
|
| 187 |
See :envvar:`PYTHONCOERCECLOCALE` and the :pep:`538`. |
| 188 |
|
| 189 |
.. option:: --without-freelists |
| 190 |
|
| 191 |
Disable all freelists except the empty tuple singleton. |
| 192 |
|
| 193 |
.. versionadded:: 3.11 |
| 194 |
|
| 195 |
.. option:: --with-platlibdir=DIRNAME |
| 196 |
|
| 197 |
Python library directory name (default is ``lib``). |
| 198 |
|
| 199 |
Fedora and SuSE use ``lib64`` on 64-bit platforms. |
| 200 |
|
| 201 |
See :data:`sys.platlibdir`. |
| 202 |
|
| 203 |
.. versionadded:: 3.9 |
| 204 |
|
| 205 |
.. option:: --with-wheel-pkg-dir=PATH |
| 206 |
|
| 207 |
Directory of wheel packages used by the :mod:`ensurepip` module |
| 208 |
(none by default). |
| 209 |
|
| 210 |
Some Linux distribution packaging policies recommend against bundling |
| 211 |
dependencies. For example, Fedora installs wheel packages in the |
| 212 |
``/usr/share/python-wheels/`` directory and don't install the |
| 213 |
:mod:`!ensurepip._bundled` package. |
| 214 |
|
| 215 |
.. versionadded:: 3.10 |
| 216 |
|
| 217 |
.. option:: --with-pkg-config=[check|yes|no] |
| 218 |
|
| 219 |
Whether configure should use :program:`pkg-config` to detect build |
| 220 |
dependencies. |
| 221 |
|
| 222 |
* ``check`` (default): :program:`pkg-config` is optional |
| 223 |
* ``yes``: :program:`pkg-config` is mandatory |
| 224 |
* ``no``: configure does not use :program:`pkg-config` even when present |
| 225 |
|
| 226 |
.. versionadded:: 3.11 |
| 227 |
|
| 228 |
.. option:: --enable-pystats |
| 229 |
|
| 230 |
Turn on internal Python performance statistics gathering. |
| 231 |
|
| 232 |
By default, statistics gathering is off. Use ``python3 -X pystats`` command |
| 233 |
or set ``PYTHONSTATS=1`` environment variable to turn on statistics |
| 234 |
gathering at Python startup. |
| 235 |
|
| 236 |
At Python exit, dump statistics if statistics gathering was on and not |
| 237 |
cleared. |
| 238 |
|
| 239 |
Effects: |
| 240 |
|
| 241 |
* Add :option:`-X pystats <-X>` command line option. |
| 242 |
* Add :envvar:`!PYTHONSTATS` environment variable. |
| 243 |
* Define the ``Py_STATS`` macro. |
| 244 |
* Add functions to the :mod:`sys` module: |
| 245 |
|
| 246 |
* :func:`!sys._stats_on`: Turns on statistics gathering. |
| 247 |
* :func:`!sys._stats_off`: Turns off statistics gathering. |
| 248 |
* :func:`!sys._stats_clear`: Clears the statistics. |
| 249 |
* :func:`!sys._stats_dump`: Dump statistics to file, and clears the statistics. |
| 250 |
|
| 251 |
The statistics will be dumped to a arbitrary (probably unique) file in |
| 252 |
``/tmp/py_stats/`` (Unix) or ``C:\temp\py_stats\`` (Windows). If that |
| 253 |
directory does not exist, results will be printed on stderr. |
| 254 |
|
| 255 |
Use ``Tools/scripts/summarize_stats.py`` to read the stats. |
| 256 |
|
| 257 |
Statistics: |
| 258 |
|
| 259 |
* Opcode: |
| 260 |
|
| 261 |
* Specialization: success, failure, hit, deferred, miss, deopt, failures; |
| 262 |
* Execution count; |
| 263 |
* Pair count. |
| 264 |
|
| 265 |
* Call: |
| 266 |
|
| 267 |
* Inlined Python calls; |
| 268 |
* PyEval calls; |
| 269 |
* Frames pushed; |
| 270 |
* Frame object created; |
| 271 |
* Eval calls: vector, generator, legacy, function VECTORCALL, build class, |
| 272 |
slot, function "ex", API, method. |
| 273 |
|
| 274 |
* Object: |
| 275 |
|
| 276 |
* incref and decref; |
| 277 |
* interpreter incref and decref; |
| 278 |
* allocations: all, 512 bytes, 4 kiB, big; |
| 279 |
* free; |
| 280 |
* to/from free lists; |
| 281 |
* dictionary materialized/dematerialized; |
| 282 |
* type cache; |
| 283 |
* optimization attempts; |
| 284 |
* optimization traces created/executed; |
| 285 |
* uops executed. |
| 286 |
|
| 287 |
* Garbage collector: |
| 288 |
|
| 289 |
* Garbage collections; |
| 290 |
* Objects visited; |
| 291 |
* Objects collected. |
| 292 |
|
| 293 |
.. versionadded:: 3.11 |
| 294 |
|
| 295 |
.. _free-threading-build: |
| 296 |
|
| 297 |
.. option:: --disable-gil |
| 298 |
|
| 299 |
Enables **experimental** support for running Python without the |
| 300 |
:term:`global interpreter lock` (GIL): free threading build. |
| 301 |
|
| 302 |
Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to |
| 303 |
:data:`sys.abiflags`. |
| 304 |
|
| 305 |
See :ref:`whatsnew313-free-threaded-cpython` for more detail. |
| 306 |
|
| 307 |
.. versionadded:: 3.13 |
| 308 |
|
| 309 |
.. option:: --enable-experimental-jit=[no|yes|yes-off|interpreter] |
| 310 |
|
| 311 |
Indicate how to integrate the :ref:`JIT compiler <whatsnew313-jit-compiler>`. |
| 312 |
|
| 313 |
* ``no`` - build the interpreter without the JIT. |
| 314 |
* ``yes`` - build the interpreter with the JIT. |
| 315 |
* ``yes-off`` - build the interpreter with the JIT but disable it by default. |
| 316 |
* ``interpreter`` - build the interpreter without the JIT, but with the tier 2 enabled interpreter. |
| 317 |
|
| 318 |
By convention, ``--enable-experimental-jit`` is a shorthand for ``--enable-experimental-jit=yes``. |
| 319 |
|
| 320 |
.. note:: |
| 321 |
|
| 322 |
When building CPython with JIT enabled, ensure that your system has Python 3.11 or later installed. |
| 323 |
|
| 324 |
.. versionadded:: 3.13 |
| 325 |
|
| 326 |
.. option:: PKG_CONFIG |
| 327 |
|
| 328 |
Path to ``pkg-config`` utility. |
| 329 |
|
| 330 |
.. option:: PKG_CONFIG_LIBDIR |
| 331 |
.. option:: PKG_CONFIG_PATH |
| 332 |
|
| 333 |
``pkg-config`` options. |
| 334 |
|
| 335 |
|
| 336 |
C compiler options |
| 337 |
------------------ |
| 338 |
|
| 339 |
.. option:: CC |
| 340 |
|
| 341 |
C compiler command. |
| 342 |
|
| 343 |
.. option:: CFLAGS |
| 344 |
|
| 345 |
C compiler flags. |
| 346 |
|
| 347 |
.. option:: CPP |
| 348 |
|
| 349 |
C preprocessor command. |
| 350 |
|
| 351 |
.. option:: CPPFLAGS |
| 352 |
|
| 353 |
C preprocessor flags, e.g. :samp:`-I{include_dir}`. |
| 354 |
|
| 355 |
|
| 356 |
Linker options |
| 357 |
-------------- |
| 358 |
|
| 359 |
.. option:: LDFLAGS |
| 360 |
|
| 361 |
Linker flags, e.g. :samp:`-L{library_directory}`. |
| 362 |
|
| 363 |
.. option:: LIBS |
| 364 |
|
| 365 |
Libraries to pass to the linker, e.g. :samp:`-l{library}`. |
| 366 |
|
| 367 |
.. option:: MACHDEP |
| 368 |
|
| 369 |
Name for machine-dependent library files. |
| 370 |
|
| 371 |
|
| 372 |
Options for third-party dependencies |
| 373 |
------------------------------------ |
| 374 |
|
| 375 |
.. versionadded:: 3.11 |
| 376 |
|
| 377 |
.. option:: BZIP2_CFLAGS |
| 378 |
.. option:: BZIP2_LIBS |
| 379 |
|
| 380 |
C compiler and linker flags to link Python to ``libbz2``, used by :mod:`bz2` |
| 381 |
module, overriding ``pkg-config``. |
| 382 |
|
| 383 |
.. option:: CURSES_CFLAGS |
| 384 |
.. option:: CURSES_LIBS |
| 385 |
|
| 386 |
C compiler and linker flags for ``libncurses`` or ``libncursesw``, used by |
| 387 |
:mod:`curses` module, overriding ``pkg-config``. |
| 388 |
|
| 389 |
.. option:: GDBM_CFLAGS |
| 390 |
.. option:: GDBM_LIBS |
| 391 |
|
| 392 |
C compiler and linker flags for ``gdbm``. |
| 393 |
|
| 394 |
.. option:: LIBB2_CFLAGS |
| 395 |
.. option:: LIBB2_LIBS |
| 396 |
|
| 397 |
C compiler and linker flags for ``libb2`` (:ref:`BLAKE2 <hashlib-blake2>`), |
| 398 |
used by :mod:`hashlib` module, overriding ``pkg-config``. |
| 399 |
|
| 400 |
.. option:: LIBEDIT_CFLAGS |
| 401 |
.. option:: LIBEDIT_LIBS |
| 402 |
|
| 403 |
C compiler and linker flags for ``libedit``, used by :mod:`readline` module, |
| 404 |
overriding ``pkg-config``. |
| 405 |
|
| 406 |
.. option:: LIBFFI_CFLAGS |
| 407 |
.. option:: LIBFFI_LIBS |
| 408 |
|
| 409 |
C compiler and linker flags for ``libffi``, used by :mod:`ctypes` module, |
| 410 |
overriding ``pkg-config``. |
| 411 |
|
| 412 |
.. option:: LIBMPDEC_CFLAGS |
| 413 |
.. option:: LIBMPDEC_LIBS |
| 414 |
|
| 415 |
C compiler and linker flags for ``libmpdec``, used by :mod:`decimal` module, |
| 416 |
overriding ``pkg-config``. |
| 417 |
|
| 418 |
.. note:: |
| 419 |
|
| 420 |
These environment variables have no effect unless |
| 421 |
:option:`--with-system-libmpdec` is specified. |
| 422 |
|
| 423 |
.. option:: LIBLZMA_CFLAGS |
| 424 |
.. option:: LIBLZMA_LIBS |
| 425 |
|
| 426 |
C compiler and linker flags for ``liblzma``, used by :mod:`lzma` module, |
| 427 |
overriding ``pkg-config``. |
| 428 |
|
| 429 |
.. option:: LIBREADLINE_CFLAGS |
| 430 |
.. option:: LIBREADLINE_LIBS |
| 431 |
|
| 432 |
C compiler and linker flags for ``libreadline``, used by :mod:`readline` |
| 433 |
module, overriding ``pkg-config``. |
| 434 |
|
| 435 |
.. option:: LIBSQLITE3_CFLAGS |
| 436 |
.. option:: LIBSQLITE3_LIBS |
| 437 |
|
| 438 |
C compiler and linker flags for ``libsqlite3``, used by :mod:`sqlite3` |
| 439 |
module, overriding ``pkg-config``. |
| 440 |
|
| 441 |
.. option:: LIBUUID_CFLAGS |
| 442 |
.. option:: LIBUUID_LIBS |
| 443 |
|
| 444 |
C compiler and linker flags for ``libuuid``, used by :mod:`uuid` module, |
| 445 |
overriding ``pkg-config``. |
| 446 |
|
| 447 |
.. option:: PANEL_CFLAGS |
| 448 |
.. option:: PANEL_LIBS |
| 449 |
|
| 450 |
C compiler and linker flags for PANEL, overriding ``pkg-config``. |
| 451 |
|
| 452 |
C compiler and linker flags for ``libpanel`` or ``libpanelw``, used by |
| 453 |
:mod:`curses.panel` module, overriding ``pkg-config``. |
| 454 |
|
| 455 |
.. option:: TCLTK_CFLAGS |
| 456 |
.. option:: TCLTK_LIBS |
| 457 |
|
| 458 |
C compiler and linker flags for TCLTK, overriding ``pkg-config``. |
| 459 |
|
| 460 |
.. option:: ZLIB_CFLAGS |
| 461 |
.. option:: ZLIB_LIBS |
| 462 |
|
| 463 |
C compiler and linker flags for ``libzlib``, used by :mod:`gzip` module, |
| 464 |
overriding ``pkg-config``. |
| 465 |
|
| 466 |
|
| 467 |
WebAssembly Options |
| 468 |
------------------- |
| 469 |
|
| 470 |
.. option:: --with-emscripten-target=[browser|node] |
| 471 |
|
| 472 |
Set build flavor for ``wasm32-emscripten``. |
| 473 |
|
| 474 |
* ``browser`` (default): preload minimal stdlib, default MEMFS. |
| 475 |
* ``node``: NODERAWFS and pthread support. |
| 476 |
|
| 477 |
.. versionadded:: 3.11 |
| 478 |
|
| 479 |
.. option:: --enable-wasm-dynamic-linking |
| 480 |
|
| 481 |
Turn on dynamic linking support for WASM. |
| 482 |
|
| 483 |
Dynamic linking enables ``dlopen``. File size of the executable |
| 484 |
increases due to limited dead code elimination and additional features. |
| 485 |
|
| 486 |
.. versionadded:: 3.11 |
| 487 |
|
| 488 |
.. option:: --enable-wasm-pthreads |
| 489 |
|
| 490 |
Turn on pthreads support for WASM. |
| 491 |
|
| 492 |
.. versionadded:: 3.11 |
| 493 |
|
| 494 |
|
| 495 |
Install Options |
| 496 |
--------------- |
| 497 |
|
| 498 |
.. option:: --prefix=PREFIX |
| 499 |
|
| 500 |
Install architecture-independent files in PREFIX. On Unix, it |
| 501 |
defaults to :file:`/usr/local`. |
| 502 |
|
| 503 |
This value can be retrieved at runtime using :data:`sys.prefix`. |
| 504 |
|
| 505 |
As an example, one can use ``--prefix="$HOME/.local/"`` to install |
| 506 |
a Python in its home directory. |
| 507 |
|
| 508 |
.. option:: --exec-prefix=EPREFIX |
| 509 |
|
| 510 |
Install architecture-dependent files in EPREFIX, defaults to :option:`--prefix`. |
| 511 |
|
| 512 |
This value can be retrieved at runtime using :data:`sys.exec_prefix`. |
| 513 |
|
| 514 |
.. option:: --disable-test-modules |
| 515 |
|
| 516 |
Don't build nor install test modules, like the :mod:`test` package or the |
| 517 |
:mod:`!_testcapi` extension module (built and installed by default). |
| 518 |
|
| 519 |
.. versionadded:: 3.10 |
| 520 |
|
| 521 |
.. option:: --with-ensurepip=[upgrade|install|no] |
| 522 |
|
| 523 |
Select the :mod:`ensurepip` command run on Python installation: |
| 524 |
|
| 525 |
* ``upgrade`` (default): run ``python -m ensurepip --altinstall --upgrade`` |
| 526 |
command. |
| 527 |
* ``install``: run ``python -m ensurepip --altinstall`` command; |
| 528 |
* ``no``: don't run ensurepip; |
| 529 |
|
| 530 |
.. versionadded:: 3.6 |
| 531 |
|
| 532 |
|
| 533 |
Performance options |
| 534 |
------------------- |
| 535 |
|
| 536 |
Configuring Python using ``--enable-optimizations --with-lto`` (PGO + LTO) is |
| 537 |
recommended for best performance. The experimental ``--enable-bolt`` flag can |
| 538 |
also be used to improve performance. |
| 539 |
|
| 540 |
.. option:: --enable-optimizations |
| 541 |
|
| 542 |
Enable Profile Guided Optimization (PGO) using :envvar:`PROFILE_TASK` |
| 543 |
(disabled by default). |
| 544 |
|
| 545 |
The C compiler Clang requires ``llvm-profdata`` program for PGO. On |
| 546 |
macOS, GCC also requires it: GCC is just an alias to Clang on macOS. |
| 547 |
|
| 548 |
Disable also semantic interposition in libpython if ``--enable-shared`` and |
| 549 |
GCC is used: add ``-fno-semantic-interposition`` to the compiler and linker |
| 550 |
flags. |
| 551 |
|
| 552 |
.. note:: |
| 553 |
|
| 554 |
During the build, you may encounter compiler warnings about |
| 555 |
profile data not being available for some source files. |
| 556 |
These warnings are harmless, as only a subset of the code is exercised |
| 557 |
during profile data acquisition. |
| 558 |
To disable these warnings on Clang, manually suppress them by adding |
| 559 |
``-Wno-profile-instr-unprofiled`` to :envvar:`CFLAGS`. |
| 560 |
|
| 561 |
.. versionadded:: 3.6 |
| 562 |
|
| 563 |
.. versionchanged:: 3.10 |
| 564 |
Use ``-fno-semantic-interposition`` on GCC. |
| 565 |
|
| 566 |
.. envvar:: PROFILE_TASK |
| 567 |
|
| 568 |
Environment variable used in the Makefile: Python command line arguments for |
| 569 |
the PGO generation task. |
| 570 |
|
| 571 |
Default: ``-m test --pgo --timeout=$(TESTTIMEOUT)``. |
| 572 |
|
| 573 |
.. versionadded:: 3.8 |
| 574 |
|
| 575 |
.. versionchanged:: 3.13 |
| 576 |
Task failure is no longer ignored silently. |
| 577 |
|
| 578 |
.. option:: --with-lto=[full|thin|no|yes] |
| 579 |
|
| 580 |
Enable Link Time Optimization (LTO) in any build (disabled by default). |
| 581 |
|
| 582 |
The C compiler Clang requires ``llvm-ar`` for LTO (``ar`` on macOS), as well |
| 583 |
as an LTO-aware linker (``ld.gold`` or ``lld``). |
| 584 |
|
| 585 |
.. versionadded:: 3.6 |
| 586 |
|
| 587 |
.. versionadded:: 3.11 |
| 588 |
To use ThinLTO feature, use ``--with-lto=thin`` on Clang. |
| 589 |
|
| 590 |
.. versionchanged:: 3.12 |
| 591 |
Use ThinLTO as the default optimization policy on Clang if the compiler accepts the flag. |
| 592 |
|
| 593 |
.. option:: --enable-bolt |
| 594 |
|
| 595 |
Enable usage of the `BOLT post-link binary optimizer |
| 596 |
<https://github.com/llvm/llvm-project/tree/main/bolt>`_ (disabled by |
| 597 |
default). |
| 598 |
|
| 599 |
BOLT is part of the LLVM project but is not always included in their binary |
| 600 |
distributions. This flag requires that ``llvm-bolt`` and ``merge-fdata`` |
| 601 |
are available. |
| 602 |
|
| 603 |
BOLT is still a fairly new project so this flag should be considered |
| 604 |
experimental for now. Because this tool operates on machine code its success |
| 605 |
is dependent on a combination of the build environment + the other |
| 606 |
optimization configure args + the CPU architecture, and not all combinations |
| 607 |
are supported. |
| 608 |
BOLT versions before LLVM 16 are known to crash BOLT under some scenarios. |
| 609 |
Use of LLVM 16 or newer for BOLT optimization is strongly encouraged. |
| 610 |
|
| 611 |
The :envvar:`!BOLT_INSTRUMENT_FLAGS` and :envvar:`!BOLT_APPLY_FLAGS` |
| 612 |
:program:`configure` variables can be defined to override the default set of |
| 613 |
arguments for :program:`llvm-bolt` to instrument and apply BOLT data to |
| 614 |
binaries, respectively. |
| 615 |
|
| 616 |
.. versionadded:: 3.12 |
| 617 |
|
| 618 |
.. option:: BOLT_APPLY_FLAGS |
| 619 |
|
| 620 |
Arguments to ``llvm-bolt`` when creating a `BOLT optimized binary |
| 621 |
<https://github.com/facebookarchive/BOLT>`_. |
| 622 |
|
| 623 |
.. versionadded:: 3.12 |
| 624 |
|
| 625 |
.. option:: BOLT_INSTRUMENT_FLAGS |
| 626 |
|
| 627 |
Arguments to ``llvm-bolt`` when instrumenting binaries. |
| 628 |
|
| 629 |
.. versionadded:: 3.12 |
| 630 |
|
| 631 |
.. option:: --with-computed-gotos |
| 632 |
|
| 633 |
Enable computed gotos in evaluation loop (enabled by default on supported |
| 634 |
compilers). |
| 635 |
|
| 636 |
.. option:: --without-mimalloc |
| 637 |
|
| 638 |
Disable the fast :ref:`mimalloc <mimalloc>` allocator |
| 639 |
(enabled by default). |
| 640 |
|
| 641 |
See also :envvar:`PYTHONMALLOC` environment variable. |
| 642 |
|
| 643 |
.. option:: --without-pymalloc |
| 644 |
|
| 645 |
Disable the specialized Python memory allocator :ref:`pymalloc <pymalloc>` |
| 646 |
(enabled by default). |
| 647 |
|
| 648 |
See also :envvar:`PYTHONMALLOC` environment variable. |
| 649 |
|
| 650 |
.. option:: --without-doc-strings |
| 651 |
|
| 652 |
Disable static documentation strings to reduce the memory footprint (enabled |
| 653 |
by default). Documentation strings defined in Python are not affected. |
| 654 |
|
| 655 |
Don't define the ``WITH_DOC_STRINGS`` macro. |
| 656 |
|
| 657 |
See the ``PyDoc_STRVAR()`` macro. |
| 658 |
|
| 659 |
.. option:: --enable-profiling |
| 660 |
|
| 661 |
Enable C-level code profiling with ``gprof`` (disabled by default). |
| 662 |
|
| 663 |
.. option:: --with-strict-overflow |
| 664 |
|
| 665 |
Add ``-fstrict-overflow`` to the C compiler flags (by default we add |
| 666 |
``-fno-strict-overflow`` instead). |
| 667 |
|
| 668 |
|
| 669 |
.. _debug-build: |
| 670 |
|
| 671 |
Python Debug Build |
| 672 |
------------------ |
| 673 |
|
| 674 |
A debug build is Python built with the :option:`--with-pydebug` configure |
| 675 |
option. |
| 676 |
|
| 677 |
Effects of a debug build: |
| 678 |
|
| 679 |
* Display all warnings by default: the list of default warning filters is empty |
| 680 |
in the :mod:`warnings` module. |
| 681 |
* Add ``d`` to :data:`sys.abiflags`. |
| 682 |
* Add :func:`!sys.gettotalrefcount` function. |
| 683 |
* Add :option:`-X showrefcount <-X>` command line option. |
| 684 |
* Add :option:`-d` command line option and :envvar:`PYTHONDEBUG` environment |
| 685 |
variable to debug the parser. |
| 686 |
* Add support for the ``__lltrace__`` variable: enable low-level tracing in the |
| 687 |
bytecode evaluation loop if the variable is defined. |
| 688 |
* Install :ref:`debug hooks on memory allocators <default-memory-allocators>` |
| 689 |
to detect buffer overflow and other memory errors. |
| 690 |
* Define ``Py_DEBUG`` and ``Py_REF_DEBUG`` macros. |
| 691 |
* Add runtime checks: code surrounded by ``#ifdef Py_DEBUG`` and ``#endif``. |
| 692 |
Enable ``assert(...)`` and ``_PyObject_ASSERT(...)`` assertions: don't set |
| 693 |
the ``NDEBUG`` macro (see also the :option:`--with-assertions` configure |
| 694 |
option). Main runtime checks: |
| 695 |
|
| 696 |
* Add sanity checks on the function arguments. |
| 697 |
* Unicode and int objects are created with their memory filled with a pattern |
| 698 |
to detect usage of uninitialized objects. |
| 699 |
* Ensure that functions which can clear or replace the current exception are |
| 700 |
not called with an exception raised. |
| 701 |
* Check that deallocator functions don't change the current exception. |
| 702 |
* The garbage collector (:func:`gc.collect` function) runs some basic checks |
| 703 |
on objects consistency. |
| 704 |
* The :c:macro:`!Py_SAFE_DOWNCAST()` macro checks for integer underflow and |
| 705 |
overflow when downcasting from wide types to narrow types. |
| 706 |
|
| 707 |
See also the :ref:`Python Development Mode <devmode>` and the |
| 708 |
:option:`--with-trace-refs` configure option. |
| 709 |
|
| 710 |
.. versionchanged:: 3.8 |
| 711 |
Release builds are now ABI compatible with debug builds: defining the |
| 712 |
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro (see the |
| 713 |
:option:`--with-trace-refs` option). However, debug builds still expose |
| 714 |
more symbols than release builds and code built against a debug build is not |
| 715 |
necessarily compatible with a release build. |
| 716 |
|
| 717 |
|
| 718 |
Debug options |
| 719 |
------------- |
| 720 |
|
| 721 |
.. option:: --with-pydebug |
| 722 |
|
| 723 |
:ref:`Build Python in debug mode <debug-build>`: define the ``Py_DEBUG`` |
| 724 |
macro (disabled by default). |
| 725 |
|
| 726 |
.. option:: --with-trace-refs |
| 727 |
|
| 728 |
Enable tracing references for debugging purpose (disabled by default). |
| 729 |
|
| 730 |
Effects: |
| 731 |
|
| 732 |
* Define the ``Py_TRACE_REFS`` macro. |
| 733 |
* Add :func:`sys.getobjects` function. |
| 734 |
* Add :envvar:`PYTHONDUMPREFS` environment variable. |
| 735 |
|
| 736 |
The :envvar:`PYTHONDUMPREFS` environment variable can be used to dump |
| 737 |
objects and reference counts still alive at Python exit. |
| 738 |
|
| 739 |
:ref:`Statically allocated objects <static-types>` are not traced. |
| 740 |
|
| 741 |
.. versionadded:: 3.8 |
| 742 |
|
| 743 |
.. versionchanged:: 3.13 |
| 744 |
This build is now ABI compatible with release build and :ref:`debug build |
| 745 |
<debug-build>`. |
| 746 |
|
| 747 |
.. option:: --with-assertions |
| 748 |
|
| 749 |
Build with C assertions enabled (default is no): ``assert(...);`` and |
| 750 |
``_PyObject_ASSERT(...);``. |
| 751 |
|
| 752 |
If set, the ``NDEBUG`` macro is not defined in the :envvar:`OPT` compiler |
| 753 |
variable. |
| 754 |
|
| 755 |
See also the :option:`--with-pydebug` option (:ref:`debug build |
| 756 |
<debug-build>`) which also enables assertions. |
| 757 |
|
| 758 |
.. versionadded:: 3.6 |
| 759 |
|
| 760 |
.. option:: --with-valgrind |
| 761 |
|
| 762 |
Enable Valgrind support (default is no). |
| 763 |
|
| 764 |
.. option:: --with-dtrace |
| 765 |
|
| 766 |
Enable DTrace support (default is no). |
| 767 |
|
| 768 |
See :ref:`Instrumenting CPython with DTrace and SystemTap |
| 769 |
<instrumentation>`. |
| 770 |
|
| 771 |
.. versionadded:: 3.6 |
| 772 |
|
| 773 |
.. option:: --with-address-sanitizer |
| 774 |
|
| 775 |
Enable AddressSanitizer memory error detector, ``asan`` (default is no). |
| 776 |
To improve ASan detection capabilities you may also want to combine this |
| 777 |
with :option:`--without-pymalloc` to disable the specialized small-object |
| 778 |
allocator whose allocations are not tracked by ASan. |
| 779 |
|
| 780 |
.. versionadded:: 3.6 |
| 781 |
|
| 782 |
.. option:: --with-memory-sanitizer |
| 783 |
|
| 784 |
Enable MemorySanitizer allocation error detector, ``msan`` (default is no). |
| 785 |
|
| 786 |
.. versionadded:: 3.6 |
| 787 |
|
| 788 |
.. option:: --with-undefined-behavior-sanitizer |
| 789 |
|
| 790 |
Enable UndefinedBehaviorSanitizer undefined behaviour detector, ``ubsan`` |
| 791 |
(default is no). |
| 792 |
|
| 793 |
.. versionadded:: 3.6 |
| 794 |
|
| 795 |
.. option:: --with-thread-sanitizer |
| 796 |
|
| 797 |
Enable ThreadSanitizer data race detector, ``tsan`` |
| 798 |
(default is no). |
| 799 |
|
| 800 |
.. versionadded:: 3.13 |
| 801 |
|
| 802 |
|
| 803 |
Linker options |
| 804 |
-------------- |
| 805 |
|
| 806 |
.. option:: --enable-shared |
| 807 |
|
| 808 |
Enable building a shared Python library: ``libpython`` (default is no). |
| 809 |
|
| 810 |
.. option:: --without-static-libpython |
| 811 |
|
| 812 |
Do not build ``libpythonMAJOR.MINOR.a`` and do not install ``python.o`` |
| 813 |
(built and enabled by default). |
| 814 |
|
| 815 |
.. versionadded:: 3.10 |
| 816 |
|
| 817 |
|
| 818 |
Libraries options |
| 819 |
----------------- |
| 820 |
|
| 821 |
.. option:: --with-libs='lib1 ...' |
| 822 |
|
| 823 |
Link against additional libraries (default is no). |
| 824 |
|
| 825 |
.. option:: --with-system-expat |
| 826 |
|
| 827 |
Build the :mod:`!pyexpat` module using an installed ``expat`` library |
| 828 |
(default is no). |
| 829 |
|
| 830 |
.. option:: --with-system-libmpdec |
| 831 |
|
| 832 |
Build the ``_decimal`` extension module using an installed ``mpdecimal`` |
| 833 |
library, see the :mod:`decimal` module (default is yes). |
| 834 |
|
| 835 |
.. versionadded:: 3.3 |
| 836 |
|
| 837 |
.. versionchanged:: 3.13 |
| 838 |
Default to using the installed ``mpdecimal`` library. |
| 839 |
|
| 840 |
.. deprecated-removed:: 3.13 3.16 |
| 841 |
A copy of the ``mpdecimal`` library sources will no longer be distributed |
| 842 |
with Python 3.16. |
| 843 |
|
| 844 |
.. seealso:: :option:`LIBMPDEC_CFLAGS` and :option:`LIBMPDEC_LIBS`. |
| 845 |
|
| 846 |
.. option:: --with-readline=readline|editline |
| 847 |
|
| 848 |
Designate a backend library for the :mod:`readline` module. |
| 849 |
|
| 850 |
* readline: Use readline as the backend. |
| 851 |
* editline: Use editline as the backend. |
| 852 |
|
| 853 |
.. versionadded:: 3.10 |
| 854 |
|
| 855 |
.. option:: --without-readline |
| 856 |
|
| 857 |
Don't build the :mod:`readline` module (built by default). |
| 858 |
|
| 859 |
Don't define the ``HAVE_LIBREADLINE`` macro. |
| 860 |
|
| 861 |
.. versionadded:: 3.10 |
| 862 |
|
| 863 |
.. option:: --with-libm=STRING |
| 864 |
|
| 865 |
Override ``libm`` math library to *STRING* (default is system-dependent). |
| 866 |
|
| 867 |
.. option:: --with-libc=STRING |
| 868 |
|
| 869 |
Override ``libc`` C library to *STRING* (default is system-dependent). |
| 870 |
|
| 871 |
.. option:: --with-openssl=DIR |
| 872 |
|
| 873 |
Root of the OpenSSL directory. |
| 874 |
|
| 875 |
.. versionadded:: 3.7 |
| 876 |
|
| 877 |
.. option:: --with-openssl-rpath=[no|auto|DIR] |
| 878 |
|
| 879 |
Set runtime library directory (rpath) for OpenSSL libraries: |
| 880 |
|
| 881 |
* ``no`` (default): don't set rpath; |
| 882 |
* ``auto``: auto-detect rpath from :option:`--with-openssl` and |
| 883 |
``pkg-config``; |
| 884 |
* *DIR*: set an explicit rpath. |
| 885 |
|
| 886 |
.. versionadded:: 3.10 |
| 887 |
|
| 888 |
|
| 889 |
Security Options |
| 890 |
---------------- |
| 891 |
|
| 892 |
.. option:: --with-hash-algorithm=[fnv|siphash13|siphash24] |
| 893 |
|
| 894 |
Select hash algorithm for use in ``Python/pyhash.c``: |
| 895 |
|
| 896 |
* ``siphash13`` (default); |
| 897 |
* ``siphash24``; |
| 898 |
* ``fnv``. |
| 899 |
|
| 900 |
.. versionadded:: 3.4 |
| 901 |
|
| 902 |
.. versionadded:: 3.11 |
| 903 |
``siphash13`` is added and it is the new default. |
| 904 |
|
| 905 |
.. option:: --with-builtin-hashlib-hashes=md5,sha1,sha256,sha512,sha3,blake2 |
| 906 |
|
| 907 |
Built-in hash modules: |
| 908 |
|
| 909 |
* ``md5``; |
| 910 |
* ``sha1``; |
| 911 |
* ``sha256``; |
| 912 |
* ``sha512``; |
| 913 |
* ``sha3`` (with shake); |
| 914 |
* ``blake2``. |
| 915 |
|
| 916 |
.. versionadded:: 3.9 |
| 917 |
|
| 918 |
.. option:: --with-ssl-default-suites=[python|openssl|STRING] |
| 919 |
|
| 920 |
Override the OpenSSL default cipher suites string: |
| 921 |
|
| 922 |
* ``python`` (default): use Python's preferred selection; |
| 923 |
* ``openssl``: leave OpenSSL's defaults untouched; |
| 924 |
* *STRING*: use a custom string |
| 925 |
|
| 926 |
See the :mod:`ssl` module. |
| 927 |
|
| 928 |
.. versionadded:: 3.7 |
| 929 |
|
| 930 |
.. versionchanged:: 3.10 |
| 931 |
|
| 932 |
The settings ``python`` and *STRING* also set TLS 1.2 as minimum |
| 933 |
protocol version. |
| 934 |
|
| 935 |
macOS Options |
| 936 |
------------- |
| 937 |
|
| 938 |
See :source:`Mac/README.rst`. |
| 939 |
|
| 940 |
.. option:: --enable-universalsdk |
| 941 |
.. option:: --enable-universalsdk=SDKDIR |
| 942 |
|
| 943 |
Create a universal binary build. *SDKDIR* specifies which macOS SDK should |
| 944 |
be used to perform the build (default is no). |
| 945 |
|
| 946 |
.. option:: --enable-framework |
| 947 |
.. option:: --enable-framework=INSTALLDIR |
| 948 |
|
| 949 |
Create a Python.framework rather than a traditional Unix install. Optional |
| 950 |
*INSTALLDIR* specifies the installation path (default is no). |
| 951 |
|
| 952 |
.. option:: --with-universal-archs=ARCH |
| 953 |
|
| 954 |
Specify the kind of universal binary that should be created. This option is |
| 955 |
only valid when :option:`--enable-universalsdk` is set. |
| 956 |
|
| 957 |
Options: |
| 958 |
|
| 959 |
* ``universal2`` (x86-64 and arm64); |
| 960 |
* ``32-bit`` (PPC and i386); |
| 961 |
* ``64-bit`` (PPC64 and x86-64); |
| 962 |
* ``3-way`` (i386, PPC and x86-64); |
| 963 |
* ``intel`` (i386 and x86-64); |
| 964 |
* ``intel-32`` (i386); |
| 965 |
* ``intel-64`` (x86-64); |
| 966 |
* ``all`` (PPC, i386, PPC64 and x86-64). |
| 967 |
|
| 968 |
Note that values for this configuration item are *not* the same as the |
| 969 |
identifiers used for universal binary wheels on macOS. See the Python |
| 970 |
Packaging User Guide for details on the `packaging platform compatibility |
| 971 |
tags used on macOS |
| 972 |
<https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#macos>`_ |
| 973 |
|
| 974 |
.. option:: --with-framework-name=FRAMEWORK |
| 975 |
|
| 976 |
Specify the name for the python framework on macOS only valid when |
| 977 |
:option:`--enable-framework` is set (default: ``Python``). |
| 978 |
|
| 979 |
.. option:: --with-app-store-compliance |
| 980 |
.. option:: --with-app-store-compliance=PATCH-FILE |
| 981 |
|
| 982 |
The Python standard library contains strings that are known to trigger |
| 983 |
automated inspection tool errors when submitted for distribution by |
| 984 |
the macOS and iOS App Stores. If enabled, this option will apply the list of |
| 985 |
patches that are known to correct app store compliance. A custom patch |
| 986 |
file can also be specified. This option is disabled by default. |
| 987 |
|
| 988 |
.. versionadded:: 3.13 |
| 989 |
|
| 990 |
iOS Options |
| 991 |
----------- |
| 992 |
|
| 993 |
See :source:`iOS/README.rst`. |
| 994 |
|
| 995 |
.. option:: --enable-framework=INSTALLDIR |
| 996 |
|
| 997 |
Create a Python.framework. Unlike macOS, the *INSTALLDIR* argument |
| 998 |
specifying the installation path is mandatory. |
| 999 |
|
| 1000 |
.. option:: --with-framework-name=FRAMEWORK |
| 1001 |
|
| 1002 |
Specify the name for the framework (default: ``Python``). |
| 1003 |
|
| 1004 |
|
| 1005 |
Cross Compiling Options |
| 1006 |
----------------------- |
| 1007 |
|
| 1008 |
Cross compiling, also known as cross building, can be used to build Python |
| 1009 |
for another CPU architecture or platform. Cross compiling requires a Python |
| 1010 |
interpreter for the build platform. The version of the build Python must match |
| 1011 |
the version of the cross compiled host Python. |
| 1012 |
|
| 1013 |
.. option:: --build=BUILD |
| 1014 |
|
| 1015 |
configure for building on BUILD, usually guessed by :program:`config.guess`. |
| 1016 |
|
| 1017 |
.. option:: --host=HOST |
| 1018 |
|
| 1019 |
cross-compile to build programs to run on HOST (target platform) |
| 1020 |
|
| 1021 |
.. option:: --with-build-python=path/to/python |
| 1022 |
|
| 1023 |
path to build ``python`` binary for cross compiling |
| 1024 |
|
| 1025 |
.. versionadded:: 3.11 |
| 1026 |
|
| 1027 |
.. option:: CONFIG_SITE=file |
| 1028 |
|
| 1029 |
An environment variable that points to a file with configure overrides. |
| 1030 |
|
| 1031 |
Example *config.site* file: |
| 1032 |
|
| 1033 |
.. code-block:: ini |
| 1034 |
|
| 1035 |
# config.site-aarch64 |
| 1036 |
ac_cv_buggy_getaddrinfo=no |
| 1037 |
ac_cv_file__dev_ptmx=yes |
| 1038 |
ac_cv_file__dev_ptc=no |
| 1039 |
|
| 1040 |
.. option:: HOSTRUNNER |
| 1041 |
|
| 1042 |
Program to run CPython for the host platform for cross-compilation. |
| 1043 |
|
| 1044 |
.. versionadded:: 3.11 |
| 1045 |
|
| 1046 |
|
| 1047 |
Cross compiling example:: |
| 1048 |
|
| 1049 |
CONFIG_SITE=config.site-aarch64 ../configure \ |
| 1050 |
--build=x86_64-pc-linux-gnu \ |
| 1051 |
--host=aarch64-unknown-linux-gnu \ |
| 1052 |
--with-build-python=../x86_64/python |
| 1053 |
|
| 1054 |
|
| 1055 |
Python Build System |
| 1056 |
=================== |
| 1057 |
|
| 1058 |
Main files of the build system |
| 1059 |
------------------------------ |
| 1060 |
|
| 1061 |
* :file:`configure.ac` => :file:`configure`; |
| 1062 |
* :file:`Makefile.pre.in` => :file:`Makefile` (created by :file:`configure`); |
| 1063 |
* :file:`pyconfig.h` (created by :file:`configure`); |
| 1064 |
* :file:`Modules/Setup`: C extensions built by the Makefile using |
| 1065 |
:file:`Module/makesetup` shell script; |
| 1066 |
|
| 1067 |
Main build steps |
| 1068 |
---------------- |
| 1069 |
|
| 1070 |
* C files (``.c``) are built as object files (``.o``). |
| 1071 |
* A static ``libpython`` library (``.a``) is created from objects files. |
| 1072 |
* ``python.o`` and the static ``libpython`` library are linked into the |
| 1073 |
final ``python`` program. |
| 1074 |
* C extensions are built by the Makefile (see :file:`Modules/Setup`). |
| 1075 |
|
| 1076 |
Main Makefile targets |
| 1077 |
--------------------- |
| 1078 |
|
| 1079 |
make |
| 1080 |
^^^^ |
| 1081 |
|
| 1082 |
For the most part, when rebuilding after editing some code or |
| 1083 |
refreshing your checkout from upstream, all you need to do is execute |
| 1084 |
``make``, which (per Make's semantics) builds the default target, the |
| 1085 |
first one defined in the Makefile. By tradition (including in the |
| 1086 |
CPython project) this is usually the ``all`` target. The |
| 1087 |
``configure`` script expands an ``autoconf`` variable, |
| 1088 |
``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make |
| 1089 |
all`` will build. The three choices are: |
| 1090 |
|
| 1091 |
* ``profile-opt`` (configured with ``--enable-optimizations``) |
| 1092 |
* ``build_wasm`` (configured with ``--with-emscripten-target``) |
| 1093 |
* ``build_all`` (configured without explicitly using either of the others) |
| 1094 |
|
| 1095 |
Depending on the most recent source file changes, Make will rebuild |
| 1096 |
any targets (object files and executables) deemed out-of-date, |
| 1097 |
including running ``configure`` again if necessary. Source/target |
| 1098 |
dependencies are many and maintained manually however, so Make |
| 1099 |
sometimes doesn't have all the information necessary to correctly |
| 1100 |
detect all targets which need to be rebuilt. Depending on which |
| 1101 |
targets aren't rebuilt, you might experience a number of problems. If |
| 1102 |
you have build or test problems which you can't otherwise explain, |
| 1103 |
``make clean && make`` should work around most dependency problems, at |
| 1104 |
the expense of longer build times. |
| 1105 |
|
| 1106 |
|
| 1107 |
make platform |
| 1108 |
^^^^^^^^^^^^^ |
| 1109 |
|
| 1110 |
Build the ``python`` program, but don't build the standard library |
| 1111 |
extension modules. This generates a file named ``platform`` which |
| 1112 |
contains a single line describing the details of the build platform, |
| 1113 |
e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``. |
| 1114 |
|
| 1115 |
|
| 1116 |
make profile-opt |
| 1117 |
^^^^^^^^^^^^^^^^ |
| 1118 |
|
| 1119 |
Build Python using profile-guided optimization (PGO). You can use the |
| 1120 |
configure :option:`--enable-optimizations` option to make this the |
| 1121 |
default target of the ``make`` command (``make all`` or just |
| 1122 |
``make``). |
| 1123 |
|
| 1124 |
|
| 1125 |
|
| 1126 |
make clean |
| 1127 |
^^^^^^^^^^ |
| 1128 |
|
| 1129 |
Remove built files. |
| 1130 |
|
| 1131 |
|
| 1132 |
make distclean |
| 1133 |
^^^^^^^^^^^^^^ |
| 1134 |
|
| 1135 |
In addition to the work done by ``make clean``, remove files |
| 1136 |
created by the configure script. ``configure`` will have to be run |
| 1137 |
before building again. [#]_ |
| 1138 |
|
| 1139 |
|
| 1140 |
make install |
| 1141 |
^^^^^^^^^^^^ |
| 1142 |
|
| 1143 |
Build the ``all`` target and install Python. |
| 1144 |
|
| 1145 |
|
| 1146 |
make test |
| 1147 |
^^^^^^^^^ |
| 1148 |
|
| 1149 |
Build the ``all`` target and run the Python test suite with the |
| 1150 |
``--fast-ci`` option. Variables: |
| 1151 |
|
| 1152 |
* ``TESTOPTS``: additional regrtest command-line options. |
| 1153 |
* ``TESTPYTHONOPTS``: additional Python command-line options. |
| 1154 |
* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes). |
| 1155 |
|
| 1156 |
|
| 1157 |
make buildbottest |
| 1158 |
^^^^^^^^^^^^^^^^^ |
| 1159 |
|
| 1160 |
This is similar to ``make test``, but uses the ``--slow-ci`` |
| 1161 |
option and default timeout of 20 minutes, instead of ``--fast-ci`` option. |
| 1162 |
|
| 1163 |
|
| 1164 |
make regen-all |
| 1165 |
^^^^^^^^^^^^^^ |
| 1166 |
|
| 1167 |
Regenerate (almost) all generated files. These include (but are not |
| 1168 |
limited to) bytecode cases, and parser generator file. |
| 1169 |
``make regen-stdlib-module-names`` and ``autoconf`` must be run |
| 1170 |
separately for the remaining `generated files <#generated-files>`_. |
| 1171 |
|
| 1172 |
|
| 1173 |
C extensions |
| 1174 |
------------ |
| 1175 |
|
| 1176 |
Some C extensions are built as built-in modules, like the ``sys`` module. |
| 1177 |
They are built with the ``Py_BUILD_CORE_BUILTIN`` macro defined. |
| 1178 |
Built-in modules have no ``__file__`` attribute: |
| 1179 |
|
| 1180 |
.. code-block:: pycon |
| 1181 |
|
| 1182 |
>>> import sys |
| 1183 |
>>> sys |
| 1184 |
<module 'sys' (built-in)> |
| 1185 |
>>> sys.__file__ |
| 1186 |
Traceback (most recent call last): |
| 1187 |
File "<stdin>", line 1, in <module> |
| 1188 |
AttributeError: module 'sys' has no attribute '__file__' |
| 1189 |
|
| 1190 |
Other C extensions are built as dynamic libraries, like the ``_asyncio`` module. |
| 1191 |
They are built with the ``Py_BUILD_CORE_MODULE`` macro defined. |
| 1192 |
Example on Linux x86-64: |
| 1193 |
|
| 1194 |
.. code-block:: pycon |
| 1195 |
|
| 1196 |
>>> import _asyncio |
| 1197 |
>>> _asyncio |
| 1198 |
<module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'> |
| 1199 |
>>> _asyncio.__file__ |
| 1200 |
'/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so' |
| 1201 |
|
| 1202 |
:file:`Modules/Setup` is used to generate Makefile targets to build C extensions. |
| 1203 |
At the beginning of the files, C extensions are built as built-in modules. |
| 1204 |
Extensions defined after the ``*shared*`` marker are built as dynamic libraries. |
| 1205 |
|
| 1206 |
The :c:macro:`!PyAPI_FUNC()`, :c:macro:`!PyAPI_DATA()` and |
| 1207 |
:c:macro:`PyMODINIT_FUNC` macros of :file:`Include/exports.h` are defined |
| 1208 |
differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined: |
| 1209 |
|
| 1210 |
* Use ``Py_EXPORTED_SYMBOL`` if the ``Py_BUILD_CORE_MODULE`` is defined |
| 1211 |
* Use ``Py_IMPORTED_SYMBOL`` otherwise. |
| 1212 |
|
| 1213 |
If the ``Py_BUILD_CORE_BUILTIN`` macro is used by mistake on a C extension |
| 1214 |
built as a shared library, its :samp:`PyInit_{xxx}()` function is not exported, |
| 1215 |
causing an :exc:`ImportError` on import. |
| 1216 |
|
| 1217 |
|
| 1218 |
Compiler and linker flags |
| 1219 |
========================= |
| 1220 |
|
| 1221 |
Options set by the ``./configure`` script and environment variables and used by |
| 1222 |
``Makefile``. |
| 1223 |
|
| 1224 |
Preprocessor flags |
| 1225 |
------------------ |
| 1226 |
|
| 1227 |
.. envvar:: CONFIGURE_CPPFLAGS |
| 1228 |
|
| 1229 |
Value of :envvar:`CPPFLAGS` variable passed to the ``./configure`` script. |
| 1230 |
|
| 1231 |
.. versionadded:: 3.6 |
| 1232 |
|
| 1233 |
.. envvar:: CPPFLAGS |
| 1234 |
|
| 1235 |
(Objective) C/C++ preprocessor flags, e.g. :samp:`-I{include_dir}` if you have |
| 1236 |
headers in a nonstandard directory *include_dir*. |
| 1237 |
|
| 1238 |
Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's |
| 1239 |
value to be able to build extension modules using the |
| 1240 |
directories specified in the environment variables. |
| 1241 |
|
| 1242 |
.. envvar:: BASECPPFLAGS |
| 1243 |
|
| 1244 |
.. versionadded:: 3.4 |
| 1245 |
|
| 1246 |
.. envvar:: PY_CPPFLAGS |
| 1247 |
|
| 1248 |
Extra preprocessor flags added for building the interpreter object files. |
| 1249 |
|
| 1250 |
Default: ``$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)``. |
| 1251 |
|
| 1252 |
.. versionadded:: 3.2 |
| 1253 |
|
| 1254 |
Compiler flags |
| 1255 |
-------------- |
| 1256 |
|
| 1257 |
.. envvar:: CC |
| 1258 |
|
| 1259 |
C compiler command. |
| 1260 |
|
| 1261 |
Example: ``gcc -pthread``. |
| 1262 |
|
| 1263 |
.. envvar:: CXX |
| 1264 |
|
| 1265 |
C++ compiler command. |
| 1266 |
|
| 1267 |
Example: ``g++ -pthread``. |
| 1268 |
|
| 1269 |
.. envvar:: CFLAGS |
| 1270 |
|
| 1271 |
C compiler flags. |
| 1272 |
|
| 1273 |
.. envvar:: CFLAGS_NODIST |
| 1274 |
|
| 1275 |
:envvar:`CFLAGS_NODIST` is used for building the interpreter and stdlib C |
| 1276 |
extensions. Use it when a compiler flag should *not* be part of |
| 1277 |
:envvar:`CFLAGS` once Python is installed (:gh:`65320`). |
| 1278 |
|
| 1279 |
In particular, :envvar:`CFLAGS` should not contain: |
| 1280 |
|
| 1281 |
* the compiler flag ``-I`` (for setting the search path for include files). |
| 1282 |
The ``-I`` flags are processed from left to right, and any flags in |
| 1283 |
:envvar:`CFLAGS` would take precedence over user- and package-supplied ``-I`` |
| 1284 |
flags. |
| 1285 |
|
| 1286 |
* hardening flags such as ``-Werror`` because distributions cannot control |
| 1287 |
whether packages installed by users conform to such heightened |
| 1288 |
standards. |
| 1289 |
|
| 1290 |
.. versionadded:: 3.5 |
| 1291 |
|
| 1292 |
.. envvar:: COMPILEALL_OPTS |
| 1293 |
|
| 1294 |
Options passed to the :mod:`compileall` command line when building PYC files |
| 1295 |
in ``make install``. Default: ``-j0``. |
| 1296 |
|
| 1297 |
.. versionadded:: 3.12 |
| 1298 |
|
| 1299 |
.. envvar:: EXTRA_CFLAGS |
| 1300 |
|
| 1301 |
Extra C compiler flags. |
| 1302 |
|
| 1303 |
.. envvar:: CONFIGURE_CFLAGS |
| 1304 |
|
| 1305 |
Value of :envvar:`CFLAGS` variable passed to the ``./configure`` |
| 1306 |
script. |
| 1307 |
|
| 1308 |
.. versionadded:: 3.2 |
| 1309 |
|
| 1310 |
.. envvar:: CONFIGURE_CFLAGS_NODIST |
| 1311 |
|
| 1312 |
Value of :envvar:`CFLAGS_NODIST` variable passed to the ``./configure`` |
| 1313 |
script. |
| 1314 |
|
| 1315 |
.. versionadded:: 3.5 |
| 1316 |
|
| 1317 |
.. envvar:: BASECFLAGS |
| 1318 |
|
| 1319 |
Base compiler flags. |
| 1320 |
|
| 1321 |
.. envvar:: OPT |
| 1322 |
|
| 1323 |
Optimization flags. |
| 1324 |
|
| 1325 |
.. envvar:: CFLAGS_ALIASING |
| 1326 |
|
| 1327 |
Strict or non-strict aliasing flags used to compile ``Python/dtoa.c``. |
| 1328 |
|
| 1329 |
.. versionadded:: 3.7 |
| 1330 |
|
| 1331 |
.. envvar:: CCSHARED |
| 1332 |
|
| 1333 |
Compiler flags used to build a shared library. |
| 1334 |
|
| 1335 |
For example, ``-fPIC`` is used on Linux and on BSD. |
| 1336 |
|
| 1337 |
.. envvar:: CFLAGSFORSHARED |
| 1338 |
|
| 1339 |
Extra C flags added for building the interpreter object files. |
| 1340 |
|
| 1341 |
Default: ``$(CCSHARED)`` when :option:`--enable-shared` is used, or an empty |
| 1342 |
string otherwise. |
| 1343 |
|
| 1344 |
.. envvar:: PY_CFLAGS |
| 1345 |
|
| 1346 |
Default: ``$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)``. |
| 1347 |
|
| 1348 |
.. envvar:: PY_CFLAGS_NODIST |
| 1349 |
|
| 1350 |
Default: ``$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal``. |
| 1351 |
|
| 1352 |
.. versionadded:: 3.5 |
| 1353 |
|
| 1354 |
.. envvar:: PY_STDMODULE_CFLAGS |
| 1355 |
|
| 1356 |
C flags used for building the interpreter object files. |
| 1357 |
|
| 1358 |
Default: ``$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)``. |
| 1359 |
|
| 1360 |
.. versionadded:: 3.7 |
| 1361 |
|
| 1362 |
.. envvar:: PY_CORE_CFLAGS |
| 1363 |
|
| 1364 |
Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE``. |
| 1365 |
|
| 1366 |
.. versionadded:: 3.2 |
| 1367 |
|
| 1368 |
.. envvar:: PY_BUILTIN_MODULE_CFLAGS |
| 1369 |
|
| 1370 |
Compiler flags to build a standard library extension module as a built-in |
| 1371 |
module, like the :mod:`posix` module. |
| 1372 |
|
| 1373 |
Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN``. |
| 1374 |
|
| 1375 |
.. versionadded:: 3.8 |
| 1376 |
|
| 1377 |
.. envvar:: PURIFY |
| 1378 |
|
| 1379 |
Purify command. Purify is a memory debugger program. |
| 1380 |
|
| 1381 |
Default: empty string (not used). |
| 1382 |
|
| 1383 |
|
| 1384 |
Linker flags |
| 1385 |
------------ |
| 1386 |
|
| 1387 |
.. envvar:: LINKCC |
| 1388 |
|
| 1389 |
Linker command used to build programs like ``python`` and ``_testembed``. |
| 1390 |
|
| 1391 |
Default: ``$(PURIFY) $(CC)``. |
| 1392 |
|
| 1393 |
.. envvar:: CONFIGURE_LDFLAGS |
| 1394 |
|
| 1395 |
Value of :envvar:`LDFLAGS` variable passed to the ``./configure`` script. |
| 1396 |
|
| 1397 |
Avoid assigning :envvar:`CFLAGS`, :envvar:`LDFLAGS`, etc. so users can use |
| 1398 |
them on the command line to append to these values without stomping the |
| 1399 |
pre-set values. |
| 1400 |
|
| 1401 |
.. versionadded:: 3.2 |
| 1402 |
|
| 1403 |
.. envvar:: LDFLAGS_NODIST |
| 1404 |
|
| 1405 |
:envvar:`LDFLAGS_NODIST` is used in the same manner as |
| 1406 |
:envvar:`CFLAGS_NODIST`. Use it when a linker flag should *not* be part of |
| 1407 |
:envvar:`LDFLAGS` once Python is installed (:gh:`65320`). |
| 1408 |
|
| 1409 |
In particular, :envvar:`LDFLAGS` should not contain: |
| 1410 |
|
| 1411 |
* the compiler flag ``-L`` (for setting the search path for libraries). |
| 1412 |
The ``-L`` flags are processed from left to right, and any flags in |
| 1413 |
:envvar:`LDFLAGS` would take precedence over user- and package-supplied ``-L`` |
| 1414 |
flags. |
| 1415 |
|
| 1416 |
.. envvar:: CONFIGURE_LDFLAGS_NODIST |
| 1417 |
|
| 1418 |
Value of :envvar:`LDFLAGS_NODIST` variable passed to the ``./configure`` |
| 1419 |
script. |
| 1420 |
|
| 1421 |
.. versionadded:: 3.8 |
| 1422 |
|
| 1423 |
.. envvar:: LDFLAGS |
| 1424 |
|
| 1425 |
Linker flags, e.g. :samp:`-L{lib_dir}` if you have libraries in a nonstandard |
| 1426 |
directory *lib_dir*. |
| 1427 |
|
| 1428 |
Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's |
| 1429 |
value to be able to build extension modules using the |
| 1430 |
directories specified in the environment variables. |
| 1431 |
|
| 1432 |
.. envvar:: LIBS |
| 1433 |
|
| 1434 |
Linker flags to pass libraries to the linker when linking the Python |
| 1435 |
executable. |
| 1436 |
|
| 1437 |
Example: ``-lrt``. |
| 1438 |
|
| 1439 |
.. envvar:: LDSHARED |
| 1440 |
|
| 1441 |
Command to build a shared library. |
| 1442 |
|
| 1443 |
Default: ``@LDSHARED@ $(PY_LDFLAGS)``. |
| 1444 |
|
| 1445 |
.. envvar:: BLDSHARED |
| 1446 |
|
| 1447 |
Command to build ``libpython`` shared library. |
| 1448 |
|
| 1449 |
Default: ``@BLDSHARED@ $(PY_CORE_LDFLAGS)``. |
| 1450 |
|
| 1451 |
.. envvar:: PY_LDFLAGS |
| 1452 |
|
| 1453 |
Default: ``$(CONFIGURE_LDFLAGS) $(LDFLAGS)``. |
| 1454 |
|
| 1455 |
.. envvar:: PY_LDFLAGS_NODIST |
| 1456 |
|
| 1457 |
Default: ``$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)``. |
| 1458 |
|
| 1459 |
.. versionadded:: 3.8 |
| 1460 |
|
| 1461 |
.. envvar:: PY_CORE_LDFLAGS |
| 1462 |
|
| 1463 |
Linker flags used for building the interpreter object files. |
| 1464 |
|
| 1465 |
.. versionadded:: 3.8 |
| 1466 |
|
| 1467 |
|
| 1468 |
.. rubric:: Footnotes |
| 1469 |
|
| 1470 |
.. [#] ``git clean -fdx`` is an even more extreme way to "clean" your |
| 1471 |
checkout. It removes all files not known to Git. |
| 1472 |
When bug hunting using ``git bisect``, this is |
| 1473 |
`recommended between probes <https://github.com/python/cpython/issues/114505#issuecomment-1907021718>`_ |
| 1474 |
to guarantee a completely clean build. **Use with care**, as it |
| 1475 |
will delete all files not checked into Git, including your |
| 1476 |
new, uncommitted work. |