mirror of
https://github.com/python/cpython.git
synced 2024-11-24 10:24:35 +08:00
bpo-43774: Document configure options (GH-25283)
Add Doc/using/configure.rst documentation to document configure, preprocessor, compiler and linker options. Add a new section about the "Python debug build".
This commit is contained in:
Victor Stinner
GitHub
parent
d92c59f486
commit
a41782cc84
@ -241,8 +241,9 @@ PyPreConfig
|
||||
* ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc
|
||||
memory allocator <pymalloc>` with debug hooks
|
||||
|
||||
``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG``
|
||||
are not supported if Python is configured using ``--without-pymalloc``
|
||||
``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are
|
||||
not supported if Python is :option:`configured using --without-pymalloc
|
||||
<--without-pymalloc>`.
|
||||
|
||||
See :ref:`Memory Management <memory>`.
|
||||
|
||||
@ -636,7 +637,8 @@ PyConfig
|
||||
|
||||
Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable.
|
||||
|
||||
Need a special build of Python with the ``Py_TRACE_REFS`` macro defined.
|
||||
Need a special build of Python with the ``Py_TRACE_REFS`` macro defined:
|
||||
see :option:`configure --with-trace-refs <--with-trace-refs>`.
|
||||
|
||||
Default: ``0``.
|
||||
|
||||
@ -817,7 +819,8 @@ PyConfig
|
||||
|
||||
Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable.
|
||||
|
||||
The option is ignored if Python is built using ``--without-pymalloc``.
|
||||
The option is ignored if Python is :option:`configured using
|
||||
--without-pymalloc <--without-pymalloc>`.
|
||||
|
||||
Default: ``0``.
|
||||
|
||||
@ -827,8 +830,9 @@ PyConfig
|
||||
|
||||
Set by the :envvar:`PYTHONPLATLIBDIR` environment variable.
|
||||
|
||||
Default: value of the ``PLATLIBDIR`` macro which is set at configure time
|
||||
by ``--with-platlibdir`` (default: ``"lib"``).
|
||||
Default: value of the ``PLATLIBDIR`` macro which is set by the
|
||||
:option`configure --with-platlibdir option <--with-platlibdir>` (default:
|
||||
``"lib"``).
|
||||
|
||||
Part of the :ref:`Python Path Configuration <init-path-config>` input.
|
||||
|
||||
@ -1016,7 +1020,8 @@ PyConfig
|
||||
|
||||
Set to 1 by :option:`-X showrefcount <-X>` command line option.
|
||||
|
||||
Need a debug build of Python (``Py_REF_DEBUG`` macro must be defined).
|
||||
Need a :ref:`debug build of Python <debug-build>` (the ``Py_REF_DEBUG``
|
||||
macro must be defined).
|
||||
|
||||
Default: ``0``.
|
||||
|
||||
|
||||
@ -742,9 +742,10 @@ allocator, or low-level profiling of the main interpreter loop. Only the most
|
||||
frequently-used builds will be described in the remainder of this section.
|
||||
|
||||
Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
|
||||
what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
|
||||
enabled in the Unix build by adding ``--with-pydebug`` to the
|
||||
:file:`./configure` command. It is also implied by the presence of the
|
||||
what is generally meant by :ref:`a debug build of Python <debug-build>`.
|
||||
:c:macro:`Py_DEBUG` is enabled in the Unix build by adding
|
||||
:option:`--with-pydebug` to the :file:`./configure` command.
|
||||
It is also implied by the presence of the
|
||||
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled
|
||||
in the Unix build, compiler optimization is disabled.
|
||||
|
||||
@ -778,7 +779,7 @@ Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
|
||||
circular doubly linked list of active objects is maintained by adding two extra
|
||||
fields to every :c:type:`PyObject`. Total allocations are tracked as well. Upon
|
||||
exit, all existing references are printed. (In interactive mode this happens
|
||||
after every statement run by the interpreter.) Implied by :c:macro:`Py_DEBUG`.
|
||||
after every statement run by the interpreter.)
|
||||
|
||||
Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
|
||||
for more detailed information.
|
||||
|
||||
@ -385,11 +385,12 @@ Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``mal
|
||||
|
||||
Legend:
|
||||
|
||||
* Name: value for :envvar:`PYTHONMALLOC` environment variable
|
||||
* Name: value for :envvar:`PYTHONMALLOC` environment variable.
|
||||
* ``malloc``: system allocators from the standard C library, C functions:
|
||||
:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`
|
||||
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`
|
||||
* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`
|
||||
:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.
|
||||
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`.
|
||||
* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`.
|
||||
* "Debug build": :ref:`Python build in debug mode <debug-build>`.
|
||||
|
||||
.. _customize-memory-allocators:
|
||||
|
||||
@ -500,8 +501,8 @@ Customize Memory Allocators
|
||||
memory block was traced.
|
||||
|
||||
These hooks are :ref:`installed by default <default-memory-allocators>` if
|
||||
Python is compiled in debug
|
||||
mode. The :envvar:`PYTHONMALLOC` environment variable can be used to install
|
||||
:ref:`Python is built in debug mode <debug-build>`.
|
||||
The :envvar:`PYTHONMALLOC` environment variable can be used to install
|
||||
debug hooks on a Python compiled in release mode.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
|
||||
@ -12,7 +12,7 @@ This section aims to give a quick fly-by on the various type methods you can
|
||||
implement and what they do.
|
||||
|
||||
Here is the definition of :c:type:`PyTypeObject`, with some fields only used in
|
||||
debug builds omitted:
|
||||
:ref:`debug builds <debug-build>` omitted:
|
||||
|
||||
.. literalinclude:: ../includes/typestruct.h
|
||||
|
||||
|
||||
@ -69,7 +69,8 @@ at the start of each object struct and defines a field called ``ob_base``
|
||||
of type :c:type:`PyObject`, containing a pointer to a type object and a
|
||||
reference count (these can be accessed using the macros :c:macro:`Py_REFCNT`
|
||||
and :c:macro:`Py_TYPE` respectively). The reason for the macro is to
|
||||
abstract away the layout and to enable additional fields in debug builds.
|
||||
abstract away the layout and to enable additional fields in :ref:`debug builds
|
||||
<debug-build>`.
|
||||
|
||||
.. note::
|
||||
There is no semicolon above after the :c:macro:`PyObject_HEAD` macro.
|
||||
|
||||
@ -266,7 +266,7 @@ should instead read:
|
||||
|
||||
probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") {
|
||||
|
||||
(assuming a debug build of CPython 3.6)
|
||||
(assuming a :ref:`debug build <debug-build>` of CPython 3.6)
|
||||
|
||||
|
||||
Available static markers
|
||||
|
||||
@ -1484,7 +1484,8 @@ are also included in the pure Python version for compatibility.
|
||||
|
||||
.. data:: HAVE_CONTEXTVAR
|
||||
|
||||
The default value is ``True``. If Python is compiled ``--without-decimal-contextvar``,
|
||||
The default value is ``True``. If Python is :option:`configured with
|
||||
--without-decimal-contextvar <--without-decimal-contextvar>`,
|
||||
the C version uses a thread-local rather than a coroutine-local context and the value
|
||||
is ``False``. This is slightly faster in some nested context scenarios.
|
||||
|
||||
|
||||
@ -13,6 +13,8 @@ detected.
|
||||
It can be enabled using the :option:`-X dev <-X>` command line option or by
|
||||
setting the :envvar:`PYTHONDEVMODE` environment variable to ``1``.
|
||||
|
||||
See also :ref:`Python debug build <debug-build>`.
|
||||
|
||||
Effects of the Python Development Mode
|
||||
======================================
|
||||
|
||||
|
||||
@ -1581,13 +1581,15 @@ expression support in the :mod:`re` module).
|
||||
|
||||
By default, the *errors* argument is not checked for best performances, but
|
||||
only used at the first encoding error. Enable the :ref:`Python Development
|
||||
Mode <devmode>`, or use a debug build to check *errors*.
|
||||
Mode <devmode>`, or use a :ref:`debug build <debug-build>` to check
|
||||
*errors*.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
Support for keyword arguments added.
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
The *errors* is now checked in development mode and in debug mode.
|
||||
The *errors* is now checked in development mode and
|
||||
in :ref:`debug mode <debug-build>`.
|
||||
|
||||
|
||||
.. method:: str.endswith(suffix[, start[, end]])
|
||||
@ -2710,7 +2712,7 @@ arbitrary binary data.
|
||||
|
||||
By default, the *errors* argument is not checked for best performances, but
|
||||
only used at the first decoding error. Enable the :ref:`Python Development
|
||||
Mode <devmode>`, or use a debug build to check *errors*.
|
||||
Mode <devmode>`, or use a :ref:`debug build <debug-build>` to check *errors*.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -2722,7 +2724,8 @@ arbitrary binary data.
|
||||
Added support for keyword arguments.
|
||||
|
||||
.. versionchanged:: 3.9
|
||||
The *errors* is now checked in development mode and in debug mode.
|
||||
The *errors* is now checked in development mode and
|
||||
in :ref:`debug mode <debug-build>`.
|
||||
|
||||
|
||||
.. method:: bytes.endswith(suffix[, start[, end]])
|
||||
|
||||
@ -250,8 +250,8 @@ always available.
|
||||
Print low-level information to stderr about the state of CPython's memory
|
||||
allocator.
|
||||
|
||||
If Python is configured --with-pydebug, it also performs some expensive
|
||||
internal consistency checks.
|
||||
If Python is :option:`configured --with-pydebug <--with-pydebug>`, it also
|
||||
performs some expensive internal consistency checks.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
@ -229,7 +229,7 @@ In regular release builds, the default warning filter has the following entries
|
||||
ignore::ImportWarning
|
||||
ignore::ResourceWarning
|
||||
|
||||
In debug builds, the list of default warning filters is empty.
|
||||
In a :ref:`debug build <debug-build>`, the list of default warning filters is empty.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
:exc:`DeprecationWarning` is now ignored by default in addition to
|
||||
|
||||
@ -433,7 +433,8 @@ Miscellaneous options
|
||||
* ``-X faulthandler`` to enable :mod:`faulthandler`;
|
||||
* ``-X showrefcount`` to output the total reference count and number of used
|
||||
memory blocks when the program finishes or after each statement in the
|
||||
interactive interpreter. This only works on debug builds.
|
||||
interactive interpreter. This only works on :ref:`debug builds
|
||||
<debug-build>`.
|
||||
* ``-X tracemalloc`` to start tracing Python memory allocations using the
|
||||
:mod:`tracemalloc` module. By default, only the most recent frame is
|
||||
stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start
|
||||
@ -926,13 +927,11 @@ conflict.
|
||||
Debug-mode variables
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Setting these variables only has an effect in a debug build of Python.
|
||||
|
||||
.. envvar:: PYTHONTHREADDEBUG
|
||||
|
||||
If set, Python will print threading debug info.
|
||||
|
||||
Need Python configured with the ``--with-pydebug`` build option.
|
||||
Need a :ref:`debug build of Python <debug-build>`.
|
||||
|
||||
|
||||
.. envvar:: PYTHONDUMPREFS
|
||||
@ -940,4 +939,4 @@ Setting these variables only has an effect in a debug build of Python.
|
||||
If set, Python will dump objects and reference counts still alive after
|
||||
shutting down the interpreter.
|
||||
|
||||
Need Python configured with the ``--with-trace-refs`` build option.
|
||||
Need Python configured with the :option:`--with-trace-refs` build option.
|
||||
|
||||
616
Doc/using/configure.rst
Normal file
616
Doc/using/configure.rst
Normal file
@ -0,0 +1,616 @@
|
||||
****************
|
||||
Configure Python
|
||||
****************
|
||||
|
||||
.. _configure-options:
|
||||
|
||||
Configure Options
|
||||
=================
|
||||
|
||||
List all ``./configure`` script options using::
|
||||
|
||||
./configure --help
|
||||
|
||||
See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution.
|
||||
|
||||
General Options
|
||||
---------------
|
||||
|
||||
.. cmdoption:: --enable-loadable-sqlite-extensions
|
||||
|
||||
Support loadable extensions in the :mod:`_sqlite` extension module (default
|
||||
is no), see the :mod:`sqlite3` module.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. cmdoption:: --disable-ipv6
|
||||
|
||||
Disable IPv6 support (enabled by default if supported), see the
|
||||
:mod:`socket` module.
|
||||
|
||||
.. cmdoption:: --enable-big-digits[=15|30]
|
||||
|
||||
Use big digits (15 or 30 bits) for Python :class:`int` numbers (default is
|
||||
system-dependent).
|
||||
|
||||
See :data:`sys.int_info.bits_per_digit <sys.int_info>`.
|
||||
|
||||
.. cmdoption:: --with-cxx-main[=COMPILER]
|
||||
|
||||
Compile the Python ``main()`` function and link Python executable with C++
|
||||
compiler specified in *COMPILER* (default is ``$CXX``).
|
||||
|
||||
.. cmdoption:: --with-suffix=SUFFIX
|
||||
|
||||
Set executable suffix to *SUFFIX* (default is ``.exe``).
|
||||
|
||||
.. cmdoption:: --with-tzpath=<list of absolute paths separated by pathsep>
|
||||
|
||||
Select the default time zone search path for :data:`zoneinfo.TZPATH`,
|
||||
see the :mod:`zoneinfo` module.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. cmdoption:: --without-decimal-contextvar
|
||||
|
||||
Build the ``_decimal`` extension module using a thread-local context rather
|
||||
than a coroutine-local context (default), see the :mod:`decimal` module.
|
||||
|
||||
See :data:`decimal.HAVE_CONTEXTVAR`.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. cmdoption:: --with-dbmliborder=db1:db2:...
|
||||
|
||||
Override order to check db backends for the :mod:`dbm` module
|
||||
|
||||
A valid value is a colon separated string with the backend names:
|
||||
|
||||
* ``ndbm``;
|
||||
* ``gdbm``;
|
||||
* ``bdb``.
|
||||
|
||||
.. cmdoption:: --with-c-locale-coercion
|
||||
|
||||
Enable C locale coercion to a UTF-8 based locale (default is yes).
|
||||
|
||||
See :envvar:`PYTHONCOERCECLOCALE` and the :pep:`538`.
|
||||
|
||||
.. cmdoption:: --with-platlibdir=DIRNAME
|
||||
|
||||
Python library directory name (default is ``lib``).
|
||||
|
||||
Fedora and SuSE use ``lib64`` on 64-bit platforms.
|
||||
|
||||
See :data:`sys.platlibdir`.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. cmdoption:: --with-wheel-pkg-dir=PATH
|
||||
|
||||
Directory of wheel packages used by the :mod:`ensurepip` module
|
||||
(none by default).
|
||||
|
||||
Some Linux distribution packaging policies recommend against bundling
|
||||
dependencies. For example, Fedora installs wheel packages in the
|
||||
``/usr/share/python-wheels/`` directory and don't install the
|
||||
:mod:`ensurepip._bundled` package.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
|
||||
Install Options
|
||||
---------------
|
||||
|
||||
.. cmdoption:: --disable-test-modules
|
||||
|
||||
Don't build nor install test modules, like the :mod:`test` package or the
|
||||
:mod:`_testcapi` extension module (built and installed by default).
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
.. cmdoption:: --with-ensurepip[=install|upgrade|no]
|
||||
|
||||
``install`` or ``upgrade`` using bundled pip of the :mod:`ensurepip` module,
|
||||
when installing Python (default is ``upgrade``).
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
|
||||
Performance options
|
||||
-------------------
|
||||
|
||||
Configuring Python using ``--enable-optimizations --with-lto`` (PGO + LTO) is
|
||||
recommended for best performance.
|
||||
|
||||
.. cmdoption:: --enable-optimizations
|
||||
|
||||
Enable Profile Guided Optimization (PGO) using :envvar:`PROFILE_TASK`
|
||||
(disabled by default).
|
||||
|
||||
Disable also semantic interposition in libpython if ``--enable-shared`` and
|
||||
GCC is used: add ``-fno-semantic-interposition`` to the compiler and linker
|
||||
flags.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. versionchanged:: 3.10
|
||||
Use ``-fno-semantic-interposition`` on GCC.
|
||||
|
||||
.. envvar:: PROFILE_TASK
|
||||
|
||||
Environment variable used in the Makefile: Python command line arguments for
|
||||
the PGO generation task.
|
||||
|
||||
Default: ``-m test --pgo --timeout=$(TESTTIMEOUT)``.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. cmdoption:: --with-lto
|
||||
|
||||
Enable Link Time Optimization (LTO) in any build (disabled by default).
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. cmdoption:: --with-computed-gotos
|
||||
|
||||
Enable computed gotos in evaluation loop (enabled by default on supported
|
||||
compilers).
|
||||
|
||||
.. cmdoption:: --without-pymalloc
|
||||
|
||||
Disable the specialized Python memory allocator :ref:`pymalloc <pymalloc>`
|
||||
(enabled by default).
|
||||
|
||||
See also :envvar:`PYTHONMALLOC` environment variable.
|
||||
|
||||
.. cmdoption:: --without-doc-strings
|
||||
|
||||
Disable static documentation strings to reduce the memory footprint (enabled
|
||||
by default). Documentation strings defined in Python are not affected.
|
||||
|
||||
If used, the ``WITH_DOC_STRINGS`` macro is not defined. See the
|
||||
``PyDoc_STRVAR()`` macro.
|
||||
|
||||
.. cmdoption:: --enable-profiling
|
||||
|
||||
Enable C-level code profiling with ``gprof`` (disabled by default).
|
||||
|
||||
|
||||
.. _debug-build:
|
||||
|
||||
Debug build
|
||||
-----------
|
||||
|
||||
A debug build is Python built with the :option:`--with-pydebug` configure
|
||||
option.
|
||||
|
||||
Effects of a debug build:
|
||||
|
||||
* Define ``Py_DEBUG`` and ``Py_REF_DEBUG`` macros.
|
||||
* Add ``d`` to :data:`sys.abiflags`.
|
||||
* Add :func:`sys.gettotalrefcount` function.
|
||||
* Add :option:`-X showrefcount <-X>` command line option.
|
||||
* Add :envvar:`PYTHONTHREADDEBUG` environment variable.
|
||||
* The list of default warning filters is empty in the :mod:`warnings` module.
|
||||
* Install debug hooks on memory allocators to detect buffer overflow and other
|
||||
memory errors: see :c:func:`PyMem_SetupDebugHooks`.
|
||||
* Build Python with assertions (don't set ``NDEBUG`` macro):
|
||||
``assert(...);`` and ``_PyObject_ASSERT(...);`` are removed.
|
||||
See also the :option:`--with-assertions` configure option.
|
||||
* Add runtime checks, code surroundeded by ``#ifdef Py_DEBUG`` and ``#endif``.
|
||||
* Unicode and int objects are created with their memory filled with a pattern
|
||||
to help detecting uninitialized bytes.
|
||||
* Many functions ensure that are not called with an exception raised, since
|
||||
they can clear or replace the current exception.
|
||||
* The garbage collector (:func:`gc.collect` function) runs some quick checks on
|
||||
consistency.
|
||||
* Add support for the ``__ltrace__`` variable: enable low-level tracing in the
|
||||
bytecode evaluation loop if the variable is defined.
|
||||
|
||||
See also the :ref:`Python Development Mode <devmode>` and the
|
||||
:option:`--with-trace-refs` configure option.
|
||||
|
||||
.. versionchanged:: 3.8
|
||||
Release builds and debug builds are now ABI compatible: defining the
|
||||
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which
|
||||
introduces the only ABI incompatibility.
|
||||
|
||||
|
||||
Debug options
|
||||
-------------
|
||||
|
||||
.. cmdoption:: --with-pydebug
|
||||
|
||||
:ref:`Build Python in debug mode <debug-build>` (disabled by default).
|
||||
|
||||
.. cmdoption:: --with-trace-refs
|
||||
|
||||
Enable tracing references for debugging purpose (disabled by default).
|
||||
|
||||
Effects:
|
||||
|
||||
* Define the ``Py_TRACE_REFS`` macro.
|
||||
* Add :func:`sys.getobjects` function.
|
||||
* Add :envvar:`PYTHONDUMPREFS` environment variable.
|
||||
|
||||
This build is not ABI compatible with release build (default build) or debug
|
||||
build (``Py_DEBUG`` macro).
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. cmdoption:: --with-assertions
|
||||
|
||||
Build with C assertions enabled (default is no).
|
||||
|
||||
If set, the ``NDEBUG`` macro is not defined in the :envvar:`OPT` compiler
|
||||
variable.
|
||||
|
||||
See also the :option:`--with-pydebug` option (:ref:`debug build
|
||||
<debug-build>`) which also enables assertions.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. cmdoption:: --with-valgrind
|
||||
|
||||
Enable Valgrind support (default is no).
|
||||
|
||||
.. cmdoption:: --with-dtrace
|
||||
|
||||
Enable DTrace support (default is no).
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. cmdoption:: --with-address-sanitizer
|
||||
|
||||
Enable AddressSanitizer memory error detector, 'asan' (default is no).
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. cmdoption:: --with-memory-sanitizer
|
||||
|
||||
Enable MemorySanitizer allocation error detector, 'msan' (default is no).
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. cmdoption:: --with-undefined-behavior-sanitizer
|
||||
|
||||
Enable UndefinedBehaviorSanitizer undefined behaviour detector, 'ubsan'
|
||||
(default is no).
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
|
||||
Linker options
|
||||
--------------
|
||||
|
||||
.. cmdoption:: --enable-shared
|
||||
|
||||
Enable building a shared Python library: "libpython" (default is no).
|
||||
|
||||
.. cmdoption:: --without-static-libpython
|
||||
|
||||
Do not build ``libpythonMAJOR.MINOR.a`` and do not install ``python.o``
|
||||
(built and enabled by default).
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
|
||||
Libraries options
|
||||
-----------------
|
||||
|
||||
.. cmdoption:: --with-libs='lib1 ...'
|
||||
|
||||
Link against additional libraries (default is no).
|
||||
|
||||
.. cmdoption:: --with-system-expat
|
||||
|
||||
Build the :mod:`pyexpat` module using an installed ``expat`` library
|
||||
(default is no).
|
||||
|
||||
.. cmdoption:: --with-system-ffi
|
||||
|
||||
Build the :mod:`_ctypes` extension module using an installed ``ffi``
|
||||
library, see the :mod:`ctypes` module (default is system-dependent).
|
||||
|
||||
.. cmdoption:: --with-system-libmpdec
|
||||
|
||||
Build the ``_decimal`` extension module using an installed ``libmpdec``
|
||||
library, see the :mod:`decimal` module (default is no).
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. cmdoption:: --with(out)-readline[=editline]
|
||||
|
||||
Use ``editline`` for backend or disable the :mod:`readline` module.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
.. cmdoption:: --with-tcltk-includes='-I...'
|
||||
|
||||
Override search for Tcl and Tk include files.
|
||||
|
||||
.. cmdoption:: --with-tcltk-libs='-L...'
|
||||
|
||||
Override search for Tcl and Tk libraries.
|
||||
|
||||
.. cmdoption:: --with-libm=STRING
|
||||
|
||||
Override ``libm`` math library to *STRING* (default is system-dependent).
|
||||
|
||||
.. cmdoption:: --with-libc=STRING
|
||||
|
||||
Override ``libc`` C library to *STRING* (default is system-dependent).
|
||||
|
||||
.. cmdoption:: --with-openssl=DIR
|
||||
|
||||
Root of the OpenSSL directory.
|
||||
|
||||
.. cmdoption:: --with-openssl-rpath=[DIR|auto|no]
|
||||
|
||||
Set runtime library directory (rpath) for OpenSSL libraries:
|
||||
|
||||
* ``no`` (default): don't set rpath;
|
||||
* ``auto``: auto-detect rpath from :option:`--with-openssl` and
|
||||
``pkg-config``;
|
||||
* *DIR*: set an explicit rpath.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
|
||||
Security Options
|
||||
----------------
|
||||
|
||||
.. cmdoption:: --with-hash-algorithm=[fnv|siphash24]
|
||||
|
||||
Select hash algorithm for use in ``Python/pyhash.c``:
|
||||
|
||||
* ``fnv``;
|
||||
* ``siphash24`` (default).
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. cmdoption:: --with-builtin-hashlib-hashes=md5,sha1,sha256,sha512,sha3,blake2
|
||||
|
||||
Built-in hash modules:
|
||||
|
||||
* ``md5``;
|
||||
* ``sha1``;
|
||||
* ``sha256``;
|
||||
* ``sha512``;
|
||||
* ``sha3`` (with shake);
|
||||
* ``blake2``.
|
||||
|
||||
.. versionadded:: 3.9
|
||||
|
||||
.. cmdoption:: --with-ssl-default-suites=[python|openssl|STRING]
|
||||
|
||||
Override the OpenSSL default cipher suites string:
|
||||
|
||||
* ``python``: use Python's preferred selection (default);
|
||||
* ``openssl``: leave OpenSSL's defaults untouched;
|
||||
* *STRING*: use a custom string, PROTOCOL_SSLv2 ignores the setting.
|
||||
|
||||
See the :mod:`ssl` module.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
macOS Options
|
||||
-------------
|
||||
|
||||
See ``Mac/README.rst``.
|
||||
|
||||
.. cmdoption:: --enable-universalsdk[=SDKDIR]
|
||||
|
||||
Create a universal binary build. *SDKDIR* specifies which macOS SDK should
|
||||
be used to perform the build (default is no).
|
||||
|
||||
.. cmdoption:: --enable-framework[=INSTALLDIR]
|
||||
|
||||
Create a Python.framework rather than a traditional Unix install. Optional
|
||||
*INSTALLDIR* specifies the installation path (default is no).
|
||||
|
||||
.. cmdoption:: --with-universal-archs=ARCH
|
||||
|
||||
Specify the kind of universal binary that should be created. this option is
|
||||
only valid when :option:`--enable-universalsdk` is set.
|
||||
|
||||
Options are:
|
||||
|
||||
* ``universal2``;
|
||||
* ``32-bit``;
|
||||
* ``64-bit``;
|
||||
* ``3-way``;
|
||||
* ``intel``;
|
||||
* ``intel-32``;
|
||||
* ``intel-64``;
|
||||
* ``all``.
|
||||
|
||||
.. cmdoption:: --with-framework-name=FRAMEWORK
|
||||
|
||||
Specify the name for the python framework on macOS only valid when
|
||||
:option:`--enable-framework` is set (default: ``Python``).
|
||||
|
||||
|
||||
Compiler and linker flags
|
||||
=========================
|
||||
|
||||
Options set by the ``./configure`` script, ``Makefile`` and by environment
|
||||
variables.
|
||||
|
||||
Preprocessor flags
|
||||
------------------
|
||||
|
||||
.. envvar:: CPP
|
||||
|
||||
C preprocessor.
|
||||
|
||||
.. envvar:: CONFIGURE_CPPFLAGS
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. envvar:: CPPFLAGS
|
||||
|
||||
(Objective) C/C++ preprocessor flags, e.g. ``-I<include dir>`` if you have
|
||||
headers in a nonstandard directory ``<include dir>``.
|
||||
|
||||
Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's
|
||||
value for setup.py to be able to build extension modules using the
|
||||
directories specified in the environment variables.
|
||||
|
||||
.. envvar:: BASECPPFLAGS
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. envvar:: MULTIARCH_CPPFLAGS
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. envvar:: PY_CPPFLAGS
|
||||
|
||||
Extra preprocessor flags added for building the interpreter object files.
|
||||
|
||||
Default: ``$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)``.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
Compiler flags
|
||||
--------------
|
||||
|
||||
.. envvar:: CC
|
||||
|
||||
C compiler command.
|
||||
|
||||
.. envvar:: CFLAGS
|
||||
|
||||
C compiler flags.
|
||||
|
||||
.. envvar:: CFLAGS_NODIST
|
||||
|
||||
:envvar:`CFLAGS_NODIST` is used for building the interpreter and stdlib C
|
||||
extensions. Use it when a compiler flag should *not* be part of the
|
||||
distutils :envvar:`CFLAGS` once Python is installed (:issue:`21121`).
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. envvar:: EXTRA_CFLAGS
|
||||
|
||||
Extra C compiler flags.
|
||||
|
||||
.. envvar:: CONFIGURE_CFLAGS
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. envvar:: CONFIGURE_CFLAGS_NODIST
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. envvar:: BASECFLAGS
|
||||
|
||||
.. envvar:: OPT
|
||||
|
||||
Optimization flags.
|
||||
|
||||
.. envvar:: CFLAGS_ALIASING
|
||||
|
||||
Strict or non-strict aliasing flags used to compile ``Python/dtoa.c``.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. envvar:: CFLAGSFORSHARED
|
||||
|
||||
Extra C flags added for building the interpreter object files.
|
||||
|
||||
.. envvar:: PY_CFLAGS
|
||||
|
||||
Default: ``$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)``.
|
||||
|
||||
.. envvar:: PY_CFLAGS_NODIST
|
||||
|
||||
Default: ``$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal``.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. envvar:: PY_STDMODULE_CFLAGS
|
||||
|
||||
C flags used for building the interpreter object files.
|
||||
|
||||
Default: ``$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)``.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. envvar:: PY_CORE_CFLAGS
|
||||
|
||||
Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE``.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. envvar:: PY_BUILTIN_MODULE_CFLAGS
|
||||
|
||||
Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN``.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
|
||||
Linker flags
|
||||
------------
|
||||
|
||||
.. envvar:: CONFIGURE_LDFLAGS
|
||||
|
||||
Avoid assigning :envvar:`CFLAGS`, :envvar:`LDFLAGS`, etc. so users can use
|
||||
them on the command line to append to these values without stomping the
|
||||
pre-set values.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. envvar:: LDFLAGS_NODIST
|
||||
|
||||
:envvar:`LDFLAGS_NODIST` is used in the same manner as
|
||||
:envvar:`CFLAGS_NODIST`. Use it when a linker flag should *not* be part of
|
||||
the distutils :envvar:`LDFLAGS` once Python is installed (:issue:`35257`).
|
||||
|
||||
.. envvar:: CONFIGURE_LDFLAGS_NODIST
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. envvar:: LDFLAGS
|
||||
|
||||
Linker flags, e.g. ``-L<lib dir>`` if you have libraries in a nonstandard
|
||||
directory ``<lib dir>``.
|
||||
|
||||
Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's
|
||||
value for setup.py to be able to build extension modules using the
|
||||
directories specified in the environment variables.
|
||||
|
||||
.. envvar:: LIBS
|
||||
|
||||
Libraries to pass to the linker, e.g. ``-l<library>``.
|
||||
|
||||
.. envvar:: LDSHARED
|
||||
|
||||
Command to build a shared library.
|
||||
|
||||
Default: ``@LDSHARED@ $(PY_LDFLAGS)``.
|
||||
|
||||
.. envvar:: BLDSHARED
|
||||
|
||||
Command to build libpython shared library.
|
||||
|
||||
Default: ``@BLDSHARED@ $(PY_CORE_LDFLAGS)``.
|
||||
|
||||
.. envvar:: PY_LDFLAGS
|
||||
|
||||
Default: ``$(CONFIGURE_LDFLAGS) $(LDFLAGS)``.
|
||||
|
||||
.. envvar:: PY_LDFLAGS_NODIST
|
||||
|
||||
Default: ``$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)``.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
|
||||
.. envvar:: PY_CORE_LDFLAGS
|
||||
|
||||
Linker flags used for building the interpreter object files.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
@ -15,6 +15,7 @@ interpreter and things that make working with Python easier.
|
||||
|
||||
cmdline.rst
|
||||
unix.rst
|
||||
configure.rst
|
||||
windows.rst
|
||||
mac.rst
|
||||
editors.rst
|
||||
|
||||
@ -78,9 +78,9 @@ The build process consists of the usual commands::
|
||||
make
|
||||
make install
|
||||
|
||||
Configuration options and caveats for specific Unix platforms are extensively
|
||||
documented in the :source:`README.rst` file in the root of the Python source
|
||||
tree.
|
||||
:ref:`Configuration options <configure-options>` and caveats for specific Unix
|
||||
platforms are extensively documented in the :source:`README.rst` file in the
|
||||
root of the Python source tree.
|
||||
|
||||
.. warning::
|
||||
|
||||
|
||||
@ -1365,9 +1365,10 @@ New Features
|
||||
to simulate.
|
||||
(Contributed by Antoine Pitrou in :issue:`43356`.)
|
||||
|
||||
* The limited C API is now supported if Python is built in debug mode (if the
|
||||
``Py_DEBUG`` macro is defined). In the limited C API, the :c:func:`Py_INCREF`
|
||||
and :c:func:`Py_DECREF` functions are now implemented as opaque function
|
||||
* The limited C API is now supported if :ref:`Python is built in debug mode
|
||||
<debug-build>` (if the ``Py_DEBUG`` macro is defined). In the limited C API,
|
||||
the :c:func:`Py_INCREF` and :c:func:`Py_DECREF` functions are now implemented
|
||||
as opaque function
|
||||
calls, rather than accessing directly the :c:member:`PyObject.ob_refcnt`
|
||||
member, if Python is built in debug mode and the ``Py_LIMITED_API`` macro
|
||||
targets Python 3.10 or newer. It became possible to support the limited C API
|
||||
|
||||
@ -722,8 +722,8 @@ for the following events in the interpreter:
|
||||
* line of code executed.
|
||||
|
||||
This can be used to instrument running interpreters in production,
|
||||
without the need to recompile specific debug builds or providing
|
||||
application-specific profiling/debugging code.
|
||||
without the need to recompile specific :ref:`debug builds <debug-build>` or
|
||||
providing application-specific profiling/debugging code.
|
||||
|
||||
More details in :ref:`instrumentation`.
|
||||
|
||||
|
||||
@ -1588,8 +1588,8 @@ The initialization of the default warnings filters has changed as follows:
|
||||
for the new ``-X dev`` mode)
|
||||
* any implicit filters defined directly by the warnings machinery
|
||||
|
||||
* in CPython debug builds, all warnings are now displayed by default (the
|
||||
implicit filter list is empty)
|
||||
* in :ref:`CPython debug builds <debug-build>`, all warnings are now displayed
|
||||
by default (the implicit filter list is empty)
|
||||
|
||||
(Contributed by Nick Coghlan and Victor Stinner in :issue:`20361`,
|
||||
:issue:`32043`, and :issue:`32230`.)
|
||||
|
||||
@ -211,7 +211,7 @@ Python now uses the same ABI whether it's built in release or debug mode. On
|
||||
Unix, when Python is built in debug mode, it is now possible to load C
|
||||
extensions built in release mode and C extensions built using the stable ABI.
|
||||
|
||||
Release builds and debug builds are now ABI compatible: defining the
|
||||
Release builds and :ref:`debug builds <debug-build>` are now ABI compatible: defining the
|
||||
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which
|
||||
introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro, which
|
||||
adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS`
|
||||
@ -904,7 +904,7 @@ for :func:`property`, :func:`classmethod`, and :func:`staticmethod`::
|
||||
io
|
||||
--
|
||||
|
||||
In development mode (:option:`-X` ``env``) and in debug build, the
|
||||
In development mode (:option:`-X` ``env``) and in :ref:`debug build <debug-build>`, the
|
||||
:class:`io.IOBase` finalizer now logs the exception if the ``close()`` method
|
||||
fails. The exception is ignored silently by default in release build.
|
||||
(Contributed by Victor Stinner in :issue:`18748`.)
|
||||
@ -2246,4 +2246,4 @@ separator key, with ``&`` as the default. This change also affects
|
||||
:func:`cgi.parse` and :func:`cgi.parse_multipart` as they use the affected
|
||||
functions internally. For more details, please see their respective
|
||||
documentation.
|
||||
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.)
|
||||
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.)
|
||||
|
||||
@ -231,7 +231,7 @@ Other Language Changes
|
||||
absolute path for :mod:`__main__` module frames in this case.
|
||||
(Contributed by Victor Stinner in :issue:`20443`.)
|
||||
|
||||
* In the :ref:`Python Development Mode <devmode>` and in debug build, the
|
||||
* In the :ref:`Python Development Mode <devmode>` and in :ref:`debug build <debug-build>`, the
|
||||
*encoding* and *errors* arguments are now checked for string encoding and
|
||||
decoding operations. Examples: :func:`open`, :meth:`str.encode` and
|
||||
:meth:`bytes.decode`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user