如何改写/增强CFFI包构建时setuptools build_ext的错误提示？

问题背景 #

在全新Linux系统上构建基于CFFI的Python包时，pip install .或python -m build返回的依赖缺失错误信息模糊（比如gcc找不到、pyconfig.h缺失），无法直接指导新手用户安装对应的系统依赖包（如build-essential、python3-dev）。需要在使用默认setuptools构建后端的前提下，捕获、改写这些错误，提供可操作的指引。

实现方案 #

方法1：自定义setuptools的build_ext子类捕获错误 #

通过继承setuptools的build_ext类，重写run()方法捕获编译过程中的异常，根据错误类型输出针对性提示：

1. 在项目根目录创建build_helpers.py文件：

from setuptools.command.build_ext import build_ext
import sys

class CustomBuildExt(build_ext):
    def run(self):
        try:
            super().run()
        except Exception as e:
            error_msg = str(e)
            # 处理gcc不存在的情况
            if "command 'gcc' failed: No such file or directory" in error_msg:
                print("\n" + "*"*50)
                print("错误：缺少C编译工具链，请安装系统依赖包：")
                if sys.platform.startswith('linux'):
                    print("Debian/Ubuntu：sudo apt install build-essential")
                    print("RHEL/CentOS/Fedora：sudo dnf groupinstall 'Development Tools'")
                elif sys.platform == 'win32':
                    print("Windows：安装Visual Studio Build Tools（勾选\"C++开发工具\"）")
                print("*"*50 + "\n")
            # 处理pyconfig.h缺失的情况
            elif "pyconfig.h: No such file or directory" in error_msg:
                print("\n" + "*"*50)
                print("错误：缺少Python开发头文件，请安装系统依赖包：")
                if sys.platform.startswith('linux'):
                    print("Debian/Ubuntu：sudo apt install python3-dev")
                    print("RHEL/CentOS/Fedora：sudo dnf install python3-devel")
                elif sys.platform == 'win32':
                    print("Windows：确保Visual Studio Build Tools安装了Python开发组件")
                print("*"*50 + "\n")
            # 重新抛出异常，不中断原有错误流程
            raise e

2. 修改setup.py，使用自定义的build_ext命令：

from setuptools import setup
from build_helpers import CustomBuildExt

setup(
    # 原有配置...
    cffi_modules=['cffi_module.py:ffi'],
    cmdclass={'build_ext': CustomBuildExt}
)

方法2：在pyproject.toml中添加前置检查提示 #

在pyproject.toml的[build-system]部分添加注释说明前置依赖，同时确保构建依赖正确声明：

[project]
name = "your-package-name"
version = "0.1.0"
dependencies = [
    "cffi >= 1.0.0; platform_python_implementation != 'PyPy'"
]

[build-system]
requires = [
    "cffi >= 1.14",
    "setuptools >= 49.5.0"
]
build-backend = "setuptools.build_meta"

# 构建前需安装系统依赖：
# Linux: build-essential + python3-dev
# Windows: Visual Studio Build Tools (勾选C++开发组件)

方法3：添加项目根目录的INSTALL.md文件 #

在项目根目录创建INSTALL.md，详细说明不同系统下的前置依赖安装步骤，同时在错误提示中引导用户查看该文件：
在CustomBuildExt的异常处理中添加：

print("请查看项目根目录的INSTALL.md文件获取详细安装指引\n")

错误示例优化效果 #

原错误（gcc缺失） #

error: command 'gcc' failed: No such file or directory
ERROR Backend subprocess exited when trying to invoke build_wheel

优化后提示 #

**************************************************
错误：缺少C编译工具链，请安装系统依赖包：
Debian/Ubuntu：sudo apt install build-essential
RHEL/CentOS/Fedora：sudo dnf groupinstall 'Development Tools'
**************************************************

error: command 'gcc' failed: No such file or directory
ERROR Backend subprocess exited when trying to invoke build_wheel

原错误（pyconfig.h缺失） #

build/temp.linux-x86_64-cpython-39/xxx.c:50:14: fatal error: pyconfig.h: No such file or directory
compilation terminated.
error: command '/usr/bin/gcc' failed with exit code 1

优化后提示 #

**************************************************
错误：缺少Python开发头文件，请安装系统依赖包：
Debian/Ubuntu：sudo apt install python3-dev
RHEL/CentOS/Fedora：sudo dnf install python3-devel
**************************************************

