3. 配置 Python

3.1. 构建要求

构建 CPython 所需的特性和最低版本

构建可选模块

有关构建所有模块所需的依赖项的完整列表以及如何安装它们，请参阅 devguide。

  • 重新生成 configure 脚本需要 Autoconf 2.72 和 aclocal 1.16.5。

3.1 版中已更改: 现在需要 Tcl/Tk 8.3.1 版本。

3.5 版中已更改: 在 Windows 上，现在需要 Visual Studio 2015 或更高版本。现在需要 Tcl/Tk 8.4 版本。

3.6 版中已更改: 现在需要选定的 C99 特性，例如 <stdint.h> 和 static inline 函数。

3.7 版中已更改: 现在需要线程支持和 OpenSSL 1.0.2。

3.10 版中已更改: 现在需要 OpenSSL 1.1.1。需要 SQLite 3.7.15。

3.11 版中已更改: 现在需要 C11 编译器、IEEE 754 和 NaN 支持。在 Windows 上，需要 Visual Studio 2017 或更高版本。对于 tkinter 模块，现在需要 Tcl/Tk 8.5.12 版本。

3.13 版中已更改: 现在需要 Autoconf 2.71、aclocal 1.16.5 和 SQLite 3.15.2。

3.14 版中已更改: 现在需要 Autoconf 2.72。

另请参阅 PEP 7 “C 代码风格指南”和 PEP 11 “CPython 平台支持”。

3.2. 生成的文件

为了减少构建依赖项，Python 源代码包含多个生成的文件。重新生成所有生成文件的命令

make regen-all
make regen-stdlib-module-names
make regen-limited-abi
make regen-configure

Makefile.pre.in 文件记录了生成的文件、它们的输入以及用于重新生成它们的工具。搜索 regen-* make 目标。

3.2.1. 配置脚本

make regen-configure 命令使用 Tools/build/regen-configure.sh shell 脚本重新生成 aclocal.m4 文件和 configure 脚本，该脚本使用 Ubuntu 容器获取相同的工具版本并生成可重现的输出。

容器是可选的，以下命令可以在本地运行

autoreconf -ivf -Werror

生成的文件可能会根据具体的 autoconf-archive、aclocal 和 pkg-config 版本而变化。

3.3. 配置选项

使用以下命令列出所有 configure 脚本选项

./configure --help

另请参阅 Python 源代码分发中的 Misc/SpecialBuilds.txt。

3.3.1. 通用选项

--enable-loadable-sqlite-extensions

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

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

在 3.6 版本加入。

--disable-ipv6

禁用 IPv6 支持（如果支持，默认启用），请参阅 socket 模块。

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

定义 Python int 数字的位大小：15 或 30 位。

默认情况下，数字大小为 30。

将 PYLONG_BITS_IN_DIGIT 定义为 15 或 30。

请参阅 sys.int_info.bits_per_digit。

--with-suffix=SUFFIX

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

在 Windows 和 macOS 上（python.exe 可执行文件），默认后缀为 .exe；在 Emscripten 节点上为 .js；在 Emscripten 浏览器上为 .html；在 WASI 上为 .wasm；在其他平台上为空字符串（python 可执行文件）。

3.11 版中已更改: WASM 平台上的默认后缀是 .js、.html 或 .wasm 之一。

--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=<list of backend names>

覆盖 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 将 wheel 包安装在 /usr/share/python-wheels/ 目录中，并且不安装 ensurepip._bundled 包。

在 3.10 版本加入。

--with-pkg-config=[check|yes|no]

configure 是否应该使用 pkg-config 来检测构建依赖项。

  • check（默认）：pkg-config 是可选的

  • yes：pkg-config 是强制性的

  • no：即使存在 pkg-config，configure 也不使用它

在 3.11 版本中新增。

--enable-pystats

开启内部 Python 性能统计信息收集。

默认情况下，统计信息收集是关闭的。使用 python3 -X pystats 命令或设置 PYTHONSTATS=1 环境变量以在 Python 启动时开启统计信息收集。

在 Python 退出时，如果统计信息收集已开启且未清除，则转储统计信息。

