推荐使用pybind11.setuptools的Pybind11Extension和build_ext，因其自动注入C++标准、头文件路径及链接标志，避免手动配置错误；混用setuptools.Extension易导致编译失败。
setup.py里用setuptools.Extension还是pybind11.setuptools？
直接用 setuptools.Extension 是最底层、最可控的方式，适合已有C源码或需要精细控制编译参数的项目。但如果你用的是 pybind11，更推荐用 pybind11.setuptools 提供的 build_ext 子类和 Pybind11Extension ——它会自动注入 -std=c++11（或更高）、头文件路径、链接标志，省去手动写 extra_compile_args 和 include_dirs 的麻烦。
常见错误：混用两者却没覆盖 build_ext 类，导致 pybind11 的 C++ 标准被忽略，编译报 constexpr 或 std::optional 未声明；或者在 Extension 中漏写 language='c++'，结果被 setuptools 当作 C 编译，链接失败。
- 用
pybind11.setuptools时，必须显式传入ext_modules=[Pybind11Extension(...)]，不能只靠setup(ext_modules=...)里的普通Extension - 若项目同时含 C 和 C++ 模块，建议拆成两个
Extension实例，分别设language='c'和language='c++'，避免编译器混淆 - Windows 上 MSVC 默认不支持
-std=c++17，此时Pybind11Extension会自动降级为/std:c++14，但你要确认 pybind11 版本 >= 2.10 才支持该自动适配
如何让Cython生成的.c文件参与构建而不重复编译？
Cython 的 .pyx 文件不能直接交给 setuptools 编译；必须先生成 .c（或 .cpp），再作为源文件传给 Extension。关键在于：别手动运行 cythonize 写死 .c 文件，而应让构建过程动态触发。
正确做法是用 setuptools 的 build_ext 钩子，在 run() 中调用 cythonize()，或更稳妥地——直接在 setup.py 顶层调用 cythonize() 并传入 Extension 列表，它会返回已替换源为 .c 路径的新列表。
立即学习“Python免费学习笔记（深入）”；
- 避免把
cythonize()放进setup()的ext_modules参数里直接调用，这会导致每次pip install都无条件重生成，哪怕.pyx没变 - 加
compiler_directives={'language_level': 3}到cythonize()调用中，否则 Python 3 的print()或 f-string 可能被当语法错误 - 如果项目有
build/目录缓存了旧.c，而你改了.pyx却没清缓存，cythonize()可能跳过重生成——建议在 CI 或本地调试时加--force参数
交叉编译或指定编译器时，setup.py怎么不硬编码gcc/g++？
硬写 CC='gcc-12' 或修改 os.environ['CC'] 在多用户环境或 CI 中极易出错。正确方式是利用 setuptools 自身的环境变量机制和构建类钩子。
优先级顺序是：命令行参数 > 环境变量 > setup.py 默认值。所以你应该允许用户通过 CC=clang CXX=clang++ python setup.py build_ext 控制，而不是在代码里覆盖 os.environ。
- 若需强制指定（如嵌入式交叉编译），子类化
build_ext，在build_extensions(self)开头插入：self.compiler.compiler = ['arm-linux-gnueabihf-gcc']，并确保self.compiler.compiler_so和self.compiler.linker_so也同步设置 - macOS 上用
clang编译 C++ 模块时，常因 SDK 路径缺失报fatal error: 'iostream' file not found——这时要额外传extra_compile_args=['-isysroot', '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk'] - 使用
scikit-build-core（现代替代方案）可彻底解耦构建逻辑，它原生支持CMAKE_C_COMPILER等变量，且能复用 CMakeLists.txt，比手工 hookbuild_ext更健壮
为什么pip install --editable .后C模块没更新？
因为 --editable（即 -e）模式下，setuptools 默认只软链接 Python 部分，C 扩展仍走传统编译流程，且不会监听 .c 或 .pyx 文件变化。改了 C 代码却不重装，模块就还是旧的二进制。
根本原因在于 editable 模式不触发 build_ext，除非你显式运行 python -m pip install -e . --no-deps --no-build-isolation 并配合 --force-reinstall，但这太重。
- 开发阶段更实用的做法：用
python setup.py build_ext --inplace，它把编译结果直接输出到源码目录（同级生成xxx.cpython-*.so），Python 导入时就能立刻加载新代码 - 若用 VS Code，可在
launch.json的env里加"PYTHONPATH": "${workspaceFolder}"，再配合build_ext --inplace，实现改 C → make → F5 调试的闭环 - 注意
--inplace不清理旧的.so，不同平台 ABI 不同（如cpython-39-x86_64-linux-gnu.sovscpython-39-darwin.so），残留文件可能引发导入冲突
build_ext 类的生命周期和 setuptools 的缓存策略——它不会因为你改了一行 #include 就自动重编译，也不会在 --editable 下默认重建 C 模块。得靠 --inplace、显式 build_ext 调用，或转向 scikit-build-core 这类更明确构建语义的工具。 
