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