影响

  • 添加 -X pystats 命令行选项。

  • 添加 PYTHONSTATS 环境变量。

  • 定义 Py_STATS 宏。

  • 向 sys 模块添加函数

    • sys._stats_on()：开启统计信息收集。

    • sys._stats_off()：关闭统计信息收集。

    • sys._stats_clear()：清除统计信息。

    • sys._stats_dump()：将统计信息转储到文件，并清除统计信息。

统计信息将被转储到 /tmp/py_stats/ (Unix) 或 C:\temp\py_stats\ (Windows) 中的任意（可能唯一）文件。如果该目录不存在，结果将打印到 stderr。

使用 Tools/scripts/summarize_stats.py 读取统计信息。

统计数据

  • 操作码

    • 专门化：成功、失败、命中、延迟、未命中、去优化、失败；

    • 执行计数；

    • 对数。

  • 调用

    • 内联 Python 调用；

    • PyEval 调用；

    • 压入帧；

    • 创建帧对象；

    • Eval 调用：向量、生成器、遗留、函数 VECTORCALL、构建类、槽、函数“ex”、API、方法。

  • 对象

    • 增引用和减引用；

    • 解释器增引用和减引用；

    • 分配：所有、512 字节、4 KiB、大；

    • 释放；

    • 到/从空闲列表；

    • 字典实体化/非实体化；

    • 类型缓存；

    • 优化尝试；

    • 创建/执行优化跟踪；

    • 执行的 uops。

  • 垃圾回收器

    • 垃圾回收；

    • 访问的对象；

    • 收集的对象。

在 3.11 版本中新增。

--disable-gil

启用在没有 全局解释器锁 (GIL) 的情况下运行 Python 的支持：自由线程构建。

定义 Py_GIL_DISABLED 宏并向 sys.abiflags 添加 "t"。

有关更多详细信息，请参阅 自由线程 CPython。

在 3.13 版本加入。

--enable-experimental-jit=[no|yes|yes-off|interpreter]

指示如何集成 实验性即时编译器。

  • no：不构建 JIT。

  • yes：启用 JIT。要在运行时禁用它，请设置环境变量 PYTHON_JIT=0。

  • yes-off：构建 JIT，但默认禁用。要在运行时启用它，请设置环境变量 PYTHON_JIT=1。

  • interpreter：启用“JIT 解释器”（仅对调试 JIT 本身的人有用）。要在运行时禁用它，请设置环境变量 PYTHON_JIT=0。

如果未提供该选项，则 --enable-experimental-jit=no 是默认行为，而 --enable-experimental-jit 是 --enable-experimental-jit=yes 的简写。有关更多信息，包括如何安装必要的构建时依赖项，请参阅 Tools/jit/README.md。

备注

当启用 JIT 构建 CPython 时，请确保您的系统已安装 Python 3.11 或更高版本。

在 3.13 版本加入。

PKG_CONFIG

pkg-config 工具的路径。

PKG_CONFIG_LIBDIR
PKG_CONFIG_PATH

pkg-config 选项。

3.3.2. C 编译器选项

CC

C 编译器命令。

CFLAGS

C 编译器标志。

CPP

C 预处理器命令。

CPPFLAGS

C 预处理器标志，例如 -Iinclude_dir。

3.3.3. 链接器选项

LDFLAGS

链接器标志，例如 -Llibrary_directory。

LIBS

传递给链接器的库，例如 -llibrary。

MACHDEP

机器相关库文件的名称。

3.3.4. 第三方依赖项选项

在 3.11 版本中新增。

BZIP2_CFLAGS
BZIP2_LIBS

用于将 Python 链接到 libbz2 的 C 编译器和链接器标志，由 bz2 模块使用，覆盖 pkg-config。

CURSES_CFLAGS
CURSES_LIBS

用于 libncurses 或 libncursesw 的 C 编译器和链接器标志，由 curses 模块使用，覆盖 pkg-config。

GDBM_CFLAGS
GDBM_LIBS

用于 gdbm 的 C 编译器和链接器标志。

LIBB2_CFLAGS
LIBB2_LIBS

