使用Setuptools与CMake构建C++ Pybind11扩展时.so文件生成报错排查

核心原因 #

pip install 执行时，setuptools会自动管理build目录下的结构，默认会把最终安装产物放到build/lib.*路径下。如果你的CMakeLists.txt里指定的目标输出路径刚好和setuptools要生成的.so文件路径重名，就会出现CMake先创建了同名目录，后续链接器要生成该文件名的动态库时，发现已经存在同名目录，直接报错。

而你手动在build_temp执行cmake时，没有和setuptools的目录结构冲突，所以能正常构建。

具体解决步骤 #

• 检查CMakeLists.txt的输出路径配置：
  找到设置CMAKE_LIBRARY_OUTPUT_DIRECTORY或set_target_properties里指定LIBRARY_OUTPUT_DIRECTORY的地方，不要把输出路径直接设成setuptools的build/lib.*下的具体.so文件名，而是设为临时构建目录（比如${CMAKE_CURRENT_BINARY_DIR}），让setuptools后续自行处理产物移动。
  示例修改：

  # 错误写法（会生成目录而非文件）
  # set_target_properties(postproc_ops_cpp PROPERTIES LIBRARY_OUTPUT_DIRECTORY "/users/thoerman/postproc_np_products/build/lib.linux-x86_64-cpython-37")
  # 正确写法：指向临时构建目录
  set_target_properties(postproc_ops_cpp PROPERTIES LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/lib")
  

• 调整setup.py里的CMake调用逻辑：
  确保setup.py中调用cmake构建时，指定的构建目录是build_temp这类临时目录，而非直接用setuptools的build目录。比如用setuptools.command.build_ext扩展时，指定build_temp作为cmake工作目录，避免和最终产物目录冲突。
  示例片段：

  class CMakeBuild(build_ext):
      def build_extension(self, ext):
          # 指定临时构建目录
          build_temp = os.path.join(self.build_temp, ext.name)
          os.makedirs(build_temp, exist_ok=True)
          # 调用cmake时指向该临时目录
          subprocess.run(['cmake', ext.sourcedir, '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=' + build_temp], cwd=build_temp, check=True)
          subprocess.run(['cmake', '--build', '.'], cwd=build_temp, check=True)
          # 最后把生成的.so文件复制到setuptools指定路径
          shutil.copy(os.path.join(build_temp, 'postproc_ops_cpp.cpython-37m-x86_64-linux-gnu.so'), self.get_ext_fullpath(ext.name))
  

• 清理残留目录后重试：
  先执行pip uninstall -y postproc_ops_cpp，删除项目根目录的build、dist、*.egg-info目录，再重新执行pip install .，避免之前的错误目录残留影响构建。

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