CMake 010 ：一步到位链接静态库

Bilibili 同步视频

CMake 010 ：一步到位链接静态库

在跨平台 C++ 开发中，静态库编译 + 外部项目链接是高频且容易踩坑的环节。头文件找不到、符号未定义、链接失败…… 这些问题看似琐碎，却直接决定编译能否跑通。

本文以XLOG 日志库为例，从零到一完成：库编译 → 测试项目创建 → CMake 配置 → 双平台成功运行，把每一步错误与修复讲透，让你真正理解「预处理 - 编译 - 链接」三阶段到底在做什么。

一、先把地基打好：编译 XLOG 静态库

我们先确保 XLOG 本身编译完成，生成可用的静态库文件。

1.1 编译命令（标准 CMake out-of-source 构建）

# 进入 XLOG 根目录cdxlog# 生成构建文件（-S源码目录 . -B构建目录 build）cmake-S.-Bbuild# 开始编译cmake--buildbuild

1.2 库输出位置

• Linux：build/libxlog.a

• Windows：build/Debug/xlog.lib/build/Release/xlog.lib

✅ 关键：静态库统一放在 build 目录，后续链接只需要指向这个路径即可。

二、创建测试项目：test_xlog

我们在与 xlog 同级目录创建测试项目test_xlog，只做一件事：实例化 XLOG 对象，验证库能正常调用。

2.1 最简测试代码：test_xlog.cpp

#include<iostream>// 后续通过 CMake 指定路径#include"xlog.h"usingnamespacestd;intmain(){// 实例化 = 调用构造函数 = 必须链接到库实现XLog log;cout<<"test_xlog run success!"<<endl;return0;}

2.2 你会立刻遇到 3 个经典错误

这是 C++ 编译的标准三段式报错，必须理解：

1. 预处理错误：找不到xlog.h（头文件路径未指定）

2. 编译错误：找不到XLog类型声明（依然是头文件问题）

3. 链接错误：undefined reference 未定义符号（没链接静态库）

三、CMakeLists.txt 完整配置（核心！）

直接给可复制的完整版，每一行都加注释，一看就懂。

# CMake 最低版本要求 cmake_minimum_required(VERSION 3.20) # 项目名称 project(test_xlog) # ====================== # 1. 添加头文件搜索路径 # 相对路径：相对于本 CMakeLists.txt 所在目录 # ====================== include_directories(../xlog) # ====================== # 2. 添加库文件搜索路径 # ====================== link_directories(../xlog/build) # ====================== # 3. 生成可执行程序 # ====================== add_executable(${PROJECT_NAME} test_xlog.cpp) # ====================== # 4. 链接静态库（无需 lib 前缀 / .a / .lib） # ====================== target_link_libraries(${PROJECT_NAME} xlog)

关键语法解释

• include_directories(...)
  等价于g++ -I路径，告诉编译器去哪里找头文件。

• link_directories(...)
  告诉链接器库文件在哪个目录。

• target_link_libraries(目标 库名)
  给可执行文件绑定要链接的库，跨平台自动适配：

  • Linux：找libxlog.a

  • Windows：找xlog.lib

四、编译运行（两种路径都支持）

方式 1：源码目录执行（最常用）

cdtest_xlog cmake-S.-Bbuild cmake--buildbuild# 运行./build/test_xlog

方式 2：进入 build 目录执行

cdtest_xlog/build cmake..make# 或 cmake --build .

✅ 成功输出：

create xlog test_xlog run success!

五、Windows 平台注意事项（自动适配 Debug/Release）

Windows 下编译后，库会放在：

• Debug：xlog/build/Debug/xlog.lib

• Release：xlog/build/Release/xlog.lib

你不需要手动改路径！
CMake 会根据当前编译配置自动进入对应子目录查找库，一套 CMakeLists 全平台通用。

六、完整目录结构（一目了然）

./ ├── xlog/ # 日志库项目 │ ├── xlog.h │ ├── xlog.cpp │ └── build/ # 编译输出：libxlog.a / xlog.lib └── test_xlog/ # 测试项目 ├── CMakeLists.txt ├── test_xlog.cpp └── build/ # 测试程序输出

七、总结：链接静态库的 4 步万能公式

1. 编译库 → 得到.a/.lib

2. 用include_directories加头文件路径

3. 用link_directories加库路径

4. 用target_link_libraries绑定库

只要按这个流程，Linux / Windows / macOS三平台链接静态库，再也不会报错。