【CMake】静态库的编译、链接与引用全解析

🔥草莓熊Lotso： 个人主页
❄️个人专栏: 《C++知识分享》《Linux 入门到实践：零基础也能懂》
✨生活是默默的坚持，毅力是永久的享受！

🎬 博主简介：

文章目录

前言：
[一. 静态库基础与 CMake 核心模型](#一. 静态库基础与 CMake 核心模型)
- [1.1 什么是静态库](#1.1 什么是静态库)
- [1.2 CMake 三大核心：目标 - 属性 - API](#1.2 CMake 三大核心：目标 - 属性 - API)
- [1.3 属性传递机制：PRIVATE/PUBLIC/INTERFACE](#1.3 属性传递机制：PRIVATE/PUBLIC/INTERFACE)
[二. 实战：构建并引用内部静态库](#二. 实战：构建并引用内部静态库)
- [2.1 项目目录结构](#2.1 项目目录结构)
- [2.2 编写静态库代码](#2.2 编写静态库代码)
- [2.3 编写 CMake 配置文件](#2.3 编写 CMake 配置文件)
- [2.4 编译与运行](#2.4 编译与运行)
[三. 深入解析：CMake 静态库生成与定位原理](#三. 深入解析：CMake 静态库生成与定位原理)
- [3.1 静态库生成与定位的四个步骤](#3.1 静态库生成与定位的四个步骤)
- [3.2 验证：使用生成器表达式打印库路径](#3.2 验证：使用生成器表达式打印库路径)
[四. 核心命令源码级解读](#四. 核心命令源码级解读)
- [4.1 add_library](#4.1 add_library)
- [4.2 target_include_directories](#4.2 target_include_directories)
- [4.3 target_link_libraries](#4.3 target_link_libraries)
- [4.4 set_target_properties](#4.4 set_target_properties)
[五. 最佳实践与常见问题](#五. 最佳实践与常见问题)
- [5.1 最佳实践](#5.1 最佳实践)
- [5.2 常见问题解决](#5.2 常见问题解决)
结尾：

前言：

在 C/C++ 项目开发中，代码复用是提升开发效率的核心手段。当项目规模逐渐扩大，我们往往会将独立的功能模块（如网络通信、数据处理、算法实现）封装成库文件，供多个模块或项目共享使用。传统的手写 Makefile 方式管理静态库不仅语法复杂、跨平台性差，而且在处理依赖传递时极易出错。CMake 作为 C/C++ 领域事实上的构建标准，通过基于目标的属性传递机制，完美解决了静态库的构建、链接与引用问题。本文将从静态库的基础原理出发，结合完整的实战项目，深入解析 CMake 中静态库管理的核心逻辑，带你掌握现代 CMake 构建静态库的最佳实践。

一. 静态库基础与 CMake 核心模型

1.1 什么是静态库

静态库（Static Library）是在编译期 将一组目标文件（.o/.obj）打包成一个归档文件的集合。在链接阶段，链接器会将静态库中实际用到的目标文件完整复制到最终的可执行文件中。

文件格式 ：Linux/macOS 下为.a（ar 归档格式），Windows 下为.lib（COFF 归档格式）
核心特点 ：
- 运行时不需要依赖库文件，可执行文件可以独立运行
- 可执行文件体积较大，包含了所有用到的库代码
- 库更新后需要重新编译链接所有使用该库的程序

详细的可以看 ：飞书笔记

1.2 CMake 三大核心：目标 - 属性 - API

CMake 是一个基于目标的属性传递现代化构建系统 ，其核心逻辑可以用三个概念概括：目标（Target） 、属性（Property） 和 API。

目标（Target）

目标是 CMake 的基本构建单元，代表了一个需要生成的实体。常见的目标类型包括：

目标类型	创建命令	产物示例	说明
EXECUTABLE	`add_executable`	`main`、`curl`	可执行文件
STATIC	`add_library(... STATIC)`	`libfoo.a`、`foo.lib`	静态库
SHARED	`add_library(... SHARED)`	`libfoo.so`、`foo.dll`	动态库
INTERFACE	`add_library(... INTERFACE)`	无实体文件	纯接口库，仅携带使用要求
IMPORTED	`add_library(... IMPORTED)`	引用外部已存在的库	导入目标，引用磁盘上的预编译库
ALIAS	`add_library(... ALIAS)`	为现有目标取别名	内部使用小名，外部使用大名

属性（Property）

属性是目标的 "键值对"，用于控制目标的编译、链接、输出等行为。CMake 中的属性分为多个作用域：

属性类别	作用域	典型命令	常用属性示例
目标属性	单个构建目标	`set_target_properties`	`INCLUDE_DIRECTORIES`、`LINK_LIBRARIES`
目录属性	当前目录及子目录	`set_property(DIRECTORY)`	`INCLUDE_DIRECTORIES`
全局属性	整个 CMake 运行周期	`set_property(GLOBAL)`	`CMAKE_ROLE`

API

API 是操作目标和属性的命令集合，主要分为四类：

通用读写接口 ：set_target_properties()、get_target_property()
编译阶段相关 ：target_compile_definitions、target_include_directories
链接阶段相关 ：target_link_libraries、target_link_directories
安装打包相关 ：install(TARGETS)、export()

CMake 构建流程

CMake 的整个构建过程分为四个阶段：

配置期：解析 CMakeLists.txt，注册目标并写入属性
生成期：将目标属性转换为具体的构建系统文件（如 Makefile）
构建期：执行编译和链接操作，生成目标文件
安装期：根据安装规则将产物复制到指定目录

1.3 属性传递机制：PRIVATE/PUBLIC/INTERFACE

CMake 最强大的特性之一就是自动属性传递 。通过PRIVATE、PUBLIC、INTERFACE三个关键字，我们可以精确控制属性的传播范围。

我们用一个 "面包制作" 的例子来理解这三个关键字：

关键字	对当前目标的构建影响	是否传播	对使用者的影响	解释	面包例子
PRIVATE	✅ 生效	❌ 否	❌ 不生效	仅当前目标自己使用	制作面包的面粉品牌，不需要告诉消费者
PUBLIC	✅ 生效	✅ 是	✅ 生效	当前目标和使用者都需要	面包的成分表，自己生产需要，消费者也需要知道
INTERFACE	❌ 不生效	✅ 是	✅ 生效	仅使用者需要，当前目标不用	面包的食用说明书，自己生产不用，消费者必须看

核心原则 ：遵循最小暴露原则，能用PRIVATE就不用PUBLIC，能用PUBLIC就不用INTERFACE。

二. 实战：构建并引用内部静态库

我们通过一个数学库的例子，完整演示如何使用 CMake 构建并引用项目内部的静态库。我们将实现一个包含加法和减法函数的MyMath静态库，并在主程序中调用这两个函数。

2.1 项目目录结构

首先创建如下的项目目录结构：

bash 复制代码

my_math/
├── CMakeLists.txt    # 顶层CMake配置文件
├── app/              # 应用程序目录
│   ├── CMakeLists.txt
│   └── main.cpp      # 主程序
└── my_lib/           # 静态库目录
    ├── CMakeLists.txt
    ├── include/      # 头文件目录
    │   └── math.h    # 数学库头文件
    └── src/          # 源文件目录
        ├── add.cpp   # 加法实现
        └── sub.cpp   # 减法实现

2.2 编写静态库代码

my_lib/include/math.h

cpp 复制代码

#ifndef MATH_H
#define MATH_H

// 加法函数声明
int add(int a, int b);

// 减法函数声明
int sub(int a, int b);

#endif // MATH_H

my_lib/src/add.cpp

cpp 复制代码

#include "math.h"

int add(int a, int b) {
    return a + b;
}

my_lib/src/sub.cpp

cpp 复制代码

#include "math.h"

int sub(int a, int b) {
    return a - b;
}

app/main.cpp

cpp 复制代码

#include <iostream>
#include "math.h"

int main() {
    std::cout << "3 + 4 = " << add(3, 4) << std::endl;
    std::cout << "3 - 4 = " << sub(3, 4) << std::endl;
    return 0;
}

2.3 编写 CMake 配置文件

顶层 CMakeLists.txt

cmake 复制代码

# 设置CMake最低版本要求
cmake_minimum_required(VERSION 3.18)

# 设置项目名称
project(TestMyMath LANGUAGES CXX)

# 添加子目录，CMake会自动进入子目录执行对应的CMakeLists.txt
add_subdirectory(my_lib)  # 先构建静态库
add_subdirectory(app)     # 再构建应用程序

my_lib/CMakeLists.txt（静态库配置）

cmake 复制代码

# 1. 收集库的源代码文件
file(GLOB SRC_LISTS "src/*.cpp")

# 2. 添加静态库目标
add_library(MyMath STATIC ${SRC_LISTS})

# 3. 设置库的头文件搜索路径
# PUBLIC表示：当前库编译时需要，并且使用该库的目标也需要
target_include_directories(MyMath
    PUBLIC ${CMAKE_CURRENT_LIST_DIR}/include
)

# 4. 修改静态库的默认输出路径到build/lib目录
set_target_properties(MyMath PROPERTIES
    ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
)

app/CMakeLists.txt（应用程序配置）

cmake 复制代码

# 1. 收集应用程序的源代码文件
file(GLOB SRC_LISTS "*.cpp")

# 2. 添加可执行文件目标
add_executable(main ${SRC_LISTS})

# 3. 链接静态库MyMath
# PRIVATE表示：仅当前可执行文件需要，不会传递给其他目标
target_link_libraries(main PRIVATE MyMath)

# 4. 修改可执行文件的默认输出路径到build/bin目录
set_target_properties(main PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin
)

2.4 编译与运行

执行以下命令完成编译和运行：

bash 复制代码

# 创建构建目录并进入
mkdir build && cd build

# 配置项目，生成Makefile
cmake ..

# 编译项目
make

# 运行程序
./bin/main

运行结果：

Plain 复制代码

3 + 4 = 7
3 - 4 = -1

编译完成后，build目录下会生成：

lib/libMyMath.a：静态库文件
bin/main：可执行文件

三. 深入解析：CMake 静态库生成与定位原理

很多初学者会疑惑：CMake 是如何知道静态库的位置，并让可执行文件正确链接到它的？下面我们深入解析这个过程。

3.1 静态库生成与定位的四个步骤

当你写下add_library(MyMath STATIC add.cpp sub.cpp)时，CMake 内部会执行以下四个步骤：

第一步：目标注册

CMake 会在全局的Targets容器中注册一个名为MyMath的cmTarget对象，记录目标的类型（静态库）、源文件列表等基本信息。

第二步：目标信息存储

每个cmTarget对象内部会维护一个属性表，存储该目标的所有属性。当你使用set_target_properties修改输出路径时，CMake 会更新ARCHIVE_OUTPUT_DIRECTORY属性的值。

第三步：生成器阶段推导路径

配置阶段结束后，CMake 进入生成阶段。生成器会遍历所有目标，根据目标的属性和平台规则，推导出静态库的实际输出路径。例如在 Linux 下，静态库的默认输出路径是${CMAKE_CURRENT_BINARY_DIR}/libMyMath.a。

第四步：生成链接命令

生成器会为每个目标生成对应的链接规则。对于依赖MyMath的main目标，CMake 会在 Makefile 中生成如下链接命令：

bash 复制代码

g++ main.o -o main ../lib/libMyMath.a

这样，链接器就能准确找到并链接静态库文件。

3.2 验证：使用生成器表达式打印库路径

我们可以使用 CMake 的生成器表达式 $<TARGET_FILE:Target>来验证静态库的输出路径。生成器表达式会在生成阶段动态计算并展开为目标的实际路径。

修改app/CMakeLists.txt，添加以下自定义命令：

cmake 复制代码

# 添加构建后命令，打印静态库的输出路径
add_custom_command(
    TARGET main POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E echo "静态库路径：$<TARGET_FILE:MyMath>"
    COMMENT "获取静态库的输出路径"
)

重新编译后，你会看到如下输出：

Plain 复制代码

[100%] Linking CXX executable ../bin/main
静态库路径：/home/bit/workspace/CMakeClass/my_math/build/lib/libMyMath.a
[100%] Built target main

我们还可以查看app/CMakeFiles/main.dir/link.txt文件，确认链接命令：

bash 复制代码

cat app/CMakeFiles/main.dir/link.txt

输出内容类似：

Plain 复制代码

/usr/bin/c++ CMakeFiles/main.dir/main.cpp.o -o ../bin/main ../lib/libMyMath.a

这完全验证了我们上面的分析。

四. 核心命令源码级解读

4.1 add_library

函数原型：

cmake 复制代码

add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [<source>...])

参数解释：

<name>：库的名称，项目内部必须唯一。CMake 会自动添加平台相关的前缀和后缀，例如在 Linux 下，MyMath会生成libMyMath.a
STATIC：创建静态库（默认值，不指定类型时使用）
SHARED：创建动态库
MODULE：创建插件库，使用dlopen运行时加载
<source>：构建库的源文件列表

4.2 target_include_directories

函数原型：

cmake 复制代码

target_include_directories(<target>
    [SYSTEM] [BEFORE]
    <INTERFACE|PUBLIC|PRIVATE> path1 [path2 ...]
    [<INTERFACE|PUBLIC|PRIVATE> pathN ...]
)

参数解释：

<target>：目标名称，由add_executable或add_library创建
SYSTEM：告诉编译器这些是系统头文件，GCC/Clang 会使用-isystem而非-I，抑制第三方头文件的警告
BEFORE：将路径插入到已有列表的最前面
<INTERFACE|PUBLIC|PRIVATE>：属性作用域关键字

最佳实践 ：永远使用 **target_include_directories而不是全局的 include_directories**。全局命令会将头文件路径添加到所有目标，容易导致路径冲突和不必要的依赖暴露。

4.3 target_link_libraries

函数原型：

cmake 复制代码

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

底层实现：

PRIVATE：仅设置目标的LINK_LIBRARIES属性，不会传播
PUBLIC：同时设置LINK_LIBRARIES和INTERFACE_LINK_LIBRARIES属性，会传播给使用者
INTERFACE：仅设置INTERFACE_LINK_LIBRARIES属性，仅传播给使用者

核心作用：

设置目标的依赖库列表，最终以-l的形式出现在 gcc 参数中
建立依赖关系链，让属性可以沿着链条自动传播

4.4 set_target_properties

函数原型：

cmake 复制代码

set_target_properties(<target1> <target2> ...
    PROPERTIES <prop1> <value1> <prop2> <value2> ...
)

常用属性：

ARCHIVE_OUTPUT_DIRECTORY：静态库的输出目录
LIBRARY_OUTPUT_DIRECTORY：动态库的输出目录
RUNTIME_OUTPUT_DIRECTORY：可执行文件的输出目录
OUTPUT_NAME：目标文件的输出名称
VERSION：库的版本号
SOVERSION：库的 API 版本号

五. 最佳实践与常见问题

5.1 最佳实践

使用现代 CMake 风格 ：优先使用target_*系列命令，避免全局命令（如include_directories、link_directories）
合理使用属性关键字：遵循最小暴露原则，只暴露必要的接口
统一输出路径 ：将所有库文件和可执行文件输出到统一的lib和bin目录，方便管理
谨慎使用 file (GLOB) ：file(GLOB)不会自动检测新增文件，新增源文件后需要重新执行cmake ..
目标命名规范：使用有意义的目标名称，避免与系统库或第三方库冲突

5.2 常见问题解决

问题 1：VS Code 中头文件出现红色下划线

这是因为 VS Code 的 C/C++ 扩展不知道头文件的搜索路径。解决方法：

鼠标放在下划线处，点击 "Quick Fix"
选择 "Add to includePath"
或者直接编辑.vscode/c_cpp_properties.json，在includePath中添加头文件路径：
1.
json 复制代码
```
"includePath": [
    "${workspaceFolder}/**",
    "${workspaceFolder}/my_lib/include"
]
```

问题 2：静态库链接顺序错误

CMake 会自动处理目标之间的依赖顺序，但如果链接的是外部静态库，需要注意顺序：被依赖的库要放在依赖它的库后面。

问题 3：目标名称冲突

如果项目中有多个同名目标，CMake 会报错。解决方法是使用命名空间或给目标添加前缀，例如MyMath::MyMath。

结尾：

html 复制代码

🍓 我是草莓熊 Lotso！若这篇技术干货帮你打通了学习中的卡点：
👀 【关注】跟我一起深耕技术领域，从基础到进阶，见证每一次成长
❤️ 【点赞】让优质内容被更多人看见，让知识传递更有力量
⭐ 【收藏】把核心知识点、实战技巧存好，需要时直接查、随时用
💬 【评论】分享你的经验或疑问（比如曾踩过的技术坑？），一起交流避坑
🗳️ 【投票】用你的选择助力社区内容方向，告诉大家哪个技术点最该重点拆解
技术之路难免有困惑，但同行的人会让前进更有方向～愿我们都能在自己专注的领域里，一步步靠近心中的技术目标！

结语：本文从原理到实战，全面讲解了 CMake 中静态库的构建、链接与引用。我们学习了：静态库的本质和特点，CMake 的三大核心：目标、属性、API，属性传递机制的三个关键字：PRIVATE、PUBLIC、INTERFACE，完整的静态库项目构建流程，CMake 内部静态库生成与定位的原理，核心命令的源码级解读和最佳实践。CMake 基于目标的属性传递机制是现代构建系统的核心思想，它让复杂的依赖管理变得简单优雅。掌握了静态库的管理，你就已经掌握了 CMake 一半的精髓。在下一篇文章中，我们将继续深入学习如何将静态库安装到系统目录，并使用find_package命令在其他项目中查找和引用我们发布的库。

✨把这些内容吃透超牛的！放松下吧✨ ʕ˘ᴥ˘ʔ づきらど