CMake Superbuild中如何让可执行程序找到依赖的dll/so文件？

在CMake Superbuild架构中，手动用GLOB和平台判断复制依赖库确实不够健壮，容易因为路径变化或版本更新失效。下面分享几种更符合CMake现代实践的解决方案，从根源上解决跨平台的依赖库部署问题：

方案1：统一依赖库的安装目录（推荐） #

核心思路是让所有外部依赖都安装到Superbuild的一个公共目录，然后主项目从这个目录查找依赖，并自动复制所需的库文件到主程序输出目录。

步骤1：在Superbuild中配置统一安装路径 #

修改你的Superbuild.cmake，给每个ExternalProject_Add指定CMAKE_INSTALL_PREFIX到同一个公共目录，比如${CMAKE_BINARY_DIR}/common_install：

# 定义统一的依赖安装目录
set(COMMON_INSTALL_DIR ${CMAKE_BINARY_DIR}/common_install)

# 配置OpenCV的ExternalProject，指定安装路径
ExternalProject_Add(OpenCV
  GIT_REPOSITORY https://github.com/opencv/opencv.git
  GIT_TAG 4.x
  CMAKE_ARGS
    -DCMAKE_INSTALL_PREFIX=${COMMON_INSTALL_DIR}
    -DBUILD_SHARED_LIBS=ON  # 确保构建动态库
    -DWITH_IPP=OFF  # 根据你的需求调整其他参数
  BUILD_ALWAYS OFF
)

# 同理配置libtiff
ExternalProject_Add(libtiff
  GIT_REPOSITORY https://gitlab.com/libtiff/libtiff.git
  GIT_TAG v4.5.1
  CMAKE_ARGS
    -DCMAKE_INSTALL_PREFIX=${COMMON_INSTALL_DIR}
    -DBUILD_SHARED_LIBS=ON
  BUILD_ALWAYS OFF
)

步骤2：主项目从公共目录查找依赖 #

在主项目的根CMakeLists.txt中，先把公共安装目录加入CMAKE_PREFIX_PATH，这样find_package就能正确找到依赖：

# 指向Superbuild的公共依赖安装目录
set(CMAKE_PREFIX_PATH ${CMAKE_BINARY_DIR}/../common_install)

# 查找依赖（现在会自动从公共目录找）
find_package(OpenCV REQUIRED)
find_package(TIFF REQUIRED)

# 设置主程序的输出目录为你的Build/Bin
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/Build/Bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/Build/Bin)

# 链接依赖到主项目
add_executable(myMainProject Project1/Source1.cpp Project2/Source2.cpp)
target_link_libraries(myMainProject PRIVATE OpenCV::core TIFF::TIFF)

步骤3：自动复制依赖库到主程序目录 #

写一个CMake函数，通过目标属性自动获取依赖库的路径，并在构建后复制到主程序的输出目录。这种方式不需要硬编码路径，跨平台自动适配Debug/Release：

# 递归复制依赖的动态库到指定目录
function(copy_dependency_libs target dest_dir)
  # 只处理动态库和模块库目标
  get_target_property(target_type ${target} TYPE)
  if(target_type STREQUAL "SHARED_LIBRARY" OR target_type STREQUAL "MODULE_LIBRARY")
    # 获取库文件路径（区分Windows的Debug/Release）
    if(WIN32)
      get_target_property(lib_debug ${target} IMPORTED_LOCATION_DEBUG)
      get_target_property(lib_release ${target} IMPORTED_LOCATION_RELEASE)
      
      if(lib_debug)
        add_custom_command(TARGET myMainProject POST_BUILD
          COMMAND ${CMAKE_COMMAND} -E copy_if_different
          ${lib_debug} ${dest_dir}/$<CONFIG>/
          COMMENT "Copying debug library: ${lib_debug}"
        )
      endif()
      if(lib_release)
        add_custom_command(TARGET myMainProject POST_BUILD
          COMMAND ${CMAKE_COMMAND} -E copy_if_different
          ${lib_release} ${dest_dir}/$<CONFIG>/
          COMMENT "Copying release library: ${lib_release}"
        )
      endif()
    else()
      get_target_property(lib_path ${target} IMPORTED_LOCATION)
      add_custom_command(TARGET myMainProject POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
        ${lib_path} ${dest_dir}/
        COMMENT "Copying shared library: ${lib_path}"
      )
    endif()
  endif()

  # 递归处理当前目标的所有依赖目标
  get_target_property(deps ${target} INTERFACE_LINK_LIBRARIES)
  if(deps)
    foreach(dep ${deps})
      if(TARGET ${dep})
        copy_dependency_libs(${dep} ${dest_dir})
      endif()
    endforeach()
  endif()
endfunction()

# 调用函数，复制OpenCV和libtiff的依赖库
copy_dependency_libs(OpenCV::core ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
copy_dependency_libs(TIFF::TIFF ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})

方案2：设置运行时搜索路径（无需复制库） #

如果不想复制库文件，可以通过配置运行时的库搜索路径，让主程序直接找到依赖库的位置：

Linux/macOS：设置RPATH #

在主项目的CMakeLists.txt中添加：

if(UNIX)
  # 设置运行时搜索路径为公共依赖安装目录的lib文件夹
  set(CMAKE_INSTALL_RPATH ${CMAKE_BINARY_DIR}/../common_install/lib)
  # 构建时就使用安装路径的RPATH（无需等到install阶段）
  set(CMAKE_BUILD_WITH_INSTALL_RPATH ON)
endif()

Windows：调试时自动设置PATH #

对于Visual Studio调试场景，可以给主程序目标添加调试环境变量，自动把依赖库的dll目录加入PATH：

if(WIN32)
  # 依赖库的dll目录（区分Debug/Release）
  set(DEPENDENCY_DLL_PATH ${CMAKE_BINARY_DIR}/../common_install/bin/$<CONFIG>)
  # 设置VS调试器的环境变量
  set_target_properties(myMainProject PROPERTIES
    VS_DEBUGGER_ENVIRONMENT "PATH=${DEPENDENCY_DLL_PATH};%PATH%"
  )
endif()

为什么不推荐手动GLOB和平台判断？ #

• 硬编码路径容易因为依赖版本更新、构建配置变化而失效；
• 无法自动适配Debug/Release的路径差异；
• 维护成本高，每新增一个依赖都要手动修改复制逻辑；
• 不符合CMake的目标导向设计理念，现代CMake更推荐通过目标属性获取依赖信息。

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