diff options
| -rw-r--r-- | Doc/c-api/init_config.rst | 19 | ||||
| -rw-r--r-- | Doc/c-api/intro.rst | 9 | ||||
| -rw-r--r-- | Doc/c-api/memory.rst | 13 | ||||
| -rw-r--r-- | Doc/extending/newtypes.rst | 2 | ||||
| -rw-r--r-- | Doc/extending/newtypes_tutorial.rst | 3 | ||||
| -rw-r--r-- | Doc/howto/instrumentation.rst | 2 | ||||
| -rw-r--r-- | Doc/library/decimal.rst | 3 | ||||
| -rw-r--r-- | Doc/library/devmode.rst | 2 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 11 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 4 | ||||
| -rw-r--r-- | Doc/library/warnings.rst | 2 | ||||
| -rw-r--r-- | Doc/using/cmdline.rst | 9 | ||||
| -rw-r--r-- | Doc/using/configure.rst | 616 | ||||
| -rw-r--r-- | Doc/using/index.rst | 1 | ||||
| -rw-r--r-- | Doc/using/unix.rst | 6 | ||||
| -rw-r--r-- | Doc/whatsnew/3.10.rst | 7 | ||||
| -rw-r--r-- | Doc/whatsnew/3.6.rst | 4 | ||||
| -rw-r--r-- | Doc/whatsnew/3.7.rst | 4 | ||||
| -rw-r--r-- | Doc/whatsnew/3.8.rst | 6 | ||||
| -rw-r--r-- | Doc/whatsnew/3.9.rst | 2 |
20 files changed, 678 insertions, 47 deletions
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 29fbb68..7ececeb 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -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``. diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index bae5ce1..1223059 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -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. diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index d2d212b..b945429 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -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 diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index d902370..c078476 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -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 diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst index 4da77e7..530e2c4 100644 --- a/Doc/extending/newtypes_tutorial.rst +++ b/Doc/extending/newtypes_tutorial.rst @@ -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. diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst index f0081e4..ab6240d 100644 --- a/Doc/howto/instrumentation.rst +++ b/Doc/howto/instrumentation.rst @@ -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 diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index e194649..35a263a 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -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. diff --git a/Doc/library/devmode.rst b/Doc/library/devmode.rst index e6ed594..44e7d4f 100644 --- a/Doc/library/devmode.rst +++ b/Doc/library/devmode.rst @@ -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 ====================================== diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 0929f32..68b6050 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -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]]) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 80b30d0..d85eadb 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -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 diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 9c1743c..fe11aab 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -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 diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 1493c7c..a39cfd6 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -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. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst new file mode 100644 index 0000000..f855c63 --- /dev/null +++ b/Doc/using/configure.rst @@ -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 diff --git a/Doc/using/index.rst b/Doc/using/index.rst index 4a45121..e1a3111 100644 --- a/Doc/using/index.rst +++ b/Doc/using/index.rst @@ -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 diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index d5f073c..b5b26ec 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.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:: diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index 453a1b4..d690463 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -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 diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index 03a877a..d7884ea 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -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`. diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 75e1973..1199535 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -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`.) diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 91afffb..b1ecaae 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -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`.)
\ No newline at end of file +(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.) diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index 24c72ee..c16b9a7 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -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`. |