06.VSCODE：备战大项目，CMake专项配置

娇小灵活的简捷配置不过是年轻人谈情说爱的玩具，帝国大厦的构建，终归要交给CMake去母仪天下。一个没有使用 CMake 的 C++ 项目，就像未来世界里的一台相声表演，有了德纲却无谦，观众笑着遗憾。—— 语出《双城记》作者，英国批判现实主义文学的开拓者查尔斯．狄更斯。

C++ 和 CMake 的双城记
版权声明：

《双城记》是查尔斯．狄更斯写的
中文版是叶红译的
书（包括封面设计）是长江文艺出版社的
郭德纲肯定是郭德纲的爸妈生的
于谦按理说是于谦的爸妈生的
C++是 Bjarne Stroustrup 无性繁殖的
CMake是 Bill Hoffman无性繁殖的
这个破课程，是南郁-第2学堂剖腹产的

欢迎关注本课程在CSDN的完整专栏。欢迎到 d2school.com 查看更多相关课程。

这节课，我们的任务是：

通过 msys2 安装 CMake
在 vscode 创建 CMake 专项配置
CMake 扩展基本设置
CMake 项目演示
CMake 扩展高级配置（其实就是状态栏的几个入口）

备战C/C++大项目，创建CMake专项配置

零、课堂视频

同样，请先看不到9分钟的视频，过程中不必一边看一边跟着操作，完整流畅地看完整个演示视频，再跟着本课堂的文本内容操作，必要时采用复制粘贴，更高效，更不会出错。

VSCODE：备战大项目，CMake专项配置

一、安装 CMake

可以在 Windows 下，可以通过 CMake 官网下载合适的安装程序（注意 32/64 位之分），独立安装 CMake，但我们推荐在 msys2 环境内下载。如果你两个都下载安装了，注意去除 Windows 环境中的路径（PATH）变量，并确保清楚自己在使用哪一个 CMake 可执行程序。

在 msys2 环境内安装 CMake 非常简单，进入对应的环境（本课程一直使用 UCRT，具体说明见课程第1节《MSYS2+GCC 安装与应用》），仍然是通过一行 pacman 指令安装：

pacman -S mingw-w64-ucrt-x86_64-cmake

如图：
在 msys2 中安装CMake

简介：Ninja / 忍者

图中可见，CMake 包含的软件包不少，其中比较重要的是 Ninja 包（https://ninja-build.org/。它是 Google 公司推出且广为使用的，可显著提升软件项目构建速度的工具。不过 CMake 完全可以脱离 Ninja 使用，但是，我们的目标~~是星辰大海~~是复杂、大型的C++项目构建，所以选择 NinJia 是必然的。并且，用它也无需多学什么，不用白不用。

如果你是在 msys2 外独立安装 CMake ，记得要检查是否有附上 Ninja。

完成安装后，可在 msys2-ucrt 环境下，通过下面这条指令（其实是四条命令结合在一起）查看 CMake 安装位置、CMake 的版本、Ninja 安装位置以及 Ninja 版本。

whereis cmake && cmake --version && whereis ninja && ninja --version

如图：
CMake及Ninja的安装位置与版本号

显示的可执行文件位置均相对于当初你安装 msys2 （通常是 msys64）根目录，所以你的任务是在 Windows 资源管理里找到 cmake.exe 和 ninja.exe。

当前我装的是 CMake 3.30.5，Ninja 1.12.1，到你安装时应该是更是高版本了。

二、创建 CMake 专用配置

2.1 创建 CM-CPP-CMake 配置

打开 VSCODE，通过主菜单或左侧边栏底部的小齿轮按钮，进入 “配置文件” 管理页面，如图：
进入VSCODE配置页

现有的 CS-CPP-Simple 是前面C/C++简捷项目专用配置课堂中，我们为 C++ 小项目创建的专用配置（Profile）——为什么我们要特意提到它？因为，这节课我们新配置的创建，必须基于简捷配置（划重点）。

① 点击页面中大大的 “新建配置文件” 按钮；
② 输入名字 “CM-CPP-CMake”；
③ 接着，在 “复制自” 一栏的下拉列表中，选中 “CS-CPP-Simple”——关键步骤;
④ 点右下 “创建” 按钮。

全部过程如下图：
四步创建CMake专用配置