用于 libb2 (BLAKE2) 的 C 编译器和链接器标志，由 hashlib 模块使用，覆盖 pkg-config。

LIBEDIT_CFLAGS
LIBEDIT_LIBS

用于 libedit 的 C 编译器和链接器标志，由 readline 模块使用，覆盖 pkg-config。

LIBFFI_CFLAGS
LIBFFI_LIBS

用于 libffi 的 C 编译器和链接器标志，由 ctypes 模块使用，覆盖 pkg-config。

LIBMPDEC_CFLAGS
LIBMPDEC_LIBS

用于 libmpdec 的 C 编译器和链接器标志，由 decimal 模块使用，覆盖 pkg-config。

备注

除非指定了 --with-system-libmpdec，否则这些环境变量无效。

LIBLZMA_CFLAGS
LIBLZMA_LIBS

用于 liblzma 的 C 编译器和链接器标志，由 lzma 模块使用，覆盖 pkg-config。

LIBREADLINE_CFLAGS
LIBREADLINE_LIBS

用于 libreadline 的 C 编译器和链接器标志，由 readline 模块使用，覆盖 pkg-config。

LIBSQLITE3_CFLAGS
LIBSQLITE3_LIBS

用于 libsqlite3 的 C 编译器和链接器标志，由 sqlite3 模块使用，覆盖 pkg-config。

LIBUUID_CFLAGS
LIBUUID_LIBS

用于 libuuid 的 C 编译器和链接器标志，由 uuid 模块使用，覆盖 pkg-config。

LIBZSTD_CFLAGS
LIBZSTD_LIBS

用于 libzstd 的 C 编译器和链接器标志，由 compression.zstd 模块使用，覆盖 pkg-config。

在 3.14 版本加入。

PANEL_CFLAGS
PANEL_LIBS

PANEL 的 C 编译器和链接器标志，覆盖 pkg-config。

用于 libpanel 或 libpanelw 的 C 编译器和链接器标志，由 curses.panel 模块使用，覆盖 pkg-config。

TCLTK_CFLAGS
TCLTK_LIBS

TCLTK 的 C 编译器和链接器标志，覆盖 pkg-config。

ZLIB_CFLAGS
ZLIB_LIBS

用于 libzlib 的 C 编译器和链接器标志，由 gzip 模块使用，覆盖 pkg-config。

3.3.5. WebAssembly 选项

--enable-wasm-dynamic-linking

为 WASM 开启动态链接支持。

动态链接启用 dlopen。由于有限的死代码消除和附加功能，可执行文件的大小增加。

在 3.11 版本中新增。

--enable-wasm-pthreads

为 WASM 开启 pthreads 支持。

在 3.11 版本中新增。

3.3.6. 安装选项

--prefix=PREFIX

将与体系结构无关的文件安装在 PREFIX 中。在 Unix 上，它默认为 /usr/local。

此值可以在运行时使用 sys.prefix 检索。

例如，可以使用 --prefix="$HOME/.local/" 将 Python 安装到其主目录中。

--exec-prefix=EPREFIX

将与体系结构相关的文件安装在 EPREFIX 中，默认为 --prefix。

此值可以在运行时使用 sys.exec_prefix 检索。

--disable-test-modules

不构建也不安装测试模块，例如 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.3.7. 性能选项

建议使用 --enable-optimizations --with-lto（PGO + LTO）配置 Python 以获得最佳性能。实验性的 --enable-bolt 标志也可用于提高性能。

--enable-optimizations

使用 PROFILE_TASK 启用配置文件引导优化 (PGO)（默认禁用）。

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

如果使用 --enable-shared 且使用 GCC，也禁用 libpython 中的语义插入：将 -fno-semantic-interposition 添加到编译器和链接器标志中。

备注

在构建过程中，您可能会遇到关于某些源文件没有可用配置文件数据的编译器警告。这些警告是无害的，因为在配置文件数据获取期间只执行了代码的一个子集。要在 Clang 上禁用这些警告，请手动添加 -Wno-profile-instr-unprofiled 到 CFLAGS 来抑制它们。

