如何正确解决pybind11项目中的链接器依赖问题？

问题现象 #

将大型库移植到pybind11实现Python接口时，遇到两种典型错误：

1. 仅编译py_modules.cpp时，Python导入模块报错：undefined symbol: _ZN16SubConfigurationC1ER7Stencil
2. 同时编译py_modules.cpp和SubConfiguration.cpp时，链接阶段触发多重定义错误：

/usr/bin/ld: CMakeFiles/TMP.dir/SubConfiguration.cpp.o (symbol from plugin): in function `Stencil::Stencil(double&)':
(.text+0x0): multiple definition of `Stencil::Stencil(double&)'; CMakeFiles/TMP.dir/py_modules.cpp.o (symbol from plugin):(.text+0x0): first defined here
collect2: error: ld returned 1 exit status

核心原因 #

1. 多重定义错误根源：Stencil类的构造函数实现直接写在头文件Stencil.h中，未拆分到cpp文件。当头文件被多个源文件（py_modules.cpp、SubConfiguration.cpp）包含后，每个编译单元都会生成一份构造函数的定义，链接时就会出现重复定义冲突。
2. 符号未找到错误根源：仅编译py_modules.cpp时，SubConfiguration的构造函数实现（位于SubConfiguration.cpp）未被链接进模块，导致Python导入时无法找到对应符号。

修复步骤 #

1. 重构Stencil类代码 #

将Stencil的构造函数实现从头部文件迁移到单独的cpp文件：

• 修改Stencil.h，仅保留函数声明：

#ifndef SRC_STENCIL_H_
#define SRC_STENCIL_H_

class Stencil {
public:
    double parent;
    Stencil(double&);
};

#endif /* SRC_STENCIL_H_ */

• 创建Stencil.cpp，实现构造函数逻辑：

#include "Stencil.h"

Stencil::Stencil(double& parent) : parent(parent) { }

2. 修正CMake配置 #

确保所有必要的源文件都被加入pybind11模块的编译列表，包括新增的Stencil.cpp：

cmake_minimum_required(VERSION 3.5)

project(tmp VERSION 1.0)

find_package(EnvModules REQUIRED)
env_module(load python39)

find_package(PythonInterp REQUIRED)
include_directories(${PYTHON_INCLUDE_DIRS})
include_directories(pybind11/include)

add_subdirectory(pybind11)
pybind11_add_module(TMP py_modules.cpp
                        SubConfiguration.cpp
                        Stencil.cpp)

3. 验证修复 #

重新执行CMake构建与编译流程，之后Python导入TMP模块时：

• 链接阶段的多重定义问题将被消除
• Python导入时可正常找到所有符号

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