第二十讲：导入库（Imported Library）—— 引用预编译的第三方库

各位同学，今天我们来聊聊 CMake 里一个非常实用的功能——导入库（Imported Library）。

说白了，就是你的项目里要用到别人已经编译好的 .lib、.dll、.so、.a 这些文件。你不需要重新编译它们，只需要告诉 CMake：“嘿，这里有现成的库，帮我链接上就行。”

我刚开始用 CMake 的时候，遇到第三方库就只会用 find_package。后来发现，很多场景下根本找不到现成的 CMake 模块，或者库是自家团队预编译的，这时候就得靠导入库来手动“注册”了。

什么是导入库？

导入库是 CMake 中一种特殊的目标（Target）。它不像 add_library 那样去编译源码，而是直接引用磁盘上已有的库文件。

你可以把它理解成一张“名片”——告诉 CMake 这个库叫什么、头文件在哪、库文件在哪、需要什么编译选项。之后，其他目标就可以通过 target_link_libraries 像使用普通库一样使用它。

核心要点：导入库不参与编译，只负责描述一个已经存在的库。

为什么需要导入库？

我遇到过不少场景，导入库是唯一的选择：

  • 商业库：比如某些加密库、图形引擎，只提供预编译的二进制文件，没有源码。
  • 内部预编译库：团队里有人专门维护一套编译好的基础库，其他人直接引用。
  • 系统库：某些平台特有的库，没有标准的 CMake 查找模块。
  • 交叉编译：目标平台的库在宿主机上无法编译，只能拿现成的。

嗯，这里要注意：如果你能通过 find_package 找到现成的库，那当然优先用那个。但找不到的时候，导入库就是你的救星。

导入库的基本语法

创建一个导入库，用 add_library 加上 IMPORTED 关键字：

add_library(MyImportedLib SHARED IMPORTED)
set_target_properties(MyImportedLib PROPERTIES
    IMPORTED_LOCATION "C:/libs/mylib.dll"
    IMPORTED_IMPLIB "C:/libs/mylib.lib"
    INTERFACE_INCLUDE_DIRECTORIES "C:/libs/include"
)

这里我解释一下几个关键属性：

  • IMPORTED_LOCATION：动态库（.dll/.so）的实际路径。
  • IMPORTED_IMPLIB：Windows 下动态库的导入库（.lib），Linux/macOS 一般不需要。
  • INTERFACE_INCLUDE_DIRECTORIES：这个库的头文件目录，会被传递给链接它的目标。

对于静态库，写法更简单：

add_library(MyStaticLib STATIC IMPORTED)
set_target_properties(MyStaticLib PROPERTIES
    IMPORTED_LOCATION "C:/libs/mylib_static.lib"
    INTERFACE_INCLUDE_DIRECTORIES "C:/libs/include"
)

小技巧：我个人习惯把导入库的路径用变量定义，方便切换不同配置（Debug/Release、32位/64位）。比如：

set(LIB_PATH "${CMAKE_SOURCE_DIR}/thirdparty/${CMAKE_BUILD_TYPE}")
add_library(MyLib STATIC IMPORTED)
set_target_properties(MyLib PROPERTIES
    IMPORTED_LOCATION "${LIB_PATH}/mylib.lib"
)

导入库的完整示例

我们来看一个实际项目中的例子。假设你有一个预编译的加密库 crypto，包含头文件和 .lib/.dll 文件。

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# 定义导入库
add_library(CryptoLib SHARED IMPORTED)

# 设置不同配置下的路径
set(CRYPTO_DIR "${CMAKE_SOURCE_DIR}/thirdparty/crypto")

set_target_properties(CryptoLib PROPERTIES
    IMPORTED_LOCATION_DEBUG "${CRYPTO_DIR}/debug/crypto.dll"
    IMPORTED_LOCATION_RELEASE "${CRYPTO_DIR}/release/crypto.dll"
    IMPORTED_IMPLIB_DEBUG "${CRYPTO_DIR}/debug/crypto.lib"
    IMPORTED_IMPLIB_RELEASE "${CRYPTO_DIR}/release/crypto.lib"
    INTERFACE_INCLUDE_DIRECTORIES "${CRYPTO_DIR}/include"
)

