3. 配置 Python

3.1. 建置需求

Features and minimum versions required to build CPython:

• C11 编译器。 可选的 C11 特性 不是必须的。

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

• 对 IEEE 754 浮点数和 浮点 Not-a-Number (NaN) 的支持。

• thread 的支援。

• OpenSSL 1.1.1 is the minimum version and OpenSSL 3.0.9 is the recommended minimum version for the ssl and hashlib extension modules.

• SQLite 3.15.2 for the sqlite3 extension module.

• Tcl/Tk 8.5.12 for the tkinter module.

• Autoconf 2.71 and aclocal 1.16.4 are required to regenerate the configure script.

在 3.1 版的變更: Tcl/Tk version 8.3.1 is now required.

在 3.5 版的變更: On Windows, Visual Studio 2015 or later is now required. Tcl/Tk version 8.4 is now required.

在 3.6 版的變更: 现在要求选定的 C99 特性，如 <stdint.h> 和 static inline 函数。

在 3.7 版的變更: 對執行緒與 OpenSSL 1.0.2 的支援現在是必要的。

在 3.10 版的變更: OpenSSL 1.1.1 is now required. Require SQLite 3.7.15.

在 3.11 版的變更: C11 compiler, IEEE 754 and NaN support are now required. On Windows, Visual Studio 2017 or later is required. Tcl/Tk version 8.5.12 is now required for the tkinter module.

在 3.13 版的變更: Autoconf 2.71, aclocal 1.16.4 and SQLite 3.15.2 are now required.

另请参阅 PEP 7 "Style Guide for C Code" 和 PEP 11 "CPython platform support"。

3.2. 產生的檔案

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

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

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

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. 設定選項

List all configure script options using:

./configure --help

請見 Python 原始碼發行版中的 Misc/SpecialBuilds.txt。

3.3.1. 一般選項

--enable-loadable-sqlite-extensions

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

請見 sqlite3 模組的 sqlite3.Connection.enable_load_extension() 方法。

Added in version 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 node 上為 .js、在 Emscripten 瀏覽器為 .html、在 WASI 上為 .wasm，以及在其他平台為空字串（python 執行檔）。

在 3.11 版的變更: 在 WASM 平台上預設的後綴是 .js、.html 或 .wasm 中的一個。

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

Select the default time zone search path for为 zoneinfo.TZPATH 选择默认的时区搜索路径。 参见 zoneinfo 模块的 编译时配置。

預設值：/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo。

請見 os.pathsep 路徑分隔符號。

Added in version 3.9.

--without-decimal-contextvar

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

請見 decimal.HAVE_CONTEXTVAR 與 contextvars 模組。

Added in version 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。

--without-freelists

禁用除空元组单例以外的所有自由列表。Disable all freelists except the empty tuple singleton.

Added in version 3.11.

--with-platlibdir=DIRNAME

Python 函式庫目錄名稱（預設為 lib ）。

Fedora 和 SuSE 在 64 位元平台上使用 lib64。

參閱 sys.platlibdir。

Added in version 3.9.

--with-wheel-pkg-dir=PATH

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

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

Added in version 3.10.

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

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

• check （預設）：pkg-config 是可選的

• yes：pkg-config 是必要的

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

Added in version 3.11.

--enable-pystats

Turn on internal Python performance statistics gathering.

By default, statistics gathering is off. Use python3 -X pystats command or set PYTHONSTATS=1 environment variable to turn on statistics gathering at Python startup.

At Python exit, dump statistics if statistics gathering was on and not cleared.

效果如下：

• Add -X pystats command line option.

• Add PYTHONSTATS environment variable.

• Define the Py_STATS macro.

• Add functions to the sys module:

  • sys._stats_on(): Turns on statistics gathering.

  • sys._stats_off(): Turns off statistics gathering.

  • sys._stats_clear(): Clears the statistics.

  • sys._stats_dump(): Dump statistics to file, and clears the statistics.

The statistics will be dumped to a arbitrary (probably unique) file in /tmp/py_stats/ (Unix) or C:\temp\py_stats\ (Windows). If that directory does not exist, results will be printed on stderr.

