使用pyproject.toml/PEP518时，如何让Setuptools编译带调试符号的扩展？

当然可以在新规范下编译带调试符号的Python扩展，以下是两种可行的方案：

方案一：通过pip临时传递编译参数 #

使用pip install时，通过--config-setting参数向Setuptools的build_ext传递debug选项，格式需要用build_ext--<option>=<value>的形式：

pip install . --config-setting="build_ext--debug=1"

如果使用build工具直接构建分发包，命令为：

python -m build --config-setting="build_ext--debug=1"

该方式会临时启用调试编译，不会修改项目配置文件，适合临时排查问题。

方案二：在pyproject.toml中持久化配置 #

在项目的pyproject.toml中添加tool.setuptools.build_ext配置段，启用调试编译：

[tool.setuptools.build_ext]
debug = true

之后执行pip install .就会自动编译带调试符号的版本。如果需要恢复默认编译，只需删除或注释这段配置即可。

为什么之前的尝试失败？ #

• pip --debug是pip自身的调试选项，不会传递给编译后端，因此被静默忽略；
• --global-option/--build-option属于PEP 517之前的旧方式，已被弃用且会被新后端忽略；
• 直接传递--debug给config-setting时，没有指定是build_ext的选项，Setuptools无法识别该参数；
• 之前在pyproject.toml中添加的[build_ext]段格式错误，新规范下需要放在[tool.setuptools.build_ext]下才会被Setuptools识别。

启用debug选项后，Setuptools会自动调整编译参数：移除-O3优化、添加-g调试符号、不定义NDEBUG宏，生成的扩展库会包含完整的调试信息，即使不附加调试器也能辅助诊断崩溃问题。

内容的提问来源于stack exchange，提问作者Nick Williams