在 3.6 版本加入。

3.10 版中已更改: 在 GCC 上使用 -fno-semantic-interposition。

PROFILE_TASK

Makefile 中使用的环境变量：用于 PGO 生成任务的 Python 命令行参数。

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

在 3.8 版本加入。

3.13 版中已更改: 任务失败不再静默忽略。

--with-lto=[full|thin|no|yes]

在任何构建中启用链接时间优化 (LTO)（默认禁用）。

C 编译器 Clang 需要 llvm-ar 进行 LTO（macOS 上为 ar），以及支持 LTO 的链接器（ld.gold 或 lld）。

在 3.6 版本加入。

3.11 新版功能: 要使用 ThinLTO 功能，请在 Clang 上使用 --with-lto=thin。

3.12 版中已更改: 如果编译器接受该标志，则在 Clang 上使用 ThinLTO 作为默认优化策略。

--enable-bolt

启用使用 BOLT 后链接二进制优化器（默认禁用）。

BOLT 是 LLVM 项目的一部分，但并非总是包含在它们的二进制发行版中。此标志要求 llvm-bolt 和 merge-fdata 可用。

BOLT 仍然是一个相当新的项目，因此此标志目前应被视为实验性。由于此工具在机器代码上运行，其成功取决于构建环境 + 其他优化配置参数 + CPU 架构的组合，并非所有组合都受支持。LLVM 16 之前的 BOLT 版本已知在某些情况下会导致 BOLT 崩溃。强烈建议使用 LLVM 16 或更新版本进行 BOLT 优化。

可以定义 BOLT_INSTRUMENT_FLAGS 和 BOLT_APPLY_FLAGS configure 变量，以分别覆盖 llvm-bolt 用于检测二进制文件和将 BOLT 数据应用于二进制文件的默认参数集。

3.12 新版功能.

BOLT_APPLY_FLAGS

创建 BOLT 优化二进制文件时传递给 llvm-bolt 的参数。

3.12 新版功能.

BOLT_INSTRUMENT_FLAGS

检测二进制文件时传递给 llvm-bolt 的参数。

3.12 新版功能.

--with-computed-gotos

在评估循环中启用计算 goto（在支持的编译器上默认启用）。

--with-tail-call-interp

启用在 CPython 中使用尾调用（tail calls）的解释器。如果启用，强烈建议启用 PGO（--enable-optimizations）。此选项特别需要支持适当尾调用的 C 编译器和 preserve_none 调用约定。例如，Clang 19 及更高版本支持此功能。

在 3.14 版本加入。

--without-mimalloc

禁用快速 mimalloc 分配器（默认启用）。

另请参阅 PYTHONMALLOC 环境变量。

--without-pymalloc

禁用专用 Python 内存分配器 pymalloc（默认启用）。

另请参阅 PYTHONMALLOC 环境变量。

--without-doc-strings

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

不定义 WITH_DOC_STRINGS 宏。

请参阅 PyDoc_STRVAR() 宏。

--enable-profiling

使用 gprof 启用 C 级代码分析（默认禁用）。

--with-strict-overflow

将 -fstrict-overflow 添加到 C 编译器标志（默认我们添加 -fno-strict-overflow）。

--without-remote-debug

停用 PEP 768 中描述的远程调试支持（默认启用）。当提供此标志时，允许解释器在单独进程中调度 Python 文件执行的代码（如 PEP 768 中所述）不会被编译。这包括调度要执行的代码的功能和接收要执行的代码的功能。

Py_REMOTE_DEBUG

除非 Python 配置了 --without-remote-debug，否则此宏默认定义。

请注意，即使定义了宏，远程调试也可能不可用（例如，在不兼容的平台上）。

在 3.14 版本加入。

3.3.8. Python 调试构建

调试构建是使用 --with-pydebug 配置选项构建的 Python。

调试构建的影响

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

  • 向 sys.abiflags 添加 d。

  • 添加 sys.gettotalrefcount() 函数。

  • 添加 -X showrefcount 命令行选项。

  • 添加 -d 命令行选项和 PYTHONDEBUG 环境变量以调试解析器。

  • 添加对 __lltrace__ 变量的支持：如果定义了该变量，则在字节码评估循环中启用低级跟踪。

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

  • 定义 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 选项）。

