CMake中add_subdirectory引入poppler子项目时CMAKE_MODULE_PATH错误如何解决

问题根因 #

该报错的核心原因是poppler的CMake配置脚本直接使用set()覆盖了CMAKE_MODULE_PATH变量，而非用list(APPEND)追加路径。当作为子模块被上层项目引入时，poppler自身的模块目录因为变量覆盖的逻辑，无法被CMake正确识别，导致找不到内部依赖的PopplerDefaults模块。

可行规避方案 #

方案1：提前注入poppler模块路径 #

在调用add_subdirectory引入poppler之前，先主动将poppler的模块目录追加到全局CMAKE_MODULE_PATH中，即使后续poppler的脚本覆盖了该变量，CMake已经在父域记录了对应的路径：

# 请替换为你项目中poppler子模块的实际路径
set(POPPLER_SUBMODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/external/poppler")
list(APPEND CMAKE_MODULE_PATH "${POPPLER_SUBMODULE_PATH}/cmake/modules")
add_subdirectory(${POPPLER_SUBMODULE_PATH})

方案2：使用ExternalProject_Add独立构建 #

如果方案1不生效，更稳妥的方式是使用CMake的ExternalProject模块独立编译poppler，完全隔离上层项目和poppler的构建变量，避免互相污染：

include(ExternalProject)
ExternalProject_Add(poppler
  SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/external/poppler
  PREFIX ${CMAKE_CURRENT_BINARY_DIR}/poppler-build
  CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=${CMAKE_CURRENT_BINARY_DIR}/poppler-install
  # 可以在这里添加需要的poppler编译参数，比如-DENABLE_QT5=ON之类的
)
# 后续链接时使用安装目录下的库和头文件即可
include_directories(${CMAKE_CURRENT_BINARY_DIR}/poppler-install/include)
link_directories(${CMAKE_CURRENT_BINARY_DIR}/poppler-install/lib)

方案3：给poppler打本地补丁 #

如果允许修改子模块的极小部分代码，可以直接把poppler根目录CMakeLists.txt中直接赋值CMAKE_MODULE_PATH的行，修改为追加模式：

# 原代码
set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
# 修改为
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)

可以把这个修改做成补丁文件和项目一起存储，每次拉取子模块后自动应用即可，不会影响后续上游代码的同步。

这类场景的通用处理逻辑 #

• 引入第三方库作为子模块前，优先检查其CMake脚本是否存在全局变量覆盖的逻辑，类似CMAKE_MODULE_PATH、CMAKE_CXX_FLAGS这类通用变量如果被直接set，大概率会出现集成问题
• 对于CMake脚本不规范的第三方库，优先选择独立构建的方式（ExternalProject、FetchContent独立构建模式）集成，避免变量污染
• 如果一定要用add_subdirectory模式，可以先在父域预先设置好对应变量，或者对第三方库的CMake脚本做极小的补丁修改

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