使用 Tools/scripts/summarize_stats.py 來讀取統計資料。

Statistics:

• Opcode:

  • Specialization: success, failure, hit, deferred, miss, deopt, failures;

  • Execution count;

  • Pair count.

• Call:

  • Inlined Python calls;

  • PyEval calls;

  • Frames pushed;

  • Frame object created;

  • Eval calls: vector, generator, legacy, function VECTORCALL, build class, slot, function "ex", API, method.

• Object:

  • incref and decref;

  • interpreter incref and decref;

  • allocations: all, 512 bytes, 4 kiB, big;

  • free;

  • to/from free lists;

  • dictionary materialized/dematerialized;

  • type cache;

  • optimization attempts;

  • optimization traces created/executed;

  • uops executed.

• Garbage collector:

  • Garbage collections;

  • Objects visited;

  • Objects collected.

Added in version 3.11.

--disable-gil

Enables experimental support for running Python without the global interpreter lock (GIL): free threading build.

Defines the Py_GIL_DISABLED macro and adds "t" to sys.abiflags.

See 自由线程的 CPython for more detail.

Added in version 3.13.

PKG_CONFIG

Path to pkg-config utility.

PKG_CONFIG_LIBDIR

PKG_CONFIG_PATH

pkg-config options.

3.3.2. C compiler options

CC

C 編譯器指令。

CFLAGS

C 編譯器旗標。

CPP

C preprocessor command.

CPPFLAGS

C preprocessor flags, e.g. -Iinclude_dir.

3.3.3. 链接器选项

LDFLAGS

Linker flags, e.g. -Llibrary_directory.

LIBS

Libraries to pass to the linker, e.g. -llibrary.

MACHDEP

Name for machine-dependent library files.

3.3.4. Options for third-party dependencies

Added in version 3.11.

BZIP2_CFLAGS

BZIP2_LIBS

C compiler and linker flags to link Python to libbz2, used by bz2 module, overriding pkg-config.

CURSES_CFLAGS

CURSES_LIBS

C compiler and linker flags for libncurses or libncursesw, used by curses module, overriding pkg-config.

GDBM_CFLAGS

GDBM_LIBS

C compiler and linker flags for gdbm.

LIBB2_CFLAGS

LIBB2_LIBS

C compiler and linker flags for libb2 (BLAKE2), used by hashlib module, overriding pkg-config.

LIBEDIT_CFLAGS

LIBEDIT_LIBS

C compiler and linker flags for libedit, used by readline module, overriding pkg-config.

LIBFFI_CFLAGS

LIBFFI_LIBS

C compiler and linker flags for libffi, used by ctypes module, overriding pkg-config.

LIBMPDEC_CFLAGS

LIBMPDEC_LIBS

C compiler and linker flags for libmpdec, used by decimal module, overriding pkg-config.

備註

These environment variables have no effect unless --with-system-libmpdec is specified.

LIBLZMA_CFLAGS

LIBLZMA_LIBS

C compiler and linker flags for liblzma, used by lzma module, overriding pkg-config.

LIBREADLINE_CFLAGS

LIBREADLINE_LIBS

C compiler and linker flags for libreadline, used by readline module, overriding pkg-config.

LIBSQLITE3_CFLAGS

LIBSQLITE3_LIBS

C compiler and linker flags for libsqlite3, used by sqlite3 module, overriding pkg-config.

LIBUUID_CFLAGS

LIBUUID_LIBS

C compiler and linker flags for libuuid, used by uuid module, overriding pkg-config.

PANEL_CFLAGS

PANEL_LIBS

C compiler and Linker flags for PANEL, overriding pkg-config.

C compiler and linker flags for libpanel or libpanelw, used by curses.panel module, overriding pkg-config.

TCLTK_CFLAGS

TCLTK_LIBS

C compiler and linker flags for TCLTK, overriding pkg-config.

ZLIB_CFLAGS

ZLIB_LIBS

