3. 配置 Python

3.1. 配置参数

用以下方式列出脚本 ./configure 的所有参数：

  1. ./configure --help

参阅 Python 源代码中的 Misc/SpecialBuilds.txt 。

3.1.1. 常用参数

--enable-loadable-sqlite-extensions

支持 _sqlite 扩展模块中的可加载扩展（默认为否）。

参见 sqlite3.Connection.enable_load_extension() 方法的 sqlite3 模块。

3.6 新版功能.

--disable-ipv6

禁用 IPv6 支持（若开启支持则默认启用），见 socket 模块。

--enable-big-digits``=[15|30]

定义 Python int 数字的比特大小：15或30比特

默认情况下，比特数取决于 sizeof(void*)。如果 void* 大小为 64 位以上，则比特数为 30 位，否则为 15 位。

定义 PYLONG_BITS_IN_DIGIT 为 15 或 30。

参见 sys.int_info.bits_per_digit 。

--with-cxx-main

--with-cxx-main``=COMPILER

编译 Python main() 函数，用 C++ 编译器链接 Python 可执行文件： $CXX` 或 COMPILER。

--with-suffix``=SUFFIX

将 Python 的可执行文件后缀设置为 SUFFIX。

在 Windows 和 macOS 上的默认后缀为 .exe``（ ``python.exe 为可执行文件），在其他平台上为空字符串（ python 可执行）。

--with-tzpath``=<list of absolute paths separated by pathsep>

为 zoneinfo.TZPATH 选择默认的时区搜索路径。 参见 zoneinfo 模块的 编译时配置。

默认：/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo

参阅 os.pathsep 路径分隔符。

3.9 新版功能.

--without-decimal-contextvar

编译 _decimal 扩展模块时使用线程本地上下文，而不是协程本地上下文（默认），参见 decimal 模块。

参见 decimal.HAVE_CONTEXTVAR 和 contextvars 模块。

3.9 新版功能.

--with-dbmliborder``=db1:db2:...

覆盖 dbm 模块的 db 后端检查顺序。

合法值是用冒号（:）分隔的字符串，包含后端名称。

  • ndbm ；

  • gdbm ；

  • bdb 。

--without-c-locale-coercion

禁用 C 语言对 UTF-8 的强制要求（默认为启用）。

不定义 PY_COERCE_C_LOCALE 宏。

参阅 PYTHONCOERCECLOCALE 和 PEP 538。

--with-platlibdir``=DIRNAME

Python 库目录名（默认为 lib）。

Fedora 和 SuSE 在64 位平台用 lib64 。

参阅 sys.platlibdir 。

3.9 新版功能.

--with-wheel-pkg-dir``=PATH

ensurepip 模块用到的 wheel 包目录（默认为无）。

某些 Linux 发行版的打包策略建议不要捆绑依赖关系。如 Fedora 在``/usr/share/python-wheels/`` 目录下安装 wheel 包，而不安装 ensurepip._bundled 包。

3.10 新版功能.

3.1.2. 安装时的选项

--disable-test-modules

不编译和安装 test 模块，如 test 包或 _testcapi 扩展模块（默认会编译并安装）。

3.10 新版功能.

--with-ensurepip``=[upgrade|install|no]

选择 Python 安装时运行的 ensurepip 命令。

  • upgrade （默认）：运行 python -m ensurepip --altinstall --upgrade 命令。

  • install ：运行 python -m ensurepip --altinstall 命令。

  • no ：不运行 ensurepip。

3.6 新版功能.

3.1.3. 性能选项

建议用 --enable-optimizations --with-lto （PGO + LTO）配置 Python，以便实现最佳性能。

--enable-optimizations

用 PROFILE_TASK 启用以配置文件主导的优化（PGO）（默认为禁用）。

C 编译器 Clang 需要用到 llvm-profdata 程序进行 PGO。在 macOS 上，GCC 也需要用到它：在 macOS 上 GCC 只是 Clang 的别名而已。

Disable also semantic interposition in libpython if --enable-shared and GCC is used: add -fno-semantic-interposition to the compiler and linker flags.

3.6 新版功能.

在 3.10 版更改: Use -fno-semantic-interposition on GCC.

PROFILE_TASK

Makefile 用到的环境变量：PGO 用到的 Python 命令行参数。

默认为：-m test --pgo --timeout=$(TESTTIMEOUT) 。

3.8 新版功能.

--with-lto

在编译过程中启用链接时间优化（LTO）（默认为禁用）。

LTO 时 C 编译器 Clang 需要用到 llvm-ar 参数（在 macOS 则为 ar），以及支持 LTO 的链接器（ld.gold 或 lld）。

3.6 新版功能.

--with-computed-gotos

在求值环节启用 goto 计数（在支持的编译器上默认启用）。

--without-pymalloc

禁用特定的 Python 内存分配器 pymalloc （默认为启用）。

参见环境变量 PYTHONMALLOC 。

--without-doc-strings

禁用静态文档字符串以减少内存占用（默认启用）。Python 中定义的文档字符串不受影响。

不定义 PY_COERCE_C_LOCALE 宏。

参阅宏 PyDoc_STRVAR() 。

--enable-profiling

用 gprof 启用 C 语言级的代码评估（默认为禁用）。

3.1.4. Python 调试级编译

调试版本 Python 是指带有 --with-pydebug 参数的编译。

调试版本的效果：

  • 默认显示所有警告：在 warnings 模块中，默认警告过滤器的列表是空的。

  • 在 sys.abiflags 中加入 d 标记。

  • 加入 sys.gettotalrefcount() 函数。

  • 命令行参数加入 -X showrefcount 。

  • 环境变量加入 PYTHONTHREADDEBUG 。

  • 加入对 __ltrace__ 变量的支持：如果定义了该变量，在计算字节码环节启用底层跟踪。

  • 安装 内存分配调试钩子 ，以便检测缓冲区溢出和其他内存错误。

  • 定义宏 Py_DEBUG 和 Py_REF_DEBUG 。

  • 加入运行时检查：针对 #ifdef Py_DEBUG 和 #endif 包裹的代码。启用 assert(...) 和 _PyObject_ASSERT(...) 断言：不设置 NDEBUG 宏（参阅 --with-assertions 参数）。主要的运行检查包括：

    • 增加了对函数参数的合理性检查。

    • 创建 Unicode 和 int 对象时，内存按某种模式进行了填充，用于检测是否使用了未初始化的对象。

    • 确保有能力清除或替换当前异常的函数在调用时不会引发异常。

    • 垃圾收集器（gc.collect() 函数）对对象的一致性进行一些基本检查。

    • 从较宽类型转换到较窄类型时，Py_SAFE_DOWNCAST() 宏会检查整数下溢和上溢的情况。

参见 Python 开发模式 和配置参数 --with-trace-refs 。

在 3.8 版更改: 发布版和调试版的编译现在是 ABI 兼容的：定义了 Py_DEBUG 宏不再意味着同时定义了 Py_TRACE_REFS 宏（参见 --with-trace-refs 参数），这引入了唯一一处不是 ABI 兼容的地方。

3.1.5. 调试选项

--with-pydebug

在调试模式下编译 Python: 定义宏 Py_DEBUG (默认为禁用)。

--with-trace-refs

为了调试而启用引用的跟踪（默认为禁用）。

效果如下：

  • 定义 Py_TRACE_REFS 宏。

  • 加入 sys.getobjects() 函数。

  • 环境变量加入 PYTHONDUMPREFS 。

此版本与发布模式（默认编译模式）或调试模式（Py_DEBUG 和 Py_REF_DEBUG 宏）不具备 ABI 兼容性。

3.8 新版功能.

--with-assertions

编译时启用 C 断言：assert(...); 和 _PyObject_ASSERT(...); （默认不启用）。

如果设置此参数，则在 OPT 编译器变量中不定义 NDEBUG 宏。

参阅 --with-pydebug 选项（调试编译模式），它也可以启用断言。

3.6 新版功能.

--with-valgrind

启用 Valgrind （默认禁用）。

--with-dtrace

启用 DTrace（默认禁用）。

参阅 用 DTrace 和 SystemTap 测试 CPython。

3.6 新版功能.

--with-address-sanitizer

启用 AddressSanitizer 内存错误检测 asan，（默认为禁用）。

3.6 新版功能.

--with-memory-sanitizer

启用 MemorySanitizer 内存错误检测 msan，（默认为禁用）。

3.6 新版功能.

--with-undefined-behavior-sanitizer

启用 undefinedBehaviorSanitizer 未定义行为检测 ubsan，（默认为禁用）。

3.6 新版功能.

3.1.6. 链接器选项

--enable-shared

启用共享 Python 库 libpython 的编译（默认为禁用）。

--without-static-libpython

不编译 libpythonMAJOR.MINOR.a，也不安装 python.o (默认会编译并安装)。

3.10 新版功能.

3.1.7. 库选项

--with-libs``='lib1 ...'

链接附加库（默认不会）。

--with-system-expat

用已安装的 expat 库编译 pyexpat 模块（默认为否）。

--with-system-ffi

用已安装的 ffi 库编译 _ctypes 扩展模块，参见 ctypes 模块（默认情况视系统而定）。

--with-system-libmpdec

用已安装的 mpdec 库编译 _decimal 扩展模块，参见 decimal 模块（默认为否）。

3.3 新版功能.

--with-readline``=editline

用 editline 库作为 readline 模块的后端。

定义 WITH_EDITLINE 宏。

3.10 新版功能.

--without-readline

不编译 readline 模块（默认会）。

不定义 HAVE_LIBREADLINE 宏。

3.10 新版功能.

--with-tcltk-includes``='-I...'

覆盖 Tcl 和 Tk 包含文件的搜索路径。

--with-tcltk-libs``='-L...'

覆盖 Tcl 和 Tk 库的搜索路径。

--with-libm``=STRING

将 libm 数学库覆盖为 STRING (默认情况视系统而定)。

--with-libc``=STRING

将 libc C 库覆盖为 STRING (默认情况视系统而定)。

--with-openssl``=DIR

OpenSSL 的根目录。

3.7 新版功能.

--with-openssl-rpath``=[no|auto|DIR]

设置 OpenSSL 库的运行时库目录（rpath）。

  • no (默认): 不设置 rpath。

  • auto：根据 --with-openssl 和 pkg-config 自动检测 rpath。

  • DIR ：直接设置 rpath。

3.10 新版功能.

3.1.8. 安全性选项

--with-hash-algorithm``=[fnv|siphash24]

选择 Python/pyhash.c 采用的哈希算法。

  • siphash24 (默认)。

  • fnv。

3.4 新版功能.

--with-builtin-hashlib-hashes``=md5,sha1,sha256,sha512,sha3,blake2

内置哈希模块：

  • md5。

  • sha1。

  • sha256。

  • sha512。

  • sha3 (带 shake)。

  • blake2。

3.9 新版功能.

--with-ssl-default-suites``=[python|openssl|STRING]

覆盖 OpenSSL 默认的密码套件字符串。

  • python (默认值): 采用 Python 推荐选择。

  • openssl：保留 OpenSSL 默认值不动。

  • STRING ：采用自定义字符串。

参见 ssl 模块。

3.7 新版功能.

在 3.10 版更改: 设置 python 和 STRING 也会把 TLS 1.2 设为最低版本的协议。

3.1.9. macOS 选项

参见 Mac/README.rst 。

--enable-universalsdk

--enable-universalsdk``=SDKDIR

创建通用的二进制版本。SDKDIR 指定应采用的 macOS SDK （默认为否）。

--enable-framework

--enable-framework``=INSTALLDIR

创建 Python.framework ，而不是传统的 Unix 安装版。可选参数 INSTALLDIR 指定了安装路径（(默认为否）。

--with-universal-archs``=ARCH

指定应创建何种通用二进制文件。该选项仅当设置了 --enable-universalsdk 时才有效。

可选项：

  • universal2。

  • 32-bit。

  • 64-bit。

  • 3-way。

  • intel。

  • intel-32。

  • intel-64。

  • all。

--with-framework-name``=FRAMEWORK

为 macOS 中的 python 框架指定名称，仅当设置了 --enable-framework 时有效（默认：Python）。

3.2. Python Build System

3.2.1. Main files of the build system

  • configure.ac => configure;

  • Makefile.pre.in => Makefile (created by configure);

  • pyconfig.h (created by configure);

  • Modules/Setup: C extensions built by the Makefile using Module/makesetup shell script;

  • setup.py: C extensions built using the distutils module.

3.2.2. Main build steps

  • C files (.c) are built as object files (.o).

  • A static libpython library (.a) is created from objects files.

  • python.o and the static libpython library are linked into the final python program.

  • C extensions are built by the Makefile (see Modules/Setup) and python setup.py build.

3.2.3. Main Makefile targets

  • make: Build Python with the standard library.

  • make platform:: build the python program, but don’t build the standard library extension modules.

  • make profile-opt: build Python using Profile Guided Optimization (PGO). You can use the configure --enable-optimizations option to make this the default target of the make command (make all or just make).

  • make buildbottest: Build Python and run the Python test suite, the same way than buildbots test Python. Set TESTTIMEOUT variable (in seconds) to change the test timeout (1200 by default: 20 minutes).

  • make install: Build and install Python.

  • make regen-all: Regenerate (almost) all generated files; make regen-stdlib-module-names and autoconf must be run separately for the remaining generated files.

  • make clean: Remove built files.

  • make distclean: Same than make clean, but remove also files created by the configure script.

3.2.4. C extensions

Some C extensions are built as built-in modules, like the sys module. They are built with the Py_BUILD_CORE_BUILTIN macro defined. Built-in modules have no __file__ attribute:

  1. >>> import sys
  2. >>> sys
  3. <module 'sys' (built-in)>
  4. >>> sys.__file__
  5. Traceback (most recent call last):
  6.   File "<stdin>", line 1, in <module>
  7. AttributeError: module 'sys' has no attribute '__file__'

Other C extensins are built as dynamic libraires, like the _asyncio module. They are built with the Py_BUILD_CORE_MODULE macro defined. Example on Linux x86-64:

  1. >>> import _asyncio
  2. >>> _asyncio
  3. <module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
  4. >>> _asyncio.__file__
  5. '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'

Modules/Setup is used to generate Makefile targets to build C extensions. At the beginning of the files, C extensions are built as built-in modules. Extensions defined after the *shared* marker are built as dynamic libraries.

The setup.py script only builds C extensions as shared libraries using the distutils module.

The PyAPI_FUNC(), PyAPI_API() and PyMODINIT_FUNC() macros of Include/pyport.h are defined differently depending if the Py_BUILD_CORE_MODULE macro is defined:

  • Use Py_EXPORTED_SYMBOL if the Py_BUILD_CORE_MODULE is defined

  • Use Py_IMPORTED_SYMBOL otherwise.

If the Py_BUILD_CORE_BUILTIN macro is used by mistake on a C extension built as a shared library, its PyInit_xxx() function is not exported, causing an ImportError on import.

3.3. Compiler and linker flags

Options set by the ./configure script and environment variables and used by Makefile.

3.3.1. Preprocessor flags

CONFIGURE_CPPFLAGS

Value of CPPFLAGS variable passed to the ./configure script.

3.6 新版功能.

CPPFLAGS

(Objective) C/C++ preprocessor flags, e.g. -I<include dir> if you have headers in a nonstandard directory <include dir>.

Both CPPFLAGS and 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.

BASECPPFLAGS

3.4 新版功能.

PY_CPPFLAGS

Extra preprocessor flags added for building the interpreter object files.

Default: $(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS).

3.2 新版功能.

3.3.2. Compiler flags

CC

C compiler command.

Example: gcc -pthread.

MAINCC

C compiler command used to build the main() function of programs like python.

Variable set by the --with-cxx-main option of the configure script.

Default: $(CC).

CXX

C++ compiler command.

Used if the --with-cxx-main option is used.

Example: g++ -pthread.

CFLAGS

C compiler flags.

CFLAGS_NODIST

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 CFLAGS once Python is installed (bpo-21121).

3.5 新版功能.

EXTRA_CFLAGS

Extra C compiler flags.

CONFIGURE_CFLAGS

Value of CFLAGS variable passed to the ./configure script.

3.2 新版功能.

CONFIGURE_CFLAGS_NODIST

Value of CFLAGS_NODIST variable passed to the ./configure script.

3.5 新版功能.

BASECFLAGS

Base compiler flags.

OPT

Optimization flags.

CFLAGS_ALIASING

Strict or non-strict aliasing flags used to compile Python/dtoa.c.

3.7 新版功能.

CCSHARED

Compiler flags used to build a shared library.

For example, -fPIC is used on Linux and on BSD.

CFLAGSFORSHARED

Extra C flags added for building the interpreter object files.

Default: $(CCSHARED) when --enable-shared is used, or an empty string otherwise.

PY_CFLAGS

Default: $(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS).

PY_CFLAGS_NODIST

Default: $(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal.

3.5 新版功能.

PY_STDMODULE_CFLAGS

C flags used for building the interpreter object files.

Default: $(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED).

3.7 新版功能.

PY_CORE_CFLAGS

Default: $(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE.

3.2 新版功能.

PY_BUILTIN_MODULE_CFLAGS

Compiler flags to build a standard library extension module as a built-in module, like the posix module.

Default: $(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN.

3.8 新版功能.

PURIFY

Purify command. Purify is a memory debugger program.

Default: empty string (not used).

3.3.3. Linker flags

LINKCC

Linker command used to build programs like python and _testembed.

Default: $(PURIFY) $(MAINCC).

CONFIGURE_LDFLAGS

Value of LDFLAGS variable passed to the ./configure script.

Avoid assigning CFLAGS, LDFLAGS, etc. so users can use them on the command line to append to these values without stomping the pre-set values.

3.2 新版功能.

LDFLAGS_NODIST

LDFLAGS_NODIST is used in the same manner as CFLAGS_NODIST. Use it when a linker flag should not be part of the distutils LDFLAGS once Python is installed (bpo-35257).

CONFIGURE_LDFLAGS_NODIST

Value of LDFLAGS_NODIST variable passed to the ./configure script.

3.8 新版功能.

LDFLAGS

Linker flags, e.g. -L<lib dir> if you have libraries in a nonstandard directory <lib dir>.

Both CPPFLAGS and 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.

LIBS

Linker flags to pass libraries to the linker when linking the Python executable.

Example: -lrt.

LDSHARED

Command to build a shared library.

Default: @LDSHARED@ $(PY_LDFLAGS).

BLDSHARED

Command to build libpython shared library.

Default: @BLDSHARED@ $(PY_CORE_LDFLAGS).

PY_LDFLAGS

Default: $(CONFIGURE_LDFLAGS) $(LDFLAGS).

PY_LDFLAGS_NODIST

Default: $(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST).

3.8 新版功能.

PY_CORE_LDFLAGS

Linker flags used for building the interpreter object files.

3.8 新版功能.