3.3.9. 调试选项

--with-pydebug

在调试模式下构建 Python：定义 Py_DEBUG 宏（默认禁用）。

--with-trace-refs

启用跟踪引用以用于调试目的（默认禁用）。

影响

PYTHONDUMPREFS 环境变量可用于在 Python 退出时转储仍然存活的对象和引用计数。

静态分配的对象 不会被跟踪。

在 3.8 版本加入。

3.13 版中已更改: 此构建现在与发布构建和 调试构建 ABI 兼容。

--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（默认禁用）。为了提高 ASan 检测能力，您可能还需要将其与 --without-pymalloc 结合使用，以禁用专门的小对象分配器，其分配不被 ASan 跟踪。

在 3.6 版本加入。

--with-memory-sanitizer

启用 MemorySanitizer 分配错误检测器 msan（默认禁用）。

在 3.6 版本加入。

--with-undefined-behavior-sanitizer

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

在 3.6 版本加入。

--with-thread-sanitizer

启用 ThreadSanitizer 数据竞争检测器 tsan（默认禁用）。

在 3.13 版本加入。

3.3.10. 链接器选项

--enable-shared

启用构建共享 Python 库：libpython（默认禁用）。

--without-static-libpython

不构建 libpythonMAJOR.MINOR.a 并且不安装 python.o（默认构建和启用）。

在 3.10 版本加入。

3.3.11. 库选项

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

链接到附加库（默认禁用）。

--with-system-expat

使用已安装的 expat 库构建 pyexpat 模块（默认禁用）。

--with-system-libmpdec

使用已安装的 mpdecimal 库构建 _decimal 扩展模块，请参阅 decimal 模块（默认启用）。

在 3.3 版本加入。

3.13 版中已更改: 默认使用已安装的 mpdecimal 库。

自 3.13 版起已废弃，并将在 3.16 版中移除: mpdecimal 库的副本将不再随 Python 3.16 一起分发。

参见

LIBMPDEC_CFLAGS 和 LIBMPDEC_LIBS。

--with-readline=readline|editline

为 readline 模块指定后端库。

  • readline：使用 readline 作为后端。

  • editline：使用 editline 作为后端。

在 3.10 版本加入。

--without-readline

不构建 readline 模块（默认构建）。

不定义 HAVE_LIBREADLINE 宏。

在 3.10 版本加入。

--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.3.12. 安全选项

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

选择用于 Python/pyhash.c 中的哈希算法

  • siphash13（默认）；

  • siphash24;

  • fnv.

在 3.4 版本加入。

3.11 新版功能: 添加了 siphash13，它是新的默认值。

--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 设置为最低协议版本。

--disable-safety

禁用 OpenSSF 为安全原因推荐的、没有性能开销的编译器选项。如果未启用此选项，CPython 将基于没有速度下降的安全编译器选项进行构建。启用此选项时，CPython 将不会使用下面列出的编译器选项进行构建。

以下编译器选项在使用 --disable-safety 时被禁用

在 3.14 版本加入。

--enable-slower-safety

启用 OpenSSF 为安全原因推荐的、需要额外开销的编译器选项。如果未启用此选项，CPython 将不会基于对性能有影响的安全编译器选项进行构建。启用此选项时，CPython 将使用下面列出的编译器选项进行构建。

以下编译器选项在使用 --enable-slower-safety 时被启用

  • -D_FORTIFY_SOURCE=3: 使用编译时和运行时检查来加固不安全的 libc 用法和缓冲区溢出。

在 3.14 版本加入。

3.3.13. 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 (x86-64 和 arm64);

  • 32-bit (PPC 和 i386);

  • 64-bit (PPC64 和 x86-64);

  • 3-way (i386, PPC 和 x86-64);

  • intel (i386 和 x86-64);

  • intel-32 (i386);

  • intel-64 (x86-64);

  • all (PPC, i386, PPC64 和 x86-64)。