C compiler and linker flags for libzlib, used by gzip module, overriding pkg-config.

3.3.5. WebAssembly 選項

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

为 wasm32-emscripten 设置生成风格。

• browser (默认值): 预加载最小 stdlib，默认 MEMFS。

• node：對 NODERAWFS 和 pthread 支援。

Added in version 3.11.

--enable-wasm-dynamic-linking

为 WASM 启用动态链接支持。

动态链接启用 dlopen。 可执行文件的大小将由于限制死代码清理和附加特性而增加。

Added in version 3.11.

--enable-wasm-pthreads

为 WASM 启用 pthreads 支持。

Added in version 3.11.

3.3.6. 安裝選項

--prefix=PREFIX

在 PREFIX 中安装架构无关的文件。 在 Unix 上，它默认为 /usr/local。

這個值可以在 runtime 使用 sys.prefix 取得。

作为示例，用户可以使用 --prefix="$HOME/.local/" 在其家目录中安装 Python。

--exec-prefix=EPREFIX

在 EPREFIX 中安装架构无关的文件，默认为 --prefix。

這個值可以在 runtime 使用 sys.exec_prefix 取得

--disable-test-modules

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

Added in version 3.10.

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

選擇在 Python 安裝時執行的 ensurepip 命令：

• upgrade （預設）：執行 python -m ensurepip --altinstall --upgrade 命令。

• install：執行 python -m ensurepip --altinstall 命令；

• no：不要執行 ensurepip；

Added in version 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 也需要用到它：在 macOS 上 GCC 只是 Clang 的别名而已。

如果使用 --enable-shared 和 GCC ，还可以禁用 libpython 中的语义插值：在编译器和链接器的标志中加入 -fno-semantic-interposition 。

備註

在构建期间，你可能会遇到编译器警告提示某些源文件的配置数据不可用。 这些警告是无害的，因为在获取配置数据时只有一部分代码会被使用。 要在 Clang 上禁用这些警告，可通过在 CFLAGS 中添加 -Wno-profile-instr-unprofiled 来手动抑制它们。

Added in version 3.6.

在 3.10 版的變更: 在 GCC 上使用 -fno-semantic-interposition。

PROFILE_TASK

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

預設值：-m test --pgo --timeout=$(TESTTIMEOUT)。

Added in version 3.8.

在 3.13 版的變更: Task failure is no longer ignored silently.

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

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

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

Added in version 3.6.

Added in version 3.11: 要使用 ThinLTO 特性，请在 Clang 上使用 --with-lto=thin。

在 3.12 版的變更: 如果编译器支持将使用 ThinLTO 旗标作为 Clang 上的默认优化策略。

--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 数据应用于二进制代码中。

Added in version 3.12.

BOLT_APPLY_FLAGS

Arguments to llvm-bolt when creating a BOLT optimized binary.

Added in version 3.12.

BOLT_INSTRUMENT_FLAGS

Arguments to llvm-bolt when instrumenting binaries.

Added in version 3.12.

--with-computed-gotos

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

--without-mimalloc

Disable the fast mimalloc allocator mimalloc (enabled by default).

另請參閱 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 调试级编译

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

调试版本的效果：

• 默认显示所有警告：在 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 版的變更: Release builds and debug builds are now ABI compatible: defining the Py_DEBUG macro no longer implies the Py_TRACE_REFS macro (see the --with-trace-refs option).

3.3.9. 调试选项

--with-pydebug

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

--with-trace-refs

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

效果如下：

• 定義 Py_TRACE_REFS 巨集。

• 新增 sys.getobjects() 函式。

• 新增 PYTHONDUMPREFS 環境變數。

The PYTHONDUMPREFS environment variable can be used to dump objects and reference counts still alive at Python exit.

Statically allocated objects are not traced.

Added in version 3.8.

在 3.13 版的變更: This build is now ABI compatible with release build and debug build.

--with-assertions

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

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

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

Added in version 3.6.

--with-valgrind

啟用 Valgrind 支援（預設不啟用）。

--with-dtrace

啟用 DTrace 支援（預設不啟用）。

