CMake 笔记 - 技术栈

CMake 常用命令速查表

项目结构命令

命令	作用	示例
`project()`	定义项目	`project(MyApp VERSION 1.0)`
`add_executable()`	添加可执行文件	`add_executable(app main.cpp)`
`add_library()`	添加库	`add_library(mylib STATIC lib.cpp)`
`target_link_libraries()`	链接库	`target_link_libraries(app mylib)`
`add_subdirectory()`	添加子目录	`add_subdirectory(src)`

目录和文件

命令	作用	示例
`include_directories()`	包含目录	`include_directories(include)`
`target_include_directories()`	为目标包含目录	`target_include_directories(app PUBLIC include)`
`file()`	文件操作	`file(GLOB SRC "src/*.cpp")`

变量和属性

命令	作用	示例
`set()`	设置变量	`set(SRC_FILES main.cpp)`
`option()`	定义选项	`option(BUILD_TESTS "编译测试" ON)`
`message()`	打印信息	`message(STATUS "编译模式: ${CMAKE_BUILD_TYPE}")`

快速上手示例

最小CMakeLists.txt示例

bash 复制代码

# 1. 版本和项目定义
cmake_minimum_required(VERSION 3.10)  # 指定CMake最低版本
project(MyProject    # 项目名
    VERSION 1.0.0
    DESCRIPTION "我的C++项目"
    LANGUAGES CXX
)

# 2. 设置C++标准
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 3. 添加可执行文件
add_executable(myapp main.cpp utils.cpp)
# 或 ↓
add_executable(${PROJECT_NAME}
    src/main.cpp
    src/utils.cpp
    include/utils.h
)

# 4. 包含目录
target_include_directories(myapp PRIVATE include)
# 或 ↓
target_include_directories(${PROJECT_NAME}
    PUBLIC
        include
        ${PROJECT_SOURCE_DIR}/include
)

# 5. 添加库（链接库）
find_package(Threads REQUIRED)
target_link_libraries(myapp Threads::Threads)
# 或 ↓
find_package(Qt5 5.15.2 REQUIRED COMPONENTS Core Gui Widgets LinguistTools)
target_link_libraries(${PROJECT_NAME}
    PRIVATE
        Threads::Threads
)

VS Code 中配合 CMake 开发 C++

核心是配置好 CMake Tools 扩展。这套配置能让你获得接近 IDE 的智能提示和调试体验。

一、环境准备（安装清单）

VS Code 扩展 ：安装 C/C++ （微软官方）和 CMake Tools（Kitware 官方）这两个扩展。
编译器：确保系统已安装 GCC（MinGW-w64）或 Clang。
CMake ：版本建议 ≥ 3.15，并确保 cmake命令在终端中可用。

二、项目结构与配置

1. 标准目录结构

建议采用以下结构，VS Code 对此有很好的原生支持

步骤1：创建项目结构

cpp 复制代码

my_project/
├── CMakeLists.txt    # 根CMakeLists
├── .vscode/          # VS Code 配置文件夹
│   ├── settings.json
│   └── launch.json   # 调试配置
├── include/          # 头文件
│   └── utils.h
├── src/              # 源文件
│   ├── main.cpp
│   └── utils.cpp
└── build/            # 构建输出（建议.gitignore）

步骤2：编写根 CMakeLists.txt

bash 复制代码

cmake_minimum_required(VERSION 3.10)
project(HelloWorld)

# 查找所有源文件
file(GLOB SRC_FILES "src/*.cpp")
file(GLOB HEADER_FILES "include/*.h")

# 添加可执行文件
add_executable(hello ${SRC_FILES} ${HEADER_FILES})

# 包含目录
target_include_directories(hello PRIVATE include)

# 设置C++标准
set_target_properties(hello PROPERTIES
    CXX_STANDARD 17
    CXX_STANDARD_REQUIRED ON
)

步骤3：多文件项目

bash 复制代码

# 更推荐的方式：显式列出文件
set(SOURCE_FILES
    src/main.cpp
    src/utils.cpp
    src/math.cpp
)

set(HEADER_FILES
    include/utils.h
    include/math.h
)

add_executable(hello ${SOURCE_FILES} ${HEADER_FILES})

2. 基础 CMakeLists.txt 模板

这是 VS Code 环境下最实用的入门配置，直接复制使用：

cpp 复制代码

cmake_minimum_required(VERSION 3.15)
project(MyProject VERSION 1.0 LANGUAGES CXX)

# 1. 设置C++标准（必须，否则IntelliSense可能报错）
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 2. 自动包含当前目录和include目录（方便头文件跳转）
target_include_directories(${PROJECT_NAME} PRIVATE include)

# 3. 添加可执行文件（自动搜索src/*.cpp）
file(GLOB_RECURSE SRC_FILES "src/*.cpp")
add_executable(${PROJECT_NAME} ${SRC_FILES})

三、VS Code 工作流（实操步骤）

1. 打开与配置

打开项目 ：直接打开包含 CMakeLists.txt的根目录。
选择Kit ：底部状态栏点击 [Unconfigured]，选择你的编译器（如 GCC）。
选择Variant ：点击状态栏 [Debug]选择构建模式（Debug/Release）。

2. 构建与运行

配置：Ctrl + Shift + P→ CMake: Configure。
构建：Ctrl + Shift + P→ CMake: Build或点击状态栏 [Build]。
运行：底部状态栏点击 ▶（三角图标）运行程序。

3. 调试（关键步骤）

