diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/using/configure.rst | 175 |
1 files changed, 125 insertions, 50 deletions
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index f855c63..940bc19 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -28,27 +28,39 @@ General Options Disable IPv6 support (enabled by default if supported), see the :mod:`socket` module. -.. cmdoption:: --enable-big-digits[=15|30] +.. cmdoption:: --enable-big-digits=[15|30] - Use big digits (15 or 30 bits) for Python :class:`int` numbers (default is - system-dependent). + Define the size in bits of Python :class:`int` digits: 15 or 30 bits. + + By default, the number of bits is selected depending on ``sizeof(void*)``: + 30 bits if ``void*`` size is 64-bit or larger, 15 bits otherwise. + + Define the ``PYLONG_BITS_IN_DIGIT`` to ``15`` or ``30``. See :data:`sys.int_info.bits_per_digit <sys.int_info>`. -.. cmdoption:: --with-cxx-main[=COMPILER] +.. cmdoption:: --with-cxx-main +.. cmdoption:: --with-cxx-main=COMPILER Compile the Python ``main()`` function and link Python executable with C++ - compiler specified in *COMPILER* (default is ``$CXX``). + compiler: ``$CXX``, or *COMPILER* if specified. .. cmdoption:: --with-suffix=SUFFIX - Set executable suffix to *SUFFIX* (default is ``.exe``). + Set the Python executable suffix to *SUFFIX*. + + The default suffix is ``.exe`` on Windows and macOS (``python.exe`` + executable), and an empty string on other platforms (``python`` executable). .. 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. + Default: ``/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo``. + + See :data:`os.pathsep` path separator. + .. versionadded:: 3.9 .. cmdoption:: --without-decimal-contextvar @@ -56,7 +68,7 @@ General Options 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`. + See :data:`decimal.HAVE_CONTEXTVAR` and the :mod:`contextvars` module. .. versionadded:: 3.9 @@ -64,15 +76,17 @@ General Options Override order to check db backends for the :mod:`dbm` module - A valid value is a colon separated string with the backend names: + A valid value is a colon (``:``) separated string with the backend names: * ``ndbm``; * ``gdbm``; * ``bdb``. -.. cmdoption:: --with-c-locale-coercion +.. cmdoption:: --without-c-locale-coercion + + Disable C locale coercion to a UTF-8 based locale (enabled by default). - Enable C locale coercion to a UTF-8 based locale (default is yes). + Don't define the ``PY_COERCE_C_LOCALE`` macro. See :envvar:`PYTHONCOERCECLOCALE` and the :pep:`538`. @@ -109,10 +123,14 @@ Install Options .. versionadded:: 3.10 -.. cmdoption:: --with-ensurepip[=install|upgrade|no] +.. cmdoption:: --with-ensurepip=[upgrade|install|no] - ``install`` or ``upgrade`` using bundled pip of the :mod:`ensurepip` module, - when installing Python (default is ``upgrade``). + Select the :mod:`ensurepip` command run on Python installation: + + * ``upgrade`` (default): run ``python -m ensurepip --altinstall --upgrade`` + command. + * ``install``: run ``python -m ensurepip --altinstall`` command; + * ``no``: don't run ensurepip; .. versionadded:: 3.6 @@ -169,8 +187,9 @@ recommended for best performance. 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. + Don't define the ``WITH_DOC_STRINGS`` macro. + + See the ``PyDoc_STRVAR()`` macro. .. cmdoption:: --enable-profiling @@ -192,21 +211,22 @@ Effects of a debug build: * Add :func:`sys.gettotalrefcount` function. * Add :option:`-X showrefcount <-X>` command line option. * Add :envvar:`PYTHONTHREADDEBUG` environment variable. +* Add support for the ``__ltrace__`` variable: enable low-level tracing in the + bytecode evaluation loop if the variable is defined. * 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. + ``assert(...);`` and ``_PyObject_ASSERT(...);``. 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. +* The garbage collector (:func:`gc.collect` function) runs some basic checks on + objects consistency. +* More generally, add runtime checks, code surroundeded by ``#ifdef Py_DEBUG`` + and ``#endif``. See also the :ref:`Python Development Mode <devmode>` and the :option:`--with-trace-refs` configure option. @@ -222,7 +242,8 @@ Debug options .. cmdoption:: --with-pydebug - :ref:`Build Python in debug mode <debug-build>` (disabled by default). + :ref:`Build Python in debug mode <debug-build>`: define the ``Py_DEBUG`` + macro (disabled by default). .. cmdoption:: --with-trace-refs @@ -235,13 +256,14 @@ Debug options * Add :envvar:`PYTHONDUMPREFS` environment variable. This build is not ABI compatible with release build (default build) or debug - build (``Py_DEBUG`` macro). + build (``Py_DEBUG`` and ``Py_REF_DEBUG`` macros). .. versionadded:: 3.8 .. cmdoption:: --with-assertions - Build with C assertions enabled (default is no). + Build with C assertions enabled (default is no): ``assert(...);`` and + ``_PyObject_ASSERT(...);``. If set, the ``NDEBUG`` macro is not defined in the :envvar:`OPT` compiler variable. @@ -263,19 +285,19 @@ Debug options .. cmdoption:: --with-address-sanitizer - Enable AddressSanitizer memory error detector, 'asan' (default is no). + 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). + Enable MemorySanitizer allocation error detector, ``msan`` (default is no). .. versionadded:: 3.6 .. cmdoption:: --with-undefined-behavior-sanitizer - Enable UndefinedBehaviorSanitizer undefined behaviour detector, 'ubsan' + Enable UndefinedBehaviorSanitizer undefined behaviour detector, ``ubsan`` (default is no). .. versionadded:: 3.6 @@ -286,7 +308,7 @@ Linker options .. cmdoption:: --enable-shared - Enable building a shared Python library: "libpython" (default is no). + Enable building a shared Python library: ``libpython`` (default is no). .. cmdoption:: --without-static-libpython @@ -315,14 +337,24 @@ Libraries options .. cmdoption:: --with-system-libmpdec - Build the ``_decimal`` extension module using an installed ``libmpdec`` + Build the ``_decimal`` extension module using an installed ``mpdec`` library, see the :mod:`decimal` module (default is no). .. versionadded:: 3.3 -.. cmdoption:: --with(out)-readline[=editline] +.. cmdoption:: --with-readline=editline - Use ``editline`` for backend or disable the :mod:`readline` module. + Use ``editline`` library for backend of the :mod:`readline` module. + + Define the ``WITH_EDITLINE`` macro. + + .. versionadded:: 3.10 + +.. cmdoption:: --without-readline + + Don't build the :mod:`readline` module (built by default). + + Don't define the ``HAVE_LIBREADLINE`` macro. .. versionadded:: 3.10 @@ -346,7 +378,9 @@ Libraries options Root of the OpenSSL directory. -.. cmdoption:: --with-openssl-rpath=[DIR|auto|no] + .. versionadded:: 3.7 + +.. cmdoption:: --with-openssl-rpath=[no|auto|DIR] Set runtime library directory (rpath) for OpenSSL libraries: @@ -365,8 +399,8 @@ Security Options Select hash algorithm for use in ``Python/pyhash.c``: - * ``fnv``; * ``siphash24`` (default). + * ``fnv``; .. versionadded:: 3.4 @@ -387,7 +421,7 @@ Security Options Override the OpenSSL default cipher suites string: - * ``python``: use Python's preferred selection (default); + * ``python`` (default): use Python's preferred selection; * ``openssl``: leave OpenSSL's defaults untouched; * *STRING*: use a custom string, PROTOCOL_SSLv2 ignores the setting. @@ -401,22 +435,24 @@ macOS Options See ``Mac/README.rst``. -.. cmdoption:: --enable-universalsdk[=SDKDIR] +.. cmdoption:: --enable-universalsdk +.. 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] +.. cmdoption:: --enable-framework +.. 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 + Specify the kind of universal binary that should be created. This option is only valid when :option:`--enable-universalsdk` is set. - Options are: + Options: * ``universal2``; * ``32-bit``; @@ -436,18 +472,23 @@ See ``Mac/README.rst``. Compiler and linker flags ========================= -Options set by the ``./configure`` script, ``Makefile`` and by environment -variables. +Options set by the ``./configure`` script and environment variables and used by +``Makefile``. -Preprocessor flags ------------------- +Main files of the Python build system: -.. envvar:: CPP +* :file:`configure.ac` => :file:`configure`; +* :file:`Makefile.pre.in` => :file:`Makefile` (created by :file:`configure`); +* :file:`pyconfig.h` (created by :file:`configure`); +* :file:`Modules/Setup`. - C preprocessor. +Preprocessor flags +------------------ .. envvar:: CONFIGURE_CPPFLAGS + Value of :envvar:`CPPFLAGS` variable passed to the ``./configure`` script. + .. versionadded:: 3.6 .. envvar:: CPPFLAGS @@ -463,10 +504,6 @@ Preprocessor flags .. versionadded:: 3.4 -.. envvar:: MULTIARCH_CPPFLAGS - - .. versionadded:: 3.6 - .. envvar:: PY_CPPFLAGS Extra preprocessor flags added for building the interpreter object files. @@ -482,6 +519,16 @@ Compiler flags C compiler command. + Example: ``gcc -pthread``. + +.. envvar:: CXX + + C++ compiler command. + + Used if the :option:`--with-cxx-main` option is used. + + Example: ``g++ -pthread``. + .. envvar:: CFLAGS C compiler flags. @@ -500,14 +547,22 @@ Compiler flags .. envvar:: CONFIGURE_CFLAGS + Value of :envvar:`CFLAGS` variable passed to the ``./configure`` + script. + .. versionadded:: 3.2 .. envvar:: CONFIGURE_CFLAGS_NODIST + Value of :envvar:`CFLAGS_NODIST` variable passed to the ``./configure`` + script. + .. versionadded:: 3.5 .. envvar:: BASECFLAGS + Base compiler flags. + .. envvar:: OPT Optimization flags. @@ -518,10 +573,19 @@ Compiler flags .. versionadded:: 3.7 +.. envvar:: CCSHARED + + Compiler flags used to build a shared library. + + For example, ``-fPIC`` is used on Linux and on BSD. + .. envvar:: CFLAGSFORSHARED Extra C flags added for building the interpreter object files. + Default: ``$(CCSHARED)`` when :option:`--enable-shared` is used, or an empty + string otherwise. + .. envvar:: PY_CFLAGS Default: ``$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)``. @@ -548,6 +612,9 @@ Compiler flags .. envvar:: PY_BUILTIN_MODULE_CFLAGS + Compiler flags to build a standard library extension module as a built-in + module, like the :mod:`posix` module. + Default: ``$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN``. .. versionadded:: 3.8 @@ -558,6 +625,8 @@ Linker flags .. envvar:: CONFIGURE_LDFLAGS + Value of :envvar:`LDFLAGS` variable passed to the ``./configure`` script. + 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. @@ -572,6 +641,9 @@ Linker flags .. envvar:: CONFIGURE_LDFLAGS_NODIST + Value of :envvar:`LDFLAGS_NODIST` variable passed to the ``./configure`` + script. + .. versionadded:: 3.8 .. envvar:: LDFLAGS @@ -585,7 +657,10 @@ Linker flags .. envvar:: LIBS - Libraries to pass to the linker, e.g. ``-l<library>``. + Linker flags to pass libraries to the linker when linking the Python + executable. + + Example: ``-lrt``. .. envvar:: LDSHARED @@ -595,7 +670,7 @@ Linker flags .. envvar:: BLDSHARED - Command to build libpython shared library. + Command to build ``libpython`` shared library. Default: ``@BLDSHARED@ $(PY_CORE_LDFLAGS)``. |