参阅 用 DTrace 和 SystemTap 测试 CPython。

Added in version 3.6.

--with-address-sanitizer

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

Added in version 3.6.

--with-memory-sanitizer

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

Added in version 3.6.

--with-undefined-behavior-sanitizer

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

Added in version 3.6.

--with-thread-sanitizer

Enable ThreadSanitizer data race detector, tsan (default is no).

Added in version 3.13.

3.3.10. 链接器选项

--enable-shared

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

--without-static-libpython

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

Added in version 3.10.

3.3.11. 函式庫選項

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

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

--with-system-expat

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

--with-system-libmpdec

Build the _decimal extension module using an installed mpdecimal library, see the decimal module (default is yes).

Added in version 3.3.

在 3.13 版的變更: Default to using the installed mpdecimal library.

自從版本 3.13 後不推薦使用，將會自版本 3.15 中移除。: A copy of the mpdecimal library sources will no longer be distributed with Python 3.15.

也參考

LIBMPDEC_CFLAGS and LIBMPDEC_LIBS.

--with-readline=readline|editline

Designate a backend library for the readline module.

• readline: Use readline as the backend.

• editline: Use editline as the backend.

Added in version 3.10.

--without-readline

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

不要定義 HAVE_LIBREADLINE 巨集。

Added in version 3.10.

--with-libm=STRING

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

--with-libc=STRING

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

--with-openssl=DIR

OpenSSL 的根目录。

Added in version 3.7.

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

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

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

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

• DIR ：直接设置 rpath。

Added in version 3.10.

3.3.12. 安全性选项

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

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

• siphash13 (默认值);

• siphash24；

• fnv。

Added in version 3.4.

Added in version 3.11: 增加了 siphash13 并且是新的默认值。

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

內建雜湊模組：

• md5；

• sha1；

• sha256；

• sha512；

• sha3 (带 shake)。

• blake2。

Added in version 3.9.

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

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

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

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

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

請見 ssl 模組。

Added in version 3.7.

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

3.3.13. macOS 選項

See 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.3.14. iOS Options

See iOS/README.rst.

--enable-framework=INSTALLDIR

Create a Python.framework. Unlike macOS, the INSTALLDIR argument specifying the installation path is mandatory.

--with-framework-name=FRAMEWORK

Specify the name for the framework (default: Python).

3.3.15. 交叉编译选项

交叉编译，或称交叉构建，可被用于为不同的 CPU 架构或平台构建 Python。 交叉编译需要一个针对构建平台的 Python 解释器。 构建的 Python 版本必须与交叉编译的主机 Python 版本相匹配。

--build=BUILD

用于在 BUILD 上执行构建的配置，通常由 config.guess 通过推测得到。

--host=HOST

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

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

针对交叉编译构建 python 二进制文件的路径

Added in version 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

Program to run CPython for the host platform for cross-compilation.