build/temp.linux-x86_64-cpython-39/xxx.c:50:14: fatal error: pyconfig.h: No such file or directory
compilation terminated.
error: command '/usr/bin/gcc' failed with exit code 1

最小可复现示例（MRE） #

以下代码可在全新Windows 10或Ubuntu LTS系统上复现CFFI包构建错误：

from itertools import chain, repeat, islice
import os
from pathlib import Path
import platform
import shlex
import subprocess
import sys
import tempfile
from textwrap import dedent
import venv

BUILD_CMD = ['python', '-m', 'pip', 'install', '-v', '.']


def main():
    with tempfile.TemporaryDirectory() as td:
        td = os.path.realpath(td)
        venv.create(td, with_pip=True)
        root = Path(td) / 'stackoverflow-77686182'
        root.mkdir()

        # 1. 创建setup.py
        (root / 'setup.py').write_text(dedent('''\
        # https://foss.heptapod.net/pypy/cffi/-/issues/441
        # https://github.com/python-cffi/cffi/issues/55
        from setuptools import setup
        
        setup(
            cffi_modules = [
                'cffi_module.py:ffi'
            ]
        )
        '''))

        # 2. 创建CFFI模块
        (root / 'cffi_module.py').write_text(dedent('''\
        from cffi import FFI
        from pathlib import Path
        root = Path(__file__).parent
        
        ffibuilder = FFI()
        ffibuilder.cdef('unsigned short spam();')
        ffibuilder.set_source(
            'stackoverflow_77686182._libspam',
            '#include "libspam.h"',
            sources=[(root / 'libspam.c').as_posix()],
            include_dirs=[root.as_posix()]
        )
        ffi = ffibuilder
        '''))

        # 3. 创建C源代码
        (root / 'libspam.c').write_text(dedent('''\
        unsigned short spam() {
            return 69;
        }
        '''))

        # 4. 创建C头文件
        (root / 'libspam.h').write_text(dedent('''\
        unsigned short spam();
        '''))

        # 5. 创建Python包代码
        (root / 'src' / 'stackoverflow_77686182').mkdir(parents=True, exist_ok=True)
        (root / 'src' / 'stackoverflow_77686182' / '__init__.py').write_text(dedent('''\
        from . import _libspam
        '''))
        (root / 'src' / 'stackoverflow_77686182' / '__main__.py').write_text(dedent('''\
        from stackoverflow_77686182._libspam import ffi, lib
        if lib.spam() == 69:
            print('OK')
        else:
            raise AssertionError('FAIL')
        '''))

        # 6. 创建Python打包元数据
        (root / 'pyproject.toml').write_text(dedent('''\
        [project]
        name = 'stackoverflow_77686182'
        version = '0'
        dependencies = [
            'cffi >= 1.0.0;platform_python_implementation != "PyPy"',
        ]
        
        [build-system]
        requires = [
            'cffi >= 1.14',
            'setuptools >= 49.5.0'
        ]
        '''))

        (root / 'requirements-dev.txt').write_text(dedent('''\
        pip >= 21.1.3
        setuptools >= 49.5.0
        '''))

        # 7. 构建并安装
        _check_call_in_venv(td, ['python', '-m', 'pip', 'install', '-r', root / 'requirements-dev.txt'])
        _check_call_in_venv(td, BUILD_CMD, cwd=root)

        # 8. 运行测试
        _check_call_in_venv(td, ['python', '-m', 'stackoverflow_77686182'])
        raise NotImplementedError('该脚本应在缺少CFFI构建必要组件的机器上运行，但构建似乎已成功。')


def _check_call_in_venv(env_dir, cmd, *a, **k):
    script = []
    is_win = (platform.system() == 'Windows')
    script.append(['.', Path(env_dir) / 'bin' / 'activate'] if not is_win else [Path(env_dir) / 'Scripts' / 'activate.bat'])
    script.append(cmd)
    _cmd = ['sh', '-c', ';\n'.join(shlex.join(cmd) for cmd in ['set -e'] + script)] if not is_win else f'cmd /C "{ " ".join(_intersperse("&&", (" ".join(map(str, cmd)) for cmd in script)))}"'
    return subprocess.check_call(_cmd, *a, **k)


def _intersperse(delim, seq):
    # https://stackoverflow.com/a/5656097/1874170
    return islice(chain.from_iterable(zip(repeat(delim), seq)), 1, None)


if __name__ == '__main__':
    main()

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