【CMake 】[第七篇]CMake 库管理完全指南：add_library 与 target_link

CMake 库管理完全指南：add_library 与 target_link_libraries 详解

在现代 C++ 项目开发中，库的创建和管理是必不可少的技能。CMake 作为最流行的构建系统，提供了add_library和target_link_libraries这两个核心命令来简化库的管理。本文将深入探讨这两个命令的使用方法、最佳实践以及常见陷阱。

📚 目录

为什么需要库？
add_library：创建库的魔法
target_link_libraries：连接一切的桥梁
实战案例：完整项目示例
常见问题与最佳实践
总结

为什么需要库？

在软件开发中，我们经常需要将代码组织成可重用的模块。库（Library）就是这样的模块，它允许我们：

代码复用：将常用功能封装成库，在多个项目中共享
模块化设计：将大型项目拆分成多个库，便于管理和维护
编译优化：只重新编译修改的库，而不是整个项目
团队协作：不同团队可以独立开发和维护各自的库

库的类型

C++ 中有两种主要的库类型：

静态库（Static Library）
- 编译时链接，代码直接嵌入到可执行文件中
- 文件扩展名：.a（Linux）或.lib（Windows）
- 优点：部署简单，不需要额外的库文件
- 缺点：可执行文件体积较大
动态库（Shared Library / Dynamic Link Library）
- 运行时链接，代码在单独的库文件中
- 文件扩展名：.so（Linux）或.dll（Windows）
- 优点：可执行文件体积小，多个程序可共享
- 缺点：部署时需要确保库文件可用

add_library：创建库的魔法

add_library是 CMake 中用于创建库的核心命令。它的基本语法如下：

add_library(<name> [STATIC | SHARED | MODULE] [源文件...])

基本用法

创建静态库

add_library(math_lib_static STATIC math_lib.cpp)

这行代码做了以下几件事：

创建一个名为math_lib_static的静态库目标
指定库的类型为STATIC（静态库）
将math_lib.cpp编译并打包成静态库

生成的文件：

Linux:libmath_lib_static.a
Windows:math_lib_static.lib（MSVC）或libmath_lib_static.a（MinGW）

创建动态库

add_library(string_lib_shared SHARED string_lib.cpp)

与静态库类似，但类型改为SHARED（共享库/动态库）。

生成的文件：

Linux:libstring_lib_shared.so
Windows:string_lib_shared.dll（以及对应的.lib导入库）

库类型详解

类型	关键字	说明	使用场景
静态库	`STATIC`	编译时链接，代码嵌入可执行文件	小型工具、需要独立部署的程序
动态库	`SHARED`	运行时链接，代码在单独文件中	大型应用、需要热更新的系统
模块库	`MODULE`	类似动态库，但不链接到可执行文件	插件系统

多源文件库

如果库包含多个源文件，可以这样写：

add_library(utils_lib STATIC math_utils.cpp string_utils.cpp file_utils.cpp )

或者使用变量：

set(UTILS_SOURCES math_utils.cpp string_utils.cpp file_utils.cpp ) add_library(utils_lib STATIC ${UTILS_SOURCES})

设置库的属性

创建库后，通常需要设置一些属性：

# 创建库 add_library(math_lib_static STATIC math_lib.cpp) # 设置包含目录（让使用此库的目标能找到头文件） target_include_directories(math_lib_static PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) # 设置 C++ 标准 target_compile_features(math_lib_static PUBLIC cxx_std_11) # 设置编译选项 target_compile_options(math_lib_static PRIVATE -Wall -Wextra)

关键点：使用PUBLIC表示这个属性会传递给链接此库的目标，使用PRIVATE表示只用于当前目标。

target_link_libraries：连接一切的桥梁

target_link_libraries用于将库链接到可执行文件或其他库。它的基本语法如下：

target_link_libraries(<target> [PRIVATE|PUBLIC|INTERFACE] <库名>...)

基本用法

# 创建可执行文件 add_executable(my_app main.cpp) # 链接库 target_link_libraries(my_app math_lib_static string_lib_shared )

这行代码告诉 CMake：将math_lib_static和string_lib_shared链接到my_app可执行文件中。

链接可见性

CMake 3.0+ 引入了链接可见性的概念，用于控制库的依赖关系如何传播：

PRIVATE（私有链接）

target_link_libraries(my_app PRIVATE math_lib_static)

my_app可以使用math_lib_static的功能
其他链接my_app的目标不会自动获得math_lib_static的依赖
适用于：库是my_app的内部实现细节

PUBLIC（公共链接）

target_link_libraries(my_app PUBLIC math_lib_static)

my_app可以使用math_lib_static的功能
其他链接my_app的目标会自动获得math_lib_static的依赖
适用于：my_app的接口依赖于math_lib_static

INTERFACE（接口链接）

target_link_libraries(my_lib INTERFACE math_lib_static)

my_lib不能使用math_lib_static的功能（用于编译）
但链接my_lib的目标会自动获得math_lib_static的依赖
适用于：头文件库（header-only libraries）的依赖

实际示例对比

假设我们有一个库utils_lib和一个可执行文件app：