Added in version 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 (created by 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

For the most part, when rebuilding after editing some code or refreshing your checkout from upstream, all you need to do is execute make, which (per Make's semantics) builds the default target, the first one defined in the Makefile. By tradition (including in the CPython project) this is usually the all target. The configure script expands an autoconf variable, @DEF_MAKE_ALL_RULE@ to describe precisely which targets make all will build. The three choices are:

• profile-opt (configured with --enable-optimizations)

• build_wasm (configured with --with-emscripten-target)

• build_all (configured without explicitly using either of the others)

Depending on the most recent source file changes, Make will rebuild any targets (object files and executables) deemed out-of-date, including running configure again if necessary. Source/target dependencies are many and maintained manually however, so Make sometimes doesn't have all the information necessary to correctly detect all targets which need to be rebuilt. Depending on which targets aren't rebuilt, you might experience a number of problems. If you have build or test problems which you can't otherwise explain, make clean && make should work around most dependency problems, at the expense of longer build times.

3.4.3.2. make platform

Build the python program, but don't build the standard library extension modules. This generates a file named platform which contains a single line describing the details of the build platform, e.g., macosx-14.3-arm64-3.12 or linux-x86_64-3.13.

3.4.3.3. 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).

3.4.3.4. make clean

Remove built files.

3.4.3.5. make distclean

In addition to the the work done by make clean, remove files created by the configure script. configure will have to be run before building again. [1]

3.4.3.6. make install

Build the all target and install Python.

3.4.3.7. make test

Build the all target and run the Python test suite with the --fast-ci option. Variables:

• TESTOPTS: additional regrtest command-line options.

• TESTPYTHONOPTS: additional Python command-line options.

• TESTTIMEOUT: timeout in seconds (default: 10 minutes).

3.4.3.8. make buildbottest

This is similar to make test, but uses the --slow-ci option and default timeout of 20 minutes, instead of --fast-ci option.

3.4.3.9. make regen-all

Regenerate (almost) all generated files. These include (but are not limited to) bytecode cases, and parser generator file. make regen-stdlib-module-names and autoconf must be run separately for the remaining generated files.

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。

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

3.5. 编译器和链接器的标志

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

3.5.1. 预处理器的标志

CONFIGURE_CPPFLAGS

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

Added in version 3.6.

CPPFLAGS

(Objective) C/C++ 预处理器标志，例如，如果头文件位于非标准的目录 include_dir 中，请使用 -Iinclude_dir 。

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

BASECPPFLAGS

Added in version 3.4.

PY_CPPFLAGS

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

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

Added in version 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 中的任何旗标都将优先于 user- 和 package- 层级所提供的 -I 旗标。

• 加固旗标如 -Werror 因为分发版无法控制由用户安装的包是否符合这样的高标准。

Added in version 3.5.

COMPILEALL_OPTS

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

Added in version 3.12.

EXTRA_CFLAGS

額外的 C 編譯器旗標。

CONFIGURE_CFLAGS

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

Added in version 3.2.

CONFIGURE_CFLAGS_NODIST

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

Added in version 3.5.

BASECFLAGS

基本編譯器旗標。

OPT

最佳化旗標。

CFLAGS_ALIASING

严格或不严格的别名标志，用于编译 Python/dtoa.c 、

Added in version 3.7.

CCSHARED

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

例如說 -fPIC 被使用於 Linux 與 BSD 上。

CFLAGSFORSHARED

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

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

PY_CFLAGS

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

PY_CFLAGS_NODIST

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

Added in version 3.5.

PY_STDMODULE_CFLAGS

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

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

Added in version 3.7.

PY_CORE_CFLAGS

默认为 $(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE 。

Added in version 3.2.

PY_BUILTIN_MODULE_CFLAGS

编译器标志，将标准库的扩展模块作为内置模块来构建，如 posix 模块

默认为： $(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN 。

Added in version 3.8.

PURIFY

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

默认为：空字符串（不使用）。

3.5.3. 链接器标志位

LINKCC

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

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

CONFIGURE_LDFLAGS

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

避免指定 CFLAGS ， LDFLAGS 等，这样用户就可以在命令行上使用它们来追加这些值，而不用触碰到预设的值。

Added in version 3.2.

LDFLAGS_NODIST

LDFLAGS_NODIST 的使用方式与 CFLAGS_NODIST 相同。 一旦装好 Python 则当某个链接器旗标 不应 成为 LDFLAGS 的一部分时将可使用它 (gh-65320)。

特别地，LDFLAGS 不应当包含:

• 编译器旗标 -L (用于为库设置搜索路径)。 -L 旗标将按从左到右的顺序处理，并且 LDFLAGS 中的任何旗标都将优先于 user- 和 package 层级所提供的 -L 旗标。

CONFIGURE_LDFLAGS_NODIST

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

Added in version 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)。

Added in version 3.8.

PY_CORE_LDFLAGS

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

Added in version 3.8.

备注

[1]

git clean -fdx is an even more extreme way to "clean" your checkout. It removes all files not known to Git. When bug hunting using git bisect, this is recommended between probes to guarantee a completely clean build. Use with care, as it will delete all files not checked into Git, including your new, uncommitted work.