其中关键的第3步，是为了在新建的配置中，继续复用之前我们在 CS-CPP-Simple（C++简捷项目专用配置）中的 C/C++ 扩展和它的设置。

小心宫斗戏！

当然，后面我们需要对部分设置做修改，从而 “弱化” C/C++ 扩展的影响，避免这两位在后宫当着皇帝面宫斗不休，烦得很（皇帝当然就是用户，也就是我们）。

完成创建后，立即在左侧配置列表中，仔细找 “CM-CPP-CMake” ，并将它设置成活动配置（之所以强调 “仔细找”，是因为此处的配置列表项，是按名称排序的，新建的配置很有可能会突然变成第二项）。

2.2 选择专用颜色主题

完成切换后，我眼前一黑，于是我按下 Ctrl+K, T（这个热键还记得吧？逗号是不用输入的哦），纠结了两个小时后，我决定就使用 “深色主题+”（Default Dark+），它的特征也是深色，但状态栏是彩的。

设有专用配色的CMake专项配置
顺便，检查一下图中箭头指示的位置，C/C++扩展已经在我们的新配置中，这是一眼可见的。不可见的是，像取消 UNICODE 特殊符号警告、以及 C/C++ 代码智能提示所使用的语言标准（我们用的都是17)等等设置，我们都不用重复再做一遍了。

三、调整 C/C++ 相关设置

3.1 问题：朕有新欢了……

朕有新欢其实不成问题，问题根源在于：1.有新欢后，旧欢的出现就是错；2.偏偏，新欢要正常工作还离不开旧欢？

