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

[Bilibili 同步视频](#Bilibili 同步视频)
[一、先把地基打好：编译 XLOG 静态库](#一、先把地基打好：编译 XLOG 静态库)
- [1.1 编译命令（标准 CMake out-of-source 构建）](#1.1 编译命令（标准 CMake out-of-source 构建）)
- [1.2 库输出位置](#1.2 库输出位置)
二、创建测试项目：test_xlog
- [2.1 最简测试代码：test_xlog.cpp](#2.1 最简测试代码：test_xlog.cpp)
- [2.2 你会立刻遇到 3 个经典错误](#2.2 你会立刻遇到 3 个经典错误)
[三、CMakeLists.txt 完整配置（核心！）](#三、CMakeLists.txt 完整配置（核心！）)
- 关键语法解释
四、编译运行（两种路径都支持）
- [方式 1：源码目录执行（最常用）](#方式 1：源码目录执行（最常用）)
- [方式 2：进入 build 目录执行](#方式 2：进入 build 目录执行)
[五、Windows 平台注意事项（自动适配 Debug/Release）](#五、Windows 平台注意事项（自动适配 Debug/Release）)
六、完整目录结构（一目了然）
[七、总结：链接静态库的 4 步万能公式](#七、总结：链接静态库的 4 步万能公式)

Bilibili 同步视频

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

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

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

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

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

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

bash 复制代码

# 进入 XLOG 根目录
cd xlog

# 生成构建文件（-S源码目录 . -B构建目录 build）
cmake -S . -B build

# 开始编译
cmake --build build

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

cpp 复制代码

#include <iostream>
// 后续通过 CMake 指定路径
#include "xlog.h"

using namespace std;

int main() {
    // 实例化 = 调用构造函数 = 必须链接到库实现
    XLog log;
    cout << "test_xlog run success!" << endl;
    return 0;
}

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

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

预处理错误 ：找不到 xlog.h（头文件路径未指定）
编译错误 ：找不到 XLog 类型声明（依然是头文件问题）
链接错误：undefined reference 未定义符号（没链接静态库）

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

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

cmake 复制代码

# 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：源码目录执行（最常用）

bash 复制代码

cd test_xlog
cmake -S . -B build
cmake --build build

# 运行
./build/test_xlog

方式 2：进入 build 目录执行

bash 复制代码

cd test_xlog/build
cmake ..
make  # 或 cmake --build .

✅ 成功输出：

Plain 复制代码

create xlog
test_xlog run success!

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

Windows 下编译后，库会放在：

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

你不需要手动改路径！

CMake 会根据当前编译配置自动进入对应子目录查找库，一套 CMakeLists 全平台通用。

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

Plain 复制代码

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

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

编译库 → 得到 .a / .lib
用 include_directories 加头文件路径
用 link_directories 加库路径
用 target_link_libraries 绑定库

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