mirror of https://github.com/python/cpython
bpo-43774: Enhance configure documentation (GH-25293)
This commit is contained in:
Victor Stinner
GitHub
parent
4f642dae4e
commit
5436695363
|
|
@ -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
|
||||
|
||||
Enable C locale coercion to a UTF-8 based locale (default is yes).
|
||||
Disable C locale coercion to a UTF-8 based locale (enabled by default).
|
||||
|
||||
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``.
|
||||
|
||||
Main files of the Python build system:
|
||||
|
||||
* :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`.
|
||||
|
||||
Preprocessor flags
|
||||
------------------
|
||||
|
||||
.. envvar:: CPP
|
||||
|
||||
C preprocessor.
|
||||
|
||||
.. 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)``.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue