26、CMake与Python集成：find_package(Python)、pybind11、构建Python扩展

说实话，C++和Python的混合开发，在工业界已经是个老生常谈的话题了。我这些年做过的项目里，十有八九都离不开Python的胶水能力——要么是C++写核心算法，Python做上层调度；要么是Python做原型验证，C++做性能优化。今天我们就聊聊CMake里怎么把这两兄弟撮合到一起。

26.1 为什么需要CMake管理Python扩展

你想想看，一个典型的Python扩展项目，通常包含三部分：C++源码、Python绑定代码、以及构建脚本。如果全靠手写setup.py或者手动编译，版本管理、依赖查找、跨平台兼容这些问题会让人头大。CMake的优势在于，它能统一管理C++的编译流程，同时通过find_package(Python)精准定位Python解释器、头文件和库文件。

我个人习惯把CMake当作“总调度员”——它负责找到Python环境，配置好编译参数，最后生成扩展模块。这样不管是在Linux、macOS还是Windows上，构建流程都是一致的。

26.2 find_package(Python) 的正确姿势

CMake从3.12版本开始提供了find_package(Python)，它比老旧的FindPythonInterp和FindPythonLibs好用得多。我刚开始迁移时还踩过坑——旧模块经常找不到正确的Python版本，尤其是系统里装了多个Python的时候。

来看一个典型的用法：

cmake_minimum_required(VERSION 3.14)
project(MyPyExt VERSION 1.0 LANGUAGES CXX)

# 查找Python3，要求同时找到解释器、开发库和NumPy
find_package(Python 3.8 REQUIRED COMPONENTS Interpreter Development NumPy)

if(Python_FOUND)
    message(STATUS "Python version: ${Python_VERSION}")
    message(STATUS "Python include: ${Python_INCLUDE_DIRS}")
    message(STATUS "Python library: ${Python_LIBRARIES}")
endif()

这里有几个关键点：

• COMPONENTS：Interpreter是找python解释器，Development是找头文件和库，NumPy是找numpy的C API。按需声明就好。
• 版本号：明确指定最低版本，避免意外匹配到Python2。我曾经在旧服务器上遇到过系统默认Python2.7，结果编译出来的扩展在Python3下根本加载不了。
• Python_EXECUTABLE：如果系统有多个Python，可以用这个变量强制指定路径。

26.3 pybind11：现代C++与Python的桥梁

说到Python绑定，pybind11是我目前最推荐的工具。它轻量、头文件-only、支持C++11/14/17，而且和CMake的集成做得非常好。我记得第一次用的时候，只花了半小时就把一个复杂的矩阵运算库暴露给了Python。

pybind11的CMake集成有两种方式：

方式一：通过FetchContent自动下载

include(FetchContent)
FetchContent_Declare(
    pybind11
    GIT_REPOSITORY https://github.com/pybind/pybind11.git
    GIT_TAG v2.10.0
)
FetchContent_MakeAvailable(pybind11)

方式二：通过find_package查找系统安装的版本

find_package(pybind11 REQUIRED)

我个人更推荐方式一，因为这样能保证所有开发者的pybind11版本一致，避免“在我机器上能编译”的尴尬。

26.4 构建Python扩展模块

有了Python和pybind11，构建扩展就很简单了。下面是一个完整的例子：

# 假设我们有一个C++函数需要暴露给Python
// example.cpp
#include <pybind11/pybind11.h>
namespace py = pybind11;

int add(int a, int b) {
    return a + b;
}

PYBIND11_MODULE(example, m) {
    m.doc() = "Example plugin";
    m.def("add", &add, "A function that adds two numbers");
}

对应的CMakeLists.txt：

pybind11_add_module(example example.cpp)
target_link_libraries(example PRIVATE pybind11::headers)
set_target_properties(example PROPERTIES
    LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/python"
)

编译后，在python/目录下会生成example.cpython-3xx-xxx.so（Linux）或example.pyd（Windows）。直接在Python里import example就能用了。

26.5 处理Python依赖与安装路径

实际项目中，扩展模块往往需要配合Python包一起发布。我习惯用CMake的install()命令把生成的.so文件安装到Python的site-packages目录下：

install(TARGETS example
    LIBRARY DESTINATION ${Python_SITELIB}
)

这样执行cmake --install .后，模块就直接安装到当前Python环境的包目录里了。配合setuptools的setup.py，还能进一步打包成wheel分发包。

26.6 避坑指南：我踩过的几个坑

• Python调试库 vs 发布库：Windows上Python有debug和release两种库，CMake默认可能找到debug版本，导致链接失败。解决方案是设置Python_FIND_ABI变量。
• 多Python版本冲突：如果系统同时有Python2和Python3，务必在CMake命令行指定-DPython_EXECUTABLE=/usr/bin/python3。
• pybind11的ABI兼容性：不同编译器版本生成的pybind11扩展可能不兼容。我建议团队统一使用相同的编译器版本。
• NumPy数组传递：如果涉及NumPy数组，记得包含pybind11/numpy.h，并且确保find_package(Python)时包含了NumPy组件。

26.7 知识体系总览

下面这张图概括了CMake与Python集成的核心流程：

26.8 实战建议

如果你现在要开始一个新项目，我的建议是：

1. 先用find_package(Python 3.8 REQUIRED COMPONENTS Interpreter Development)确认环境。
2. 用FetchContent引入pybind11，避免版本依赖问题。
3. 用pybind11_add_module创建扩展目标，链接必要的C++库。
4. 用install()把产物安装到${Python_SITELIB}。
5. 写一个简单的Python测试脚本，验证import和函数调用。

嗯，这套流程我用了好几年，在多个跨平台项目里都跑得很稳。你只要照着这个路子走，基本不会出大问题。