一、为什么需要 CMake？#

单文件编译时手敲 g++ 没问题，但如果项目有十几个源文件，而且分布在不同文件夹里：

1
g++ src/main.cpp src/camera.cpp src/serial.cpp src/detector.cpp \
2
    -Iinclude -I/usr/local/include/opencv4 \
3
    -lopencv_core -lopencv_imgproc -lopencv_highgui -lpthread \
4
    -O3 -std=c++17 -o robot_app

这样手动编译有三个明显问题：

1. 命令太长，每次改动都要重新敲或者翻历史命令；
2. 只要动了一个文件，上面的命令会把所有文件全部从头编译一遍，项目变大后编译耗时很长；
3. 换到车载工控机或者队友电脑上，如果库的安装路径不一样，这串命令就报错了。

CMake 的作用是用一套跨平台的配置脚本（CMakeLists.txt），自动帮你生成底层的编译指令（Makefile）。你只需要维护好这个脚本，编译时敲两行命令或者在 VS Code 里按个快捷键就行。后续学 ROS2 时，它的底层编译规则本质上也是 CMake。

二、C++ 编译过程与两种常见报错#

在写 CMake 之前，先搞清楚 C++ 代码是怎么变成可执行程序的。整个过程主要分两步：

1
[源文件 .cpp] ──(编译阶段：检查语法、引入头文件)──> [目标文件 .o]
2
                                                        │
3
                                                 (链接阶段：把函数实现和库拼在一起)
4
                                                        ↓
5
                                                 [最终程序 robot_app]

平时排查编译错误，只要看懂这两类报错就能定位问题：

1
fatal error: target.hpp: No such file or directory

1
undefined reference to `TargetDetector::detect()'

三、规范的工程目录结构#

在机器人上位机项目中，通常使用下面的分层目录：

1
my_vision_project/
2
├── CMakeLists.txt        # 整个项目的编译配置文件
3
├── include/              # 存放所有头文件 (.hpp / .h)
4
│   └── detector.hpp
5
├── src/                  # 存放所有源文件实现 (.cpp)
6
│   ├── detector.cpp
7
│   └── main.cpp
8
└── build/                # 编译生成的中间文件和最终可执行文件都在这里

把编译产物集中放在 build/ 目录里（外部构建，Out-of-source Build）：
这样所有的临时文件（.o、Makefile）都在 build/ 内部，源码目录很干净。如果不小心编译出问题想从头来过，直接 rm -rf build/* 即可，不会误删源代码。

四、编写你的第一个 CMakeLists.txt#

在项目根目录下创建一个名为 CMakeLists.txt 的文件（注意大小写完全匹配）：

1
# 1. 规定 CMake 的最低版本要求
2
cmake_minimum_required(VERSION 3.16)
3

4
# 2. 项目名称、版本和语言
5
project(my_vision_project VERSION 1.0 LANGUAGES CXX)
6

7
# 3. 指定 C++ 标准为 C++17
8
set(CMAKE_CXX_STANDARD 17)
9
set(CMAKE_CXX_STANDARD_REQUIRED ON)
10

11
# 4. 生成可执行文件目标（Target）
12
add_executable(vision_app
13
    src/main.cpp
14
    src/detector.cpp
15
)
16

17
# 5. 为目标绑定头文件搜索路径（现代 CMake 规范：围绕 Target 进行配置）
18
# PRIVATE 表示该头文件路径仅供 vision_app 自己使用
19
target_include_directories(vision_app PRIVATE include)

1
# 1. 配置并生成构建目录（-B 自动创建 build 文件夹）
2
cmake -B build
3

4
# 2. 调用底层编译器开始并行构建（-j 自动使用全核）
5
cmake --build build -j
6

7
# 3. 运行生成的可执行程序
8
./build/vision_app

五、引入第三方库（以 OpenCV 为例）#

下一章我们要开始讲图像处理，所以先看在 CMake 里怎么引入外部库。现代 CMake 提供了一个专门查找库的命令：find_package。

修改 CMakeLists.txt：

1
cmake_minimum_required(VERSION 3.16)
2
project(my_vision_project VERSION 1.0 LANGUAGES CXX)
3

4
set(CMAKE_CXX_STANDARD 17)
5
set(CMAKE_CXX_STANDARD_REQUIRED ON)
6

7
# 查找系统里安装的 OpenCV 库（REQUIRED 表示如果找不到就直接报错停止）
8
find_package(OpenCV REQUIRED)
9

10
# 生成可执行文件
11
add_executable(vision_app
12
    src/main.cpp
13
    src/detector.cpp
14
)
15

16
target_include_directories(vision_app PRIVATE include)
17

18
# 链接库文件（OpenCV 4+ 导出的现代目标会自动处理依赖的头文件路径）
19
target_link_libraries(vision_app PRIVATE ${OpenCV_LIBS})

只要通过 sudo apt install libopencv-dev 安装过 OpenCV，find_package(OpenCV REQUIRED) 就能自动找到其配置，并通过 target_link_libraries 完成库链接。

六、在 VS Code 中一键构建与单步断点调试#

第二章我们在 VS Code 里安装了 CMake Tools 插件。配置好之后，日常开发就不需要频繁在终端里手动敲 cmake 和 make 了。

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "name": "CMake: Debug Current Target",
6
            "type": "cppdbg",
7
            "request": "launch",
8
            // 自动关联 CMake Tools 选中的目标，无需手动写死路径
9
            "program": "${command:cmake.launchTargetPath}",
10
            "args": [],
11
            "stopAtEntry": false,
12
            "cwd": "${workspaceFolder}",
13
            "environment": [],
14
            "externalConsole": false,
15
            "MIMode": "gdb",
16
            "setupCommands": [
17
                {
18
                    "description": "Enable pretty-printing for gdb",
19
                    "text": "-enable-pretty-printing",
20
                    "ignoreFailures": true
21
                }
22
            ]
23
        }
24
    ]
25
}

1
调试常用快捷键：
2
- F5：继续运行（Continue），直到遇到下一个断点；
3
- F10：单步跳过（Step Over），执行当前行，停在下一行；
4
- F11：单步进入（Step Into），如果当前行是一个函数调用，会跳进函数内部；
5
- Shift + F11：单步跳出（Step Out），直接执行完当前函数剩下的部分，返回到上一层调用处；
6
- Shift + F5：停止调试。

🎯 本章通关小作业#

请在本地建一个符合规范的最小工程并验证调试流程：

1. 搭建目录结构：

   1
   demo/
   2
   ├── CMakeLists.txt
   3
   ├── include/
   4
   │   └── math_utils.hpp
   5
   └── src/
   6
       ├── math_utils.cpp
   7
       └── main.cpp

2. 编写代码：
   • math_utils.hpp：声明一个函数 float calculate_3d_dist(float x, float y, float z);
   • math_utils.cpp：实现该函数（开方计算模长）
   • main.cpp：调用该函数并输出结果
3. 编写 CMakeLists.txt 并用现代命令（cmake -B build && cmake --build build -j）编译跑通。
4. 断点调试体验：
   • 在 VS Code 中打开该项目；
   • 在 main.cpp 调用函数的那一行打上断点；
   • 点击底部状态栏的“小虫子”或配置 launch.json 后按 F5 启动调试，按 F11 单步跳进 math_utils.cpp 内部，在左侧变量窗口观察传入的参数值。