如何在CMake中通过通用add_dep函数引入预编译外部依赖？

我刚好做过类似的需求，核心思路是把每个预编译库的依赖信息（头文件目录、库路径、平台适配的库文件名）提前封装成配置文件，再通过一个通用函数自动加载这些配置并关联到目标上，完全满足你“调用add_dep(libName)就搞定”的需求，下面一步步来实现：

1. 目录结构规划 #

先给项目搭个清晰的目录结构，把预编译库和配置文件分开管理，比如：

your_project/
├── cmake/
│   ├── AddDep.cmake       # 存放add_dep函数的实现
│   └── PrebuiltDeps/      # 每个预编译库的配置文件
│       ├── FindSDL2.cmake
│       └── FindBoost.cmake
├── third_party/           # 存放预编译库的实际文件
│   ├── SDL2/
│   │   ├── include/
│   │   └── lib/
│   │       ├── x64/       # Windows x64库
│   │       └── x86/
│   └── Boost/
│       ├── include/
│       └── lib/
├── src/
│   └── main.cpp
└── CMakeLists.txt

2. 编写通用的add_dep函数 #

在cmake/AddDep.cmake里实现核心函数，它的作用是：加载对应库的配置文件，自动给目标添加头文件目录、链接目录并关联库文件：

function(add_dep TARGET DEP_NAME)
    # 从我们自定义的PrebuiltDeps目录加载库的配置文件
    # NO_DEFAULT_PATH避免CMake去系统路径找同名库
    find_package(${DEP_NAME} REQUIRED 
                 PATHS ${CMAKE_CURRENT_LIST_DIR}/PrebuiltDeps 
                 NO_DEFAULT_PATH)

    # 为目标添加头文件目录（PRIVATE表示仅当前目标可见，按需换成PUBLIC/INTERFACE）
    target_include_directories(${TARGET} PRIVATE ${${DEP_NAME}_INCLUDE_DIRS})

    # 添加库文件所在目录
    target_link_directories(${TARGET} PRIVATE ${${DEP_NAME}_LIBRARY_DIRS})

    # 把预编译库链接到目标上
    target_link_libraries(${TARGET} PRIVATE ${${DEP_NAME}_LIBRARIES})
endfunction()

3. 为每个预编译库编写配置文件 #

以SDL2为例，在cmake/PrebuiltDeps/FindSDL2.cmake里写好该库的具体路径和平台适配：

# 定义SDL2的头文件目录，对应third_party下的实际路径
set(SDL2_INCLUDE_DIRS "${CMAKE_SOURCE_DIR}/third_party/SDL2/include")

# 根据当前编译平台自动选择对应的库目录
if(CMAKE_SYSTEM_PROCESSOR MATCHES "AMD64|x86_64")
    set(SDL2_LIBRARY_DIRS "${CMAKE_SOURCE_DIR}/third_party/SDL2/lib/x64")
elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "x86")
    set(SDL2_LIBRARY_DIRS "${CMAKE_SOURCE_DIR}/third_party/SDL2/lib/x86")
endif()

# 区分Windows/Linux/macOS的库文件名
if(WIN32)
    set(SDL2_LIBRARIES "SDL2.lib;SDL2main.lib")
elseif(UNIX AND NOT APPLE)
    set(SDL2_LIBRARIES "libSDL2.so;libSDL2main.so")
elseif(APPLE)
    set(SDL2_LIBRARIES "libSDL2.dylib;libSDL2main.dylib")
endif()

其他库（比如Boost、OpenCV）都按这个模板写，只需要替换对应的路径和库文件名即可。

4. 在项目中使用add_dep #

在根目录的CMakeLists.txt里，先引入我们的函数，然后在创建目标后直接调用add_dep：

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# 引入我们自定义的add_dep函数
include(cmake/AddDep.cmake)

# 创建你的目标（可执行文件或库）
add_executable(MyApp src/main.cpp)

# 一键引入SDL2依赖！不用手动加任何目录或库
add_dep(MyApp SDL2)

# 如果需要引入多个依赖，直接多次调用就行
# add_dep(MyApp Boost)

一些进阶优化 #

• 依赖传递性控制：如果你的目标是一个库，并且需要把依赖暴露给上层项目，把PRIVATE换成PUBLIC或INTERFACE即可。
• 版本检查：可以在配置文件里添加版本变量（比如SDL2_VERSION "2.26.5"），然后在add_dep函数里加入版本校验逻辑。
• 组件支持：如果库有多个子组件（比如Qt的Core/Widgets），可以扩展函数支持COMPONENTS参数，比如add_dep(MyApp Qt5 COMPONENTS Core Widgets)，然后在配置文件里处理组件对应的库。
• 自动复制动态库：如果是Windows平台，还可以在add_dep里加一段逻辑，把.dll文件自动复制到输出目录，避免运行时找不到库。

这样实现的add_dep完全通用，不管是哪个预编译库，只要写好对应的配置文件，就能一键引入，用户完全不用关心头文件和库目录的细节~

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