# 场景1：PRIVATE - utils_lib 是 app 的内部实现 add_library(utils_lib STATIC utils.cpp) add_executable(app main.cpp) target_link_libraries(app PRIVATE utils_lib) # 如果另一个目标链接 app： add_executable(other_app other_main.cpp) target_link_libraries(other_app app) # other_app 不会自动获得 utils_lib，需要手动链接

# 场景2：PUBLIC - app 的接口依赖于 utils_lib add_library(utils_lib STATIC utils.cpp) add_executable(app main.cpp) target_link_libraries(app PUBLIC utils_lib) # 如果另一个目标链接 app： add_executable(other_app other_main.cpp) target_link_libraries(other_app app) # other_app 会自动获得 utils_lib 的依赖

链接外部库

除了链接项目内的库，还可以链接系统库或第三方库：

# 链接系统库（如 pthread） target_link_libraries(my_app pthread) # 链接第三方库（使用 find_package 找到的） find_package(Boost REQUIRED) target_link_libraries(my_app Boost::boost)

实战案例：完整项目示例

让我们通过一个完整的项目来理解这两个命令的实际应用。

项目结构

04_libTest/ ├── CMakeLists.txt ├── main.cpp ├── math_lib.h ├── math_lib.cpp ├── string_lib.h └── string_lib.cpp

源代码

math_lib.h:

#ifndefMATH_LIB_H#defineMATH_LIB_Hintpower(intbase,intexponent);#endif

math_lib.cpp:

#include"math_lib.h"intpower(intbase,intexponent){intresult=1;for(inti=0;i<exponent;i++){result*=base;}returnresult;}

string_lib.h:

#ifndefSTRING_LIB_H#defineSTRING_LIB_H#include<string>std::stringreverse(conststd::string&str);#endif

string_lib.cpp:

#include"string_lib.h"#include<algorithm>std::stringreverse(conststd::string&str){std::string result=str;std::reverse(result.begin(),result.end());returnresult;}

main.cpp:

#include<iostream>#include"math_lib.h"#include"string_lib.h"intmain(){std::cout<<"=== 使用静态库和动态库 ==="<<std::endl;// 使用数学库intresult=power(2,8);std::cout<<"2^8 = "<<result<<std::endl;// 使用字符串库std::string text="Hello CMake";std::cout<<"反转 '"<<text<<"' = '"<<reverse(text)<<"'"<<std::endl;return0;}

CMakeLists.txt 完整配置

# CMake 最低版本要求 cmake_minimum_required(VERSION 3.10) # 项目名称和语言 project(LibraryExample LANGUAGES CXX) # 设置C++标准 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) # ========== 创建静态库 ========== add_library(math_lib_static STATIC math_lib.cpp) # PUBLIC 表示：库本身需要这个包含目录，使用此库的目标也需要 target_include_directories(math_lib_static PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) # ========== 创建动态库（共享库） ========== add_library(string_lib_shared SHARED string_lib.cpp) target_include_directories(string_lib_shared PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) # ========== 创建可执行文件并链接库 ========== add_executable(lib_example main.cpp) # 链接静态库和动态库 target_link_libraries(lib_example math_lib_static string_lib_shared ) # 设置包含目录（PRIVATE 表示只用于编译 lib_example） target_include_directories(lib_example PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

构建和运行

# 创建构建目录mkdirbuild&&cdbuild# 配置项目cmake..# 编译cmake --build.# 运行（Linux）./lib_example# 运行（Windows）.\Debug\lib_example.exe

输出结果：

=== 使用静态库和动态库 === 2^8 = 256 反转 'Hello CMake' = 'ekaMC olleH'

代码解析

创建静态库：
```
add_library(math_lib_static STATIC math_lib.cpp)
```
- 将math_lib.cpp编译成静态库
- 使用PUBLIC设置包含目录，确保使用此库的目标能找到math_lib.h
创建动态库：
```
add_library(string_lib_shared SHARED string_lib.cpp)
```
- 将string_lib.cpp编译成动态库
- 同样使用PUBLIC设置包含目录
链接库：
```
target_link_libraries(lib_example math_lib_static string_lib_shared )
```
- 将两个库都链接到lib_example
- CMake 会自动处理静态库和动态库的链接差异

常见问题与最佳实践

1. 什么时候使用静态库？什么时候使用动态库？

使用静态库的场景：

小型工具程序
需要完全独立的可执行文件
库代码很少变化
不想处理库文件部署问题

使用动态库的场景：

大型应用程序
多个程序共享同一库
需要热更新库功能
插件系统

2. PUBLIC、PRIVATE、INTERFACE 如何选择？

选择原则：

PRIVATE：库是目标的内部实现细节
PUBLIC：目标的接口依赖于库（头文件中使用了库的类型）
INTERFACE：目标本身不使用库，但使用此目标的其他目标需要

示例：

# 如果 my_lib.h 中包含了 utils.h，使用 PUBLIC target_include_directories(my_lib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) target_link_libraries(my_lib PUBLIC utils_lib) # 如果 my_lib.cpp 中使用了 utils，但 my_lib.h 中没有，使用 PRIVATE target_link_libraries(my_lib PRIVATE utils_lib)

