3. 配置 Python

3.1. 构建要求

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

  • C11 编译器。不需要可选的 C11 特性。

  • 在 Windows 上，需要 Microsoft Visual Studio 2017 或更高版本。

  • 支持 IEEE 754 浮点数和 浮点数非数字 (NaN)。

  • 支持线程。

  • OpenSSL 1.1.1 是 ssl 和 hashlib 扩展模块的最低版本，建议最低版本为 OpenSSL 3.0.9。

  • sqlite3 扩展模块需要 SQLite 3.15.2。

  • tkinter 模块需要 Tcl/Tk 8.5.12。

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

在 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。

另请参阅 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. configure 脚本

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.Connection.enable_load_extension() 方法，来自 sqlite3 模块。

在 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 上为 .exe（python.exe 可执行文件），在 Emscripten 节点上为 .js，在 Emscripten 浏览器上为 .html，在 WASI 上为 .wasm，在其他平台上为空字符串（python 可执行文件）。

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

--with-tzpath=<以路径分隔符分隔的绝对路径列表>

为 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=<后端名称列表>

覆盖检查 dbm 模块的数据库后端顺序

有效值是以冒号 (:) 分隔的后端名称字符串

  • ndbm;

  • gdbm;

  • bdb.

--without-c-locale-coercion

禁用 C 语言环境强制转换为基于 UTF-8 的语言环境（默认启用）。

不要定义 PY_COERCE_C_LOCALE 宏。

请参阅 PYTHONCOERCECLOCALE 和 PEP 538。

--without-freelists

禁用除空元组单例之外的所有空闲列表。

在 3.11 版本中添加。

--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]

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

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

  • yes：pkg-config 是强制性的

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

在 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、方法。

  • 对象

    • incref 和 decref；

    • 解释器 incref 和 decref；

    • 分配：全部、512 字节、4 kiB、大；

    • 释放；

    • 到/从空闲列表；

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

    • 类型缓存；

    • 优化尝试；

    • 创建/执行的优化跟踪；

    • 执行的 uops。

  • 垃圾回收器

    • 垃圾回收；

    • 访问的对象；

    • 收集的对象。

在 3.11 版本中添加。

--disable-gil

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

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

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

在 3.13 版本中添加。

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

指示如何集成 JIT 编译器。

  • no - 构建不带 JIT 的解释器。

  • yes - 构建带有 JIT 的解释器。

  • yes-off - 构建带有 JIT 的解释器，但默认情况下禁用它。

  • interpreter - 构建不带 JIT 的解释器，但启用第 2 层解释器。

按照惯例，--enable-experimental-jit 是 --enable-experimental-jit=yes 的简写形式。

在 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。

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 选项

--with-emscripten-target=[browser|node]

为 wasm32-emscripten 设置构建风格。

  • browser（默认）：预加载最小的 stdlib，默认使用 MEMFS。

  • node：NODERAWFS 和 pthread 支持。

在 3.11 版本中添加。

--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（在受支持的编译器上默认启用）。

--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）。

3.3.8. Python 调试构建

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

调试构建的效果

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

  • 将 d 添加到 sys.abiflags。

  • 添加 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(...);。

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

另请参阅 --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 版本中添加。

--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.15 版本中删除: mpdecimal 库的源代码副本将不再与 Python 3.15 一起分发。

另请参阅

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

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;

  • 32 位;

  • 64 位;

  • 三向;

  • intel;

  • intel-32;

  • intel-64;

  • 全部.

--with-framework-name=FRAMEWORK

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

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

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

在 3.13 版本中添加。

3.3.14. iOS 选项

请参阅 iOS/README.rst。

--enable-framework=INSTALLDIR

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

--with-framework-name=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（使用 --with-emscripten-target 配置）

  • 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。您可以使用 configure --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 测试套件。 变量

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

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

  • TESTTIMEOUT: 超时时间（以秒为单位）（默认值：10 分钟）。

3.4.3.8. make buildbottest

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

3.4.3.9. 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* 标记之后定义的扩展被构建为动态库。

PyAPI_FUNC()、 PyAPI_DATA() 和 PyMODINIT_FUNC Include/exports.h 的宏根据是否定义了 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 用于构建解释器和 stdlib 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 标志。

默认值：$(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 版本中添加。

脚注