# 使用导入库
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE CryptoLib)

注意这里我用了 IMPORTED_LOCATION_DEBUG 和 IMPORTED_LOCATION_RELEASE，CMake 会根据当前的构建类型自动选择对应的库文件。这个特性我在做跨平台项目时经常用到，省去了手动判断的麻烦。

导入库的常见属性

除了位置和头文件，导入库还可以设置很多其他属性。我整理了一个表格，方便大家查阅：

属性 说明 适用场景
IMPORTED_LOCATION 库文件的主路径 所有导入库必须设置
IMPORTED_IMPLIB Windows DLL 的导入库 Windows 动态库
INTERFACE_INCLUDE_DIRECTORIES 头文件目录 几乎所有库都需要
INTERFACE_COMPILE_DEFINITIONS 编译宏定义 库需要特定宏才能使用
INTERFACE_COMPILE_OPTIONS 编译选项 库需要特定的编译开关
INTERFACE_LINK_LIBRARIES 该库依赖的其他库 库有传递性依赖

避坑指南：我曾经在 Linux 上折腾了一下午，就是因为忘记设置 INTERFACE_LINK_LIBRARIES。一个动态库可能依赖其他系统库（比如 pthread、dl），如果不声明，链接时会报“未定义的引用”。

解决办法：把依赖的库也作为导入库，或者直接用 -lpthread 这样的方式写在 INTERFACE_LINK_LIBRARIES 里。

导入库 vs. find_package

很多同学会问：有了 find_package，为什么还要手动创建导入库？

我的理解是这样的：

  • find_package 是“自动查找”，它背后有 CMake 模块或者库自带的 XXXConfig.cmake 文件。找到后，它通常会帮你创建好导入库。
  • 手动创建导入库是“手动注册”，适用于那些没有提供 CMake 支持的库。

说白了，find_package 是高级 API，导入库是底层机制。很多 find_package 找到的库，本质上也是通过导入库来暴露给项目的。

知识体系图

下面这张图展示了导入库在整个 CMake 构建体系中的位置和作用：

导入库（Imported Library）知识体系 导入库 add_library(... IMPORTED) set_target_properties target_link_libraries target_include_directories IMPORTED_LOCATION INTERFACE_INCLUDE INTERFACE_LINK IMPORTED_IMPLIB 核心思想：描述已有库，不参与编译，只负责链接和接口传递

实战中的注意事项

最后，分享几个我在实际项目中积累的经验：

  1. 路径尽量用相对路径：绝对路径换台机器就废了。我习惯把第三方库放在项目目录下的 thirdparty 文件夹里，用 ${CMAKE_SOURCE_DIR} 引用。
  2. 区分 Debug 和 Release：很多库的 Debug 版和 Release 版不兼容（比如 MSVC 的运行时库不同）。用 IMPORTED_LOCATION_DEBUG 和 IMPORTED_LOCATION_RELEASE 分别指定。
  3. 别忘了传递性依赖：如果库 A 依赖库 B，而你的项目只链接了 A，那么 B 也要通过 INTERFACE_LINK_LIBRARIES 声明。否则链接时会报错。
  4. 检查库的位数：32 位库不能链接到 64 位程序，反之亦然。这个错误很隐蔽，我曾经在 CI 上排查了半天才发现是库的位数不对。

一个实用技巧：如果你经常使用某个第三方库，可以写一个自定义的 CMake 模块（比如 FindMyLib.cmake），在里面封装好导入库的创建逻辑。这样其他项目只需要 find_package(MyLib) 就能用，一劳永逸。

好了，关于导入库的内容就讲到这里。它虽然看起来简单，但在实际项目中非常实用。尤其是当你需要集成各种预编译组件时，掌握好导入库能省去很多麻烦。

记住一句话：导入库就是给 CMake 一张“名片”，告诉它这个库是谁、在哪、怎么用。剩下的，CMake 会帮你处理好。

公众号：蓝海资料掘金营，微信 deep3321

← 上一章 📖 返回目录 下一章 →