VSCODE自带通用调试、C/C++ 扩展、以及下一步我们要安装的 CMake 扩展，都提供了一和编译、运行、调试相关的界面组件，典型的如我们在 CS-CPP-Simple 配置下经常要用到的，位于活动文件右上角的：添加调试配置、运行或调试当前活动文件(或工作区内所有源文件）等操作入口：

需要关闭的操作入口示意

不仅右上角，左下角也有。在C/C++的默认设置下，当我们第一次启动调试，状态栏右端位置，还会出现一个用于选择调试任务的入口，如图：

低调的调试状态栏

这项入口的来源倒不是 C/C++ 扩展，而是 VSCODE 自带的调试功能。

有了 CMake 扩展，图中标示的操作入口不是没用，而是有错（基本上就是你一误点就出错），可是它们不会主动躲开，而是天天在我们眼前晃，严重影响我们和新欢，哦不，是和新扩展的感情，所以我们要去除它，从而为新欢留出床位。

3.2 方法：仅在表面上废弃旧欢……

（一）确保在新建的 CM-CPP-CMake 配置下，如果有打开工作区或文件夹，建议先关闭，然后打开设置页（热键：Ctrl + ,），确保位于 “用户”级别下；

（二）在设置项过滤栏输入 “Cpp Debug Shortcut”，将得到 “C_Cpp: Debug Shortcut” 设置项，去除其下 “Show ‘Run and Debug’ play button and ‘Add Deubg Configuration’ gear ……” 的选中状态，如图：
关闭C/C++构建快捷入口

（三）过滤栏输入 “Debug Show in Status Bar”，然后在和过滤内容同名的设置内，从下拉框中选择 “never” （操作时适合的内心戏：无情帝王冲废后咆啸：“NEVER!” ）
调试状态栏永不显示
很可惜，以上操作只是在界面上将 C/C++ 扩展的相关操作入口隐藏，更容易搞混热键入口并没有关闭。

四、安装 CMake 扩展

可以开始迎娶新娘娘了……
确保处于 CM-CPP-CMake 配置下……然后在扩展市场找到出于微软的 “CMake Tools”（这个扩展包包含 CMake 的扩展），安装它。

安装 CMake 扩展

五、设置 CMake 扩展

5.1 基础步骤

（一）确保在新建的 CM-CPP-CMake 配置下，如果有打开工作区或文件夹，建议先关闭，然后打开设置页（热键：Ctrl + ,），确保位于 “用户”级别下；

（二）可以先在左边树形设置目录中，找到 “扩展 / CMake Tools”，整体看看CMake 扩展的众多设置项。

5.2 设置 CMake 可执行路径

我们历来不建议在 Windows 环境变量中添加全局路径，因此，装完 CMake 扩展之后，首先要告诉 VSCODE 上哪里去找 CMake.exe 。

（一）设置过滤栏内输入：CMake Path，找到过滤内容同名的设置项内，填写 cmake 可执行程序的完整路径，在本课程中是 “c:\msys64\ucrt64\bin\cmake.exe”，注意，因为是在图形界面填写，所以此处路径分隔符无需转义：
设置 cmake.exe 绝对路径
（我就曾不小心把 ucrt64 写成 urct64……）

（二）另外，我们还需为 CMake 指定上哪里找编译器。过滤栏输入 “Cmake Additional Compiler Search Dirs”，点“添加项”后，输入“c:\msys64\ucrt64\bin”，最后“确定”，如图：
添加CMake搜索编译器的可先路径

未来你可能需要使用CMake在同一个项目中，支持多种编译器（比如在 Linux下使用gcc,在Mac下使用 clang），到时记得在这里添加更多编译器的位置。

5.3 让 CMake 使用 Ninja

CMake 是母后，它能生成多种制作文件和多家IDE（比如 Visual Studio 、Code::Blocks）的项目文件，现在我们要让它固定生成 Ninja 所需的制作文件。输入 “CMake Generator”过滤，然后在同名设置项内，输入：Ninja（注意首字母大写）：
指定生成目标为 Ninja

5.4 设置 CMake 调试选项

最后，我们一样需要为 gdb.exe 添加启动指令，一样希望在外部独立的控制台调试程序，不过，这次不是在 launch.json 中设置，CMake Tools 扩展内置任务与启动设置（当然，如有需要，也可以和 launch.json / tasks.json 继续配合）。在我看来，使用 CMake Tools 带来的最大的好处之一是，可以实现一次性配置，而不是每个项目都需要手工改 launch.json/tasks.json。

重点当然是：确保在新建的 CM-CPP-CMake 配置下，用户级别上，做如下设置。

（一）设置过滤栏内输入 “CMake Debug Config”，找到同名设置项，点击 “在 settings.json 中编辑 ”：
设置 CMake 调试选项

将自动打开 CM-CPP-CMake 配置下用户级别的 settings.json 文件，请于其内找到 “cmake.debugConfig” 字段（它是一个JSON对象），一开始，它的一对花括号内应该是空的，请将它修改成：

"cmake.debugConfig": {    
        "externalConsole": true,
        "setupCommands": [
            {
                "description": "为 gdb 启用整齐打印",
                "text": "-enable-pretty-printing",
                "ignoreFailures": true
            },
            {
                "description": "将反汇编风格设置为 Intel",
                "text": "-gdb-set disassembly-flavor intel",
                "ignoreFailures": true
            },
            {
                "description": "让 GDB 使用 UTF-8 编码",
                "text": "-gdb-set charset UTF-8",
                "ignoreFailures": false
            }            
        ]
    }

如果前面的课堂你没有打瞌睡，此处无需解释，每一项你都应该很熟悉了，倒是建议看看该文件中，别的以 “cmake.” 开头的字段，并尝试尽量将它们和前面的设置对应起来。

Ctrl + S 保存上述设置文件，然后关闭它。如果设置页还开着，也关闭。

六、测试使用 CMake

6.1 准备源文件

在操作系统里新建个目录，取名 “HelloCMake”，然后用 VSCode 打开它，再将配置切换成 “CM-CPP-CMake”。

于其内新建 main.cpp 文件，UTF-8编码，内容为：

#include <cstdlib>
#include <iostream>
#include <string>

int main()
{
   std::system("chcp 65001 > nul");
   std::string hello = "CMake —— 母仪天下，帝国管家！";
   std::cout << hello << std::endl;
   std::system("pause");
}

6.2 快速开始：生成 CMakeList.txt

在 VSCode 内按下热键 Ctrl+Shift+P，然后输入 “CMake Quick Start”，

不知道哪位高人，把此处的 “Quick Start” 翻译成 “快速入门”，极具误导性。

这里的 “Quick Start” 就是 “快速开始”之意，它将一步步引导我们生成 CMake 项目最为重要的文件 “CMakeList.txt” (没有之一）。

（一）输入项目名称，我们取 “hello_cmake” ，通常它就是构建得到的程序名字：
cmake 项目向导第1步：取项目名称

（二）选择语言，请选 C++：
cmake 项目向导第2步：选语言

（三）选构建目标类型，我们选可执行程序：
cmake 项目向导第3步：选目标类型

（四）选择其他选项，默认可选的有打包安装组件和测试组件，现在，我们一个都不要，直接回车：
cmake 项目向导第4步：其他选项

（五）加入已有源文件，勾上 main.cpp：
cmake 项目向导第5步：添加源文件

（六）添加新预设，我们暂不添加，并且后面的步骤都暂不需要，因此，此步需直接按 Esc 键中止向导（如果你不小心手按快了，也没关系，还是按 Esc 键中止即可）：
cmake 项目向导第6步：添加新预设

一顿操作猛如虎，最终生成的 CMakeLists.txt 为：

cmake_minimum_required(VERSION 3.5.0)
project(hello_cmake VERSION 0.1.0 LANGUAGES C CXX)

add_executable(hello_cmake main.cpp)

三行，第一行指定本项目对 cmake 版本号的最低要求；第二行指定本项目名称、版本、以及所有语言为 C 和 C++ （记住，在CMake中，基本都是 CXX 表示C++，而不是CPP）；最后一行指定本项目将生成一个可执行（executable）程序，名字也叫 hello_cmake，并且只用到一个源文件，main.cpp。

就这样？不是，以上操作还生成了一个子目录，叫 “build”，和 CMakeLists.txt 同级，如图：
CMake项目树
这个目录的名字也可以在设置中修改，它的作用是用来存储构建过程中生成的最终文件，以及大量的中间文件。你可以随感时删除它，反正一构建它就会重新生成。

请特别注意两点：

build 目录下有个名为 build.ninja 的文件，表明 CMake 确实没生错“孩子”；
在 vscode 左侧边栏悄悄冒出一个按钮，下面称它为 CMake 边栏。

6.3 快速了解 CMake 项目状态

关键词：项目状态、构建Kits、构建变体、构建目标……

进入 CMake 边栏，注意到 “配置” 节点下有个 “unspec”子节点，这会令优秀的程序员夜不能寐……请点击它左端的小笔，在弹出列表中，选择 “GCC 14.2.0 x86_64-w64-mingw32(urct64)…”：
确定Kits

选择后，CMake将对该编译套件进行一番检测，通过后，该节点将变成：
配置节点

它的意思是：您现在正在构建的，是使用 “GCC 14.2.0 x86_64-w64-mingw32(urct64）”编译组件（在CMake中称为 “Kits”），且构建 “变体” 是 “Debug” （即：具备调试信息）的程序。

之所以 Kits 一开始是 “unspec”，是因为我们现在只用一套编译组件，所以在一开始时就直接跳过去相关选择，通常不会带来什么问题，CMake会做必要的自动推导。

我们也可以切换构建变体，只需尝试点击 Debug 节点右端的小笔，这回将弹出 CMake 预置的变体列表：
选择变体

因为我们下一步就是要调试程序，所以请保持使用 Debug 变体。

明确构建类型后，接着需要关心构建目标。这回请看上图中的 “生成” 节点，它的子节点是 “all”，表示将生成该项目的所有目标，我们现在也只有一个构建目标，所以，可以让目标更明确一些：

其他几个节点都可以先不管，最终我们得到如下项目状态：

项目状态

6.4 构建（生成） F7

在 CMake 侧边栏内，选择 “生成” 子节点，然后点击其右端的生成按钮：

如果你的代码没有错误，且 CMake 相关设置也无误，则应在 vscode 底部的输出终端，看到 “生成已完成，退出代码为0” 的输出。同时，在项目的 build 文件夹内，应能看到：hello_cmake.exe 。

在 CMake 环境，构建项目的热键是：F7。

6.5 调试 Shift+F5

切换到 main.cpp ，在第9行加断点：

切换到 CMake 侧边栏，选中“调试”节点，然后点击其右端的调试按钮：
开始调试
目标程序将被启动，且被调试器停止在第7行，vscode 自动打开左侧调试边栏，显示 hello 变量内容，包含汉字，无乱码。点击调试栏的“逐过程”，控制台上出现输出内容：
调试过程

在 CMake 环境下，启动项目调试的热键是： Shift + F5。

注意，F5 仍然是 C/C++ 扩展用于启动调试当前活动文件的热键，但在 CMake 环境下，这个热键引发的操作：编译当前活动文件 → 生成可执行文件 → 启动调试，都不是我们想要的。

6.6 全速运行

切换到 CMake 侧边栏，选中“启动”节点，然后点击其右端的运行按钮：

点击 CMake 侧边栏 “启动” 节点右端的小三角按钮，将在 vscode 集成的终端中直接运行程序——暂时没有简单的办法让它使用外部终端，并且，它也一样没能解决输入汉字再回显时的乱码问题。

手工写 tasks.json 和 launch.json 可以做到对调试和运行的更多控制，但对于一个 CMake 项目，改回纯手工管理会带来更多其它麻烦。再加上我们使用 CMake 管理的实际项目，多数不会有需要从控制台读入汉字输入的需求，真有这个需要，工作中可以写一个tasks.json，或者干脆在外部开一个控制台就能解决，所以，“无法在外部控制台直接启动程序” 这个问题也就无所谓了……

七、状态栏上CMake操作

C/C++ 妃被打入冷宫，CMake 娘娘成功上位后，状态栏左侧见风使舵地多出三个小按钮，分别是 CMake 项目里的 “生成”、 “调试” 和 “启动”，如图：
未调整前的状态栏中CMake操作入口

可在用户级设置中，通过 “CMake Status Bar Visibility”，过滤，找到如下设置项，并将值改变成 “visible”：
修改状态栏中CMake操作入口的可见性

这时，状态栏会一下子多出很多 CMake 操作入口，并且带有详细标题：
状态栏上详细的CMake操作入口

当前，CPack、工作流我们用得比较少，可以通过以下方法，来隐藏它们——不仅在状态栏上，也在 CMake 侧边栏上。

在设置页中，使用 “cmake.options.advanced” 过滤，然后点击该项设置的 “在 settings.json 中编辑 ”，如图：
状态栏上CMake操作入口精调

先确保 “cmake.options.statusBarVisibility” 字段值为 “visible”，它会让所有入口都默认可见（所以，其实改成 “hidden” ，反倒可以少一些设置项，大家可以自行试试）：

再对 “cmake.options.advanced” 做修改，二者最终内容如下：

    "cmake.options.statusBarVisibility": "visible",
    "cmake.options.advanced": {            
        "variant": {
            "statusBarVisibility": "compact", // 变体使用精简方式
        },
        "kit": {
            "statusBarVisibility": "compact", // 构建组件使用精简方式
        },
        "configure": { // 配置，只能在侧边栏中显示
            "projectStatusVisibility": "visible"
        },
        "build": {  // 生成
            "statusBarVisibility": "visible",
        },
        "buildTarget": { // 生成目标选择
            "statusBarVisibility": "visible",
            },
        "debug": { // 调试
            "statusBarVisibility": "inherit",
        },
        "launch": { // 启动
            "statusBarVisibility": "visible",
        },
        "cpack": { // 打包
            "statusBarVisibility": "hidden",
            "projectStatusVisibility": "hidden"
        },
        "workflow": { // 工作流
            "statusBarVisibility": "hidden",
            "projectStatusVisibility": "hidden"
        }
    },

得到的状态栏是：
设置后的状态栏

得到的CMake侧边栏（项目状态树）是：
设置后的项目状态树

显然，当漂亮的鼓励师（其实就是搞卫生的阿姨）站在你身后时，你应该尽量使用最高效也最帅气的操作：热键！！！

通常我会没事就来几下 Ctrl + K,T，按键时，配合身体前俯后仰以及几根刘海的剧烈抖动……从屏幕的反光中能清楚地看到鼓励师看向我的眼神，仿佛是吉娜看向郞朗……对面的老刘就学不来了这招，因为他已头秃。

如果鼓励师不在，或者你的脑容量记不了几个热键，那就使用状态上的入口吧。毕竟，每个人的天份是不一样的。有些人可以同时记住七个女生的姓名、生日、喜欢的礼物、爱好，随时无缝切换；而有些程序狗，比如我，只配同时记住 Borland C++ Builder、Visual Studio、Code::Blocks、CLion、QCreator、VSCode 的热键，随时无缝切换。