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

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

---

版权声明：

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

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

这节课，我们的任务是：

1. 通过 msys2 安装 CMake
2. 在 vscode 创建 CMake 专项配置
3. CMake 扩展基本设置
4. CMake 项目演示
5. 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

如图：

简介：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

如图：

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

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

二、创建 CMake 专用配置

2.1 创建 CM-CPP-CMake 配置

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

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

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

全部过程如下图：

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

小心宫斗戏！

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

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

2.2 选择专用颜色主题

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

顺便，检查一下图中箭头指示的位置，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 ......" 的选中状态，如图：

（三）过滤栏输入 "Debug Show in Status Bar"，然后在和过滤内容同名的设置内，从下拉框中选择 "never" （操作时适合的内心戏：无情帝王冲废后咆啸："NEVER!" ）

很可惜，以上操作只是在界面上将 C/C++ 扩展的相关操作入口隐藏，更容易搞混热键入口并没有关闭。

四、安装 CMake 扩展

可以开始迎娶新娘娘了......

确保处于 CM-CPP-CMake 配置下......然后在扩展市场找到 出于微软的 "CMake Tools"（这个扩展包包含 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"，注意，因为是在图形界面填写，所以此处路径分隔符无需转义：

（我就曾不小心把 ucrt64 写成 urct64......）

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

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

5.3 让 CMake 使用 Ninja

CMake 是母后，它能生成多种制作文件和多家IDE（比如 Visual Studio 、Code::Blocks）的项目文件，现在我们要让它固定生成 Ninja 所需的制作文件。输入 "CMake Generator"过滤，然后在同名设置项内，输入：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 中编辑 "：

将自动打开 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" ，通常它就是构建得到的程序名字：

（二）选择语言，请选 C++：

（三）选构建目标类型，我们选可执行程序：

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

（五）加入已有源文件，勾上 main.cpp：

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

一顿操作猛如虎，最终生成的 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 同级，如图：

这个目录的名字也可以在设置中修改，它的作用是用来存储构建过程中生成的最终文件，以及大量的中间文件。你可以随感时删除它，反正一构建它就会重新生成。

请特别注意两点：

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

6.3 快速了解 CMake 项目状态

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

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

选择后，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 Status Bar Visibility"，过滤，找到如下设置项，并将值改变成 "visible"：

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

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

在设置页中，使用 "cmake.options.advanced" 过滤，然后点击该项设置的 "在 settings.json 中编辑 "，如图：

先确保 "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 的热键，随时无缝切换。