请注意，此配置项的值与 macOS 上通用二进制轮子使用的标识符 不 相同。有关 macOS 上使用的打包平台兼容性标签 的详细信息，请参见 Python 打包用户指南。

--with-framework-name=FRAMEWORK

指定 macOS 上 Python framework 的名称，仅在设置 --enable-framework 时有效（默认值：Python）。

--with-app-store-compliance
--with-app-store-compliance=PATCH-FILE

Python 标准库包含的字符串在提交到 macOS 和 iOS App Store 进行分发时已知会触发自动化检查工具错误。如果启用此选项，将应用已知能纠正 App Store 合规性的补丁列表。也可以指定自定义补丁文件。此选项默认禁用。

在 3.13 版本加入。

3.3.14. iOS 选项

参见 iOS/README.rst。

--enable-framework=INSTALLDIR

创建 Python.framework。与 macOS 不同，指定安装路径的 INSTALLDIR 参数是强制性的。

--with-framework-name=FRAMEWORK

指定 framework 的名称（默认值：Python）。

3.3.15. 交叉编译选项

交叉编译，也称为交叉构建，可用于为其他 CPU 架构或平台构建 Python。交叉编译需要用于构建平台的 Python 解释器。构建 Python 的版本必须与交叉编译的主机 Python 的版本匹配。

--build=BUILD

为 BUILD 上的构建进行配置，通常由 config.guess 推断。

--host=HOST

交叉编译以构建在 HOST（目标平台）上运行的程序

--with-build-python=path/to/python

用于交叉编译的构建 python 二进制文件的路径

在 3.11 版本中新增。

CONFIG_SITE=file

指向包含配置覆盖的文件名的环境变量。

示例 config.site 文件

# config.site-aarch64
ac_cv_buggy_getaddrinfo=no
ac_cv_file__dev_ptmx=yes
ac_cv_file__dev_ptc=no
HOSTRUNNER

用于交叉编译的主机平台运行 CPython 的程序。

在 3.11 版本中新增。

交叉编译示例

CONFIG_SITE=config.site-aarch64 ../configure \
    --build=x86_64-pc-linux-gnu \
    --host=aarch64-unknown-linux-gnu \
    --with-build-python=../x86_64/python

3.4. Python 构建系统

3.4.1. 构建系统主要文件

  • configure.ac => configure;

  • Makefile.pre.in => Makefile (由 configure 创建);

  • pyconfig.h (由 configure 创建);

  • Modules/Setup: 通过 Makefile 使用 Module/makesetup shell 脚本构建的 C 扩展；

3.4.2. 主要构建步骤

  • C 文件 (.c) 被构建为对象文件 (.o)。

  • 从对象文件创建静态 libpython 库 (.a)。

  • python.o 和静态 libpython 库被链接到最终的 python 程序中。

  • C 扩展由 Makefile 构建（参见 Modules/Setup）。

3.4.3. 主要 Makefile 目标

3.4.3.1. make

在编辑一些代码或从上游刷新检出后重新构建时，大多数情况下，您只需要执行 make，它（根据 Make 的语义）会构建默认目标，即 Makefile 中定义的第一个目标。按照传统（包括在 CPython 项目中），这通常是 all 目标。configure 脚本扩展了一个 autoconf 变量 @DEF_MAKE_ALL_RULE@，以精确描述 make all 将构建哪些目标。有三种选择：

  • profile-opt（使用 --enable-optimizations 配置）

  • build_wasm（如果主机平台匹配 wasm32-wasi* 或 wasm32-emscripten 则选择）

  • build_all（未明确使用其他任何选项进行配置）

根据最近的源文件更改，Make 将重新构建任何被视为过时的目标（对象文件和可执行文件），必要时还会再次运行 configure。然而，源/目标依赖项众多且是手动维护的，因此 Make 有时无法获得正确检测所有需要重新构建的目标所需的所有信息。根据未重新构建的目标，您可能会遇到一些问题。如果您遇到无法解释的构建或测试问题，make clean && make 应该可以解决大多数依赖项问题，但会增加构建时间。

3.4.3.2. make platform