3. 为什么需要设置包含目录？

即使链接了库，编译器在编译时仍然需要找到头文件。target_include_directories告诉编译器在哪里查找头文件。

# 错误示例：只链接库，不设置包含目录 add_library(math_lib STATIC math_lib.cpp) add_executable(app main.cpp) target_link_libraries(app math_lib) # main.cpp 编译时会报错：找不到 math_lib.h # 正确示例：同时设置包含目录 add_library(math_lib STATIC math_lib.cpp) target_include_directories(math_lib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) add_executable(app main.cpp) target_link_libraries(app math_lib) # 现在可以正常编译了

4. 如何链接多个库？

可以一次链接多个库：

target_link_libraries(my_app lib1 lib2 lib3 pthread ${CMAKE_DL_LIBS} # 系统库 )

5. 库的命名规范

CMake 会自动添加平台特定的前缀和后缀：

Linux 静态库：lib+ 名称 +.a
Linux 动态库：lib+ 名称 +.so
Windows 静态库：名称 +.lib
Windows 动态库：名称 +.dll

你只需要指定库的名称，CMake 会处理其余部分。

6. 条件编译库

可以根据条件创建不同类型的库：

option(BUILD_SHARED_LIBS "Build shared libraries" OFF) if(BUILD_SHARED_LIBS) add_library(my_lib SHARED my_lib.cpp) else() add_library(my_lib STATIC my_lib.cpp) endif()

或者使用 CMake 的全局变量：

set(BUILD_SHARED_LIBS ON) # 全局设置为动态库 add_library(my_lib my_lib.cpp) # 默认创建动态库

7. 避免常见错误

错误1：忘记设置包含目录

# ❌ 错误 add_library(math_lib STATIC math_lib.cpp) add_executable(app main.cpp) target_link_libraries(app math_lib) # ✅ 正确 add_library(math_lib STATIC math_lib.cpp) target_include_directories(math_lib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) add_executable(app main.cpp) target_link_libraries(app math_lib)

错误2：链接顺序问题

# ❌ 可能有问题（依赖关系复杂时） target_link_libraries(app lib1 lib2 lib3) # ✅ 更好（明确依赖关系） target_link_libraries(app PRIVATE lib1 PRIVATE lib2 PRIVATE lib3 )

错误3：混淆 PUBLIC 和 PRIVATE

# ❌ 如果 my_lib.h 中使用了 utils_lib，应该用 PUBLIC target_link_libraries(my_lib PRIVATE utils_lib) # ✅ 正确 target_link_libraries(my_lib PUBLIC utils_lib)

总结

add_library和target_link_libraries是 CMake 中管理库的核心命令：

关键要点

add_library用于创建库：
- STATIC创建静态库
- SHARED创建动态库
- 记得使用target_include_directories设置包含目录
target_link_libraries用于链接库：
- 可以链接项目内的库和外部库
- 使用PRIVATE、PUBLIC、INTERFACE控制依赖传播
- 链接顺序通常不重要，CMake 会自动处理
最佳实践：
- 库的包含目录使用PUBLIC（如果头文件需要被外部使用）
- 明确指定链接可见性（PRIVATE/PUBLIC/INTERFACE）
- 使用target_include_directories而不是全局的include_directories

进一步学习

CMake 的find_package和find_library用于查找外部库
install命令用于安装库
export和CMakePackageConfigHelpers用于创建可重用的库包

掌握这两个命令，你就能在 CMake 项目中自如地创建和管理库了！

作者注：本文基于 CMake 3.10+ 版本。如果你使用的是较旧版本，某些特性可能不可用。建议使用 CMake 3.15 或更高版本以获得最佳体验。

相关资源：

CMake 官方文档
CMake 教程
Modern CMake 指南

如果这篇文章对你有帮助，欢迎点赞和分享！

CMake 库管理完全指南：add_library 与 target_link_libraries 详解

📚 目录

为什么需要库？

库的类型

add_library：创建库的魔法

基本用法

创建静态库

创建动态库

库类型详解

多源文件库

设置库的属性

target_link_libraries：连接一切的桥梁

基本用法

链接可见性

PRIVATE（私有链接）

PUBLIC（公共链接）

INTERFACE（接口链接）

实际示例对比

链接外部库

实战案例：完整项目示例

项目结构

源代码

CMakeLists.txt 完整配置

构建和运行

代码解析

常见问题与最佳实践

1. 什么时候使用静态库？什么时候使用动态库？

2. PUBLIC、PRIVATE、INTERFACE 如何选择？

3. 为什么需要设置包含目录？

4. 如何链接多个库？

5. 库的命名规范

6. 条件编译库

7. 避免常见错误

总结

关键要点

进一步学习

3步法揭秘：如何用提示工程让AI输出质量稳定提升72%

向量数据库集成中的常见陷阱与性能优化策略

Bananas：免费跨平台屏幕共享工具完整使用教程

终极指南：离线环境一键部署宝塔面板7.7.0

布隆过滤器的作用和原理

SMP语言基础知识-应用系统，应用系统，应用系统