VS Code 调试需要配置 launch.json 。在 .vscode/文件夹下创建：

cpp 复制代码

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "CMake Debug",
            "type": "cppdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}", // 自动获取CMake目标路径
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "启用反汇编",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ],
            "preLaunchTask": "cmake: build" // 调试前自动构建
        }
    ]
}

配置好后，按 F5即可直接启动调试。

实例 .vscode/launch.json：

cpp 复制代码

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "GalvanoCalibration Debug",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build_debug/bin/GalvanoCalibration.exe",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}/build_debug/bin",
      "environment": [
        {
          "name": "PATH",
          "value": "${env:QT_ROOT}\\bin;${workspaceFolder}\\ThirdParty\\HuaraySDK\\Runtime\\x64;%PATH%"
        }
      ],
      "console": "internalConsole"
    },
    {
      "name": "GalvanoCalibration Release",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build_release/bin/GalvanoCalibration.exe",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}/build_release/bin",
      "environment": [
        {
          "name": "PATH",
          "value": "${env:QT_ROOT}\\bin;${workspaceFolder}\\ThirdParty\\HuaraySDK\\Runtime\\x64;%PATH%"
        }
      ],
      "console": "internalConsole",
      "preLaunchTask": "Build Release"
    }
  ]
}

实例 .vscode/tasks.json：

bash 复制代码

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Configure Debug",
      "type": "shell",
      "command": "${env:CMAKE_ROOT}\\bin\\cmake.exe",
      "args": [
        "--preset",
        "vs2019-debug"
      ],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": []
    },
    {
      "label": "Build Debug",
      "type": "shell",
      "command": "${env:CMAKE_ROOT}\\bin\\cmake.exe",
      "args": [
        "--build",
        "--preset",
        "vs2019-debug",
        "--",
        "/m",
        "/verbosity:minimal"
      ],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "dependsOn": [
        "Configure Debug"
      ],
      "problemMatcher": "$msCompile",
      "group": "build"
    },
    {
      "label": "Configure Release",
      "type": "shell",
      "command": "${env:CMAKE_ROOT}\\bin\\cmake.exe",
      "args": [
        "--preset",
        "vs2019-release"
      ],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": []
    },
    {
      "label": "Build Release",
      "type": "shell",
      "command": "${env:CMAKE_ROOT}\\bin\\cmake.exe",
      "args": [
        "--build",
        "--preset",
        "vs2019-release",
        "--",
        "/m",
        "/verbosity:minimal"
      ],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "dependsOn": [
        "Configure Release"
      ],
      "problemMatcher": "$msCompile",
      "group": "build"
    }
  ]
}

四、常见问题与优化

1. IntelliSense 报错（红色波浪线）

如果代码没错但提示报错，通常是配置未刷新：

强制刷新 ：Ctrl + Shift + P→ CMake: Delete Cache and Reconfigure。
检查配置 ：确保 CMakeLists.txt中的 include_directories路径正确。

2. 多文件项目管理

对于复杂的多目录项目，建议使用 add_subdirectory进行模块化拆分：

cpp 复制代码

# 根目录 CMakeLists.txt
add_subdirectory(lib/mylib)
add_subdirectory(src)

cpp 复制代码

# lib/mylib/CMakeLists.txt
add_library(mylib STATIC mylib.cpp)
target_include_directories(mylib PUBLIC .) # PUBLIC让依赖者自动包含头文件

3. 推荐 VS Code 配置（settings.json）

cpp 复制代码

{
    "cmake.generator": "Ninja",           // 构建更快
    "cmake.buildDirectory": "${workspaceFolder}/build",
    "cmake.configureOnOpen": true,        // 打开即配置
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" // 让C++插件读取CMake配置
}

实例 settings.json：

cpp 复制代码

{
  "cmake.useCMakePresets": "always",
  "cmake.configurePreset": "vs2019-debug",
  "cmake.buildPreset": "vs2019-debug",
  "cmake.cmakePath": "${env:CMAKE_ROOT}/bin/cmake.exe",  //读系统环境变量CMAKE_ROOT
  "cmake.configureOnOpen": true,        // 打开即配置
  "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" // 让C++插件读取CMake配置
}

进阶示例：模块化项目

项目结构

bash 复制代码

myapp/
├── CMakeLists.txt
├── app/
│   ├── CMakeLists.txt
│   └── main.cpp
├── lib/
│   ├── math/
│   │   ├── CMakeLists.txt
│   │   ├── include/mathlib.h
│   │   └── src/mathlib.cpp
│   └── utils/
│       ├── CMakeLists.txt
│       ├── include/utils.h
│       └── src/utils.cpp
└── tests/
    ├── CMakeLists.txt
    └── test_math.cpp

根 CMakeLists.txt

bash 复制代码

cmake_minimum_required(VERSION 3.10)
project(MyApp VERSION 1.0.0)

# 包含子目录
add_subdirectory(lib/math)
add_subdirectory(lib/utils)
add_subdirectory(app)
add_subdirectory(tests)  # 可选测试

库的 CMakeLists.txt

bash 复制代码

# lib/math/CMakeLists.txt
add_library(mathlib STATIC
    src/mathlib.cpp
    include/mathlib.h
)

target_include_directories(mathlib
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
)

target_compile_features(mathlib PRIVATE cxx_std_17)

应用的 CMakeLists.txt

bash 复制代码

# app/CMakeLists.txt
add_executable(myapp main.cpp)

target_link_libraries(myapp
    PRIVATE
        mathlib
        utils
)

target_include_directories(myapp
    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}
)