构建 python 程序，但不构建标准库扩展模块。这将生成一个名为 platform 的文件，其中包含一行描述构建平台详细信息的内容，例如 macosx-14.3-arm64-3.12 或 linux-x86_64-3.13。

3.4.3.3. make profile-opt

使用配置文件引导优化 (PGO) 构建 Python。您可以使用配置选项 --enable-optimizations 使其成为 make 命令（make all 或仅仅 make）的默认目标。

3.4.3.4. make clean

移除已构建文件。

3.4.3.5. make distclean

除了 make clean 完成的工作外，还移除由 configure 脚本创建的文件。configure 必须在再次构建之前运行。[1]

3.4.3.6. make install

构建 all 目标并安装 Python。

3.4.3.7. make test

构建 all 目标并使用 --fast-ci 选项运行 Python 测试套件，不包括 GUI 测试。变量：

  • TESTOPTS: 额外的 regrtest 命令行选项。

  • TESTPYTHONOPTS: 额外的 Python 命令行选项。

  • TESTTIMEOUT: 超时时间（秒）（默认：10 分钟）。

3.4.3.8. make ci

这类似于 make test，但使用 -ugui 也运行 GUI 测试。

在 3.14 版本加入。

3.4.3.9. make buildbottest

这类似于 make test，但使用 --slow-ci 选项和默认 20 分钟的超时时间，而不是 --fast-ci 选项。

3.4.3.10. make regen-all

重新生成（几乎）所有生成的文件。其中包括（但不限于）字节码用例和解析器生成器文件。make regen-stdlib-module-names 和 autoconf 必须为剩余的生成文件单独运行。

3.4.4. C 扩展

一些 C 扩展被构建为内置模块，例如 sys 模块。它们在定义了 Py_BUILD_CORE_BUILTIN 宏的情况下构建。内置模块没有 __file__ 属性。

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

其他 C 扩展被构建为动态库，例如 _asyncio 模块。它们在定义了 Py_BUILD_CORE_MODULE 宏的情况下构建。Linux x86-64 上的示例：

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

Modules/Setup 用于生成 Makefile 目标以构建 C 扩展。在文件开头，C 扩展作为内置模块构建。在 *shared* 标记之后定义的扩展作为动态库构建。

Include/exports.h 中的 PyAPI_FUNC()、PyAPI_DATA() 和 PyMODINIT_FUNC 宏的定义取决于是否定义了 Py_BUILD_CORE_MODULE 宏。

  • 如果定义了 Py_BUILD_CORE_MODULE，则使用 Py_EXPORTED_SYMBOL。

  • 否则使用 Py_IMPORTED_SYMBOL。

如果在作为共享库构建的 C 扩展上错误地使用了 Py_BUILD_CORE_BUILTIN 宏，其 PyInit_xxx() 函数将不会导出，导致导入时出现 ImportError。

3.5. 编译器和链接器标志

由 ./configure 脚本和环境变量设置并由 Makefile 使用的选项。

3.5.1. 预处理器标志

CONFIGURE_CPPFLAGS

传递给 ./configure 脚本的 CPPFLAGS 变量的值。

在 3.6 版本加入。

CPPFLAGS

(Objective) C/C++ 预处理器标志，例如，如果您在非标准目录 include_dir 中有头文件，则为 -Iinclude_dir。

CPPFLAGS 和 LDFLAGS 都需要包含 shell 的值，以便能够使用环境变量中指定的目录构建扩展模块。

BASECPPFLAGS

在 3.4 版本加入。

PY_CPPFLAGS

为构建解释器对象文件而添加的额外预处理器标志。

默认值：$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)。

在 3.2 版本加入。

3.5.2. 编译器标志

CC

C 编译器命令。

示例：gcc -pthread。

CXX

C++ 编译器命令。

示例：g++ -pthread。

CFLAGS

C 编译器标志。

CFLAGS_NODIST

CFLAGS_NODIST 用于构建解释器和标准库 C 扩展。当编译器标志在 Python 安装后 不应 成为 CFLAGS 的一部分时使用（gh-65320）。

