如何配置CMake搜索路径以找到FindXXXX.cmake文件？

问题场景 #

编译依赖公共库的CMake项目时，执行find_package(Eigen3 REQUIRED)触发如下错误。已尝试设置CMAKE_MODULE_PATH和CMAKE_PREFIX_PATH为FindEigen3.cmake的完整文件路径，但问题仍未解决。

错误信息：

CMake Error at CMakeLists.txt:298 (find_package):
  By not providing "FindEigen3.cmake" in CMAKE_MODULE_PATH this project has
  asked CMake to find a package configuration file provided by "Eigen3", but
  CMake did not find one.

  Could not find a package configuration file provided by "Eigen3" with any
  of the following names:

    Eigen3Config.cmake
    eigen3-config.cmake

  Add the installation prefix of "Eigen3" to CMAKE_PREFIX_PATH or set
  "Eigen3_DIR" to a directory containing one of the above files.  If "Eigen3"
  provides a separate development package or SDK, be sure it has been
  installed.

已知FindEigen3.cmake路径为path/to/FindEigen3.cmake，最小复现步骤：

git clone https://github.com/lightvector/KataGo.git
cd KataGo/cpp
cmake . -DUSE_BACKEND=EIGEN

解决方案 #

先搞懂CMake查找逻辑 #

find_package有两种查找模式：

• 模块模式：CMake会在CMAKE_MODULE_PATH指定的目录下查找FindXXXX.cmake文件。
• 配置模式：CMake会查找XXXXConfig.cmake或xxxx-config.cmake文件，优先级高于模块模式。

报错提示找不到配置文件，说明CMake优先尝试了配置模式失败，此时才会去模块模式查找，但你的CMAKE_MODULE_PATH设置有误。

正确设置CMAKE_MODULE_PATH #

关键：CMAKE_MODULE_PATH要指向包含FindEigen3.cmake的目录，而非文件本身。比如文件路径是path/to/FindEigen3.cmake，则需要把path/to加入CMAKE_MODULE_PATH：

1. 在CMakeLists.txt中设置（需放在find_package之前）：

list(APPEND CMAKE_MODULE_PATH "path/to")

2. 或通过cmake命令行参数设置：

cmake . -DUSE_BACKEND=EIGEN -DCMAKE_MODULE_PATH=path/to

额外排查点 #

• 路径尽量用绝对路径，避免相对路径导致的定位错误。
• 检查文件名大小写：Linux/macOS下CMake对文件名大小写敏感，确保FindEigen3.cmake拼写完全正确。
• 若使用官方安装的Eigen3，部分版本会自带Eigen3Config.cmake，此时可直接设置Eigen3_DIR到该文件所在目录，或把Eigen的安装前缀加入CMAKE_PREFIX_PATH。

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