特别是，CFLAGS 不应包含：

  • 编译器标志 -I（用于设置包含文件的搜索路径）。-I 标志从左到右处理，CFLAGS 中的任何标志都将优先于用户和包提供的 -I 标志。

  • 强化标志，例如 -Werror，因为发行版无法控制用户安装的包是否符合此类更高的标准。

在 3.5 版本加入。

COMPILEALL_OPTS

在 make install 中构建 PYC 文件时传递给 compileall 命令行的选项。默认值：-j0。

3.12 新版功能.

EXTRA_CFLAGS

额外的 C 编译器标志。

CONFIGURE_CFLAGS

传递给 ./configure 脚本的 CFLAGS 变量的值。

在 3.2 版本加入。

CONFIGURE_CFLAGS_NODIST

传递给 ./configure 脚本的 CFLAGS_NODIST 变量的值。

在 3.5 版本加入。

BASECFLAGS

基本编译器标志。

OPT

优化标志。

CFLAGS_ALIASING

用于编译 Python/dtoa.c 的严格或非严格别名标志。

在 3.7 版本加入。

CCSHARED

用于构建共享库的编译器标志。

例如，在 Linux 和 BSD 上使用 -fPIC。

CFLAGSFORSHARED

为构建解释器对象文件而添加的额外 C 标志。

默认值：当使用 --enable-shared 时为 $(CCSHARED)，否则为空字符串。

PY_CFLAGS

默认值：$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)。

PY_CFLAGS_NODIST

默认值：$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal。

在 3.5 版本加入。

PY_STDMODULE_CFLAGS

用于将标准库扩展模块构建为内置模块的 C 标志，例如 posix 模块。

默认值：$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)。

在 3.7 版本加入。

PY_CORE_CFLAGS

默认值：$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE。

在 3.2 版本加入。

PY_BUILTIN_MODULE_CFLAGS

用于将标准库扩展模块构建为内置模块的编译器标志，例如 posix 模块。

默认值：$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN。

在 3.8 版本加入。

PURIFY

Purify 命令。Purify 是一个内存调试程序。

默认值：空字符串（未使用）。

3.5.3. 链接器标志

LINKCC

用于构建 python 和 _testembed 等程序的链接器命令。

默认值：$(PURIFY) $(CC)。

CONFIGURE_LDFLAGS

传递给 ./configure 脚本的 LDFLAGS 变量的值。

避免赋值 CFLAGS, LDFLAGS 等，这样用户可以在命令行上使用它们来追加这些值而不会覆盖预设值。

在 3.2 版本加入。

LDFLAGS_NODIST

LDFLAGS_NODIST 的用法与 CFLAGS_NODIST 相同。当链接器标志在 Python 安装后 不应 成为 LDFLAGS 的一部分时使用（gh-65320）。

特别是，LDFLAGS 不应包含：

  • 编译器标志 -L（用于设置库的搜索路径）。-L 标志从左到右处理，LDFLAGS 中的任何标志都将优先于用户和包提供的 -L 标志。

CONFIGURE_LDFLAGS_NODIST

传递给 ./configure 脚本的 LDFLAGS_NODIST 变量的值。

在 3.8 版本加入。

LDFLAGS

链接器标志，例如，如果您在非标准目录 lib_dir 中有库，则为 -Llib_dir。

CPPFLAGS 和 LDFLAGS 都需要包含 shell 的值，以便能够使用环境变量中指定的目录构建扩展模块。

LIBS

将库传递给链接器以链接 Python 可执行文件时的链接器标志。

示例：-lrt。

LDSHARED

用于构建共享库的命令。

默认值：@LDSHARED@ $(PY_LDFLAGS)。

BLDSHARED

用于构建 libpython 共享库的命令。

默认值：@BLDSHARED@ $(PY_CORE_LDFLAGS)。

PY_LDFLAGS

默认值：$(CONFIGURE_LDFLAGS) $(LDFLAGS)。

PY_LDFLAGS_NODIST

默认值：$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)。

在 3.8 版本加入。

PY_CORE_LDFLAGS

用于构建解释器对象文件的链接器标志。

在 3.8 版本加入。

脚注