%%
# 纲要
> 主干纲要、Hint/线索/路标
- CMake 插件本身，需要配置些什么？
- CMake 项目配置，需要配置些什么？ => `CMakeLists.txt`
- 如何在 VSCode 下从零开始构建一个项目？
# Q&A
#### 已明确
#### 待明确
> 当下仍存有的疑惑
**❓<font color="#c0504d"> 有什么问题？</font>**
# Buffer
## 闪念
> sudden idea
## 候选资料
> Read it later
%%
# CMake 插件
CMake 插件具体有两项，包含在了 C/C++官方插件包中。
- **`CMake` 插件** <br>提供 CMake 语言支持，如**代码提示、代码高亮**等，便于编辑在 VSCode 中编辑 `CMakeLists.txt` 文件
- **`CMake Tools` 插件**<br>在 VSCode 中提供 CMake 支持（需要系统上已安装有 CMake），**自动构建 CMake 项目**，**完成编译调试**等。
> [!NOTE] 注：CMake 是个独立的构建工具，需要先在电脑上安装 CMake。
>
> 
>
>
整体配置及使用说明参见 VSCode 官方文档 [^1] 。
<br><br>
# CMake 插件选项设置
> 关于 VSCode CMake Tools 插件本身的配置项
关闭下面三个 **自动进行 CMake Configure** 的选项。
![[_attachment/05-工具/VSCode/VSCode 配置使用 CMake 插件.assets/IMG-VSCode 配置使用 CMake 插件-D571B4FAE00C97C614768DF84BCC668F.png|600]]
避免在 VSCode 本身有开启文件自动保存时，**编辑 CMakeLists.txt 文件过程中频繁触发自动配置**。
<br><br>
# CMake 构建工具链配置
安装 CMake 插件之后，需要为插件**配置==构建工具链==**——指定**编译套件、调试器等构建相关工具**，例如 gcc/clang/mscv、gdb 等。
在 VSCode 中有两种方式进行配置：
- 方式一：**通过 ==CMake 工具自身提供==的 CMake Presets 方式** （❇️ ==**推荐**==）
- 方式二：**通过 VSCode CMake Tools 插件提供的 CMake Kits 方式**
![[_attachment/05-工具/VSCode/VSCode配置C++开发环境.assets/IMG-VSCode配置C++开发环境-B3F8015D7D152F28CDD3ED0D62B74A6B.png|611]]
### 方式一：通过 CMake Presets
> [!NOTE] 关于 CMake Presets
>
> CMake Presets 是 CMake 3.19 版本起引入的功能，通过**项目内的一个 JSON 文件**（通常命名为 `CMakePresets.json`） 来定义**该项目的构建配置和编译选项**，指定**编译工具、构建模式**等，CMake 将**使用该文件指定的编译工具集进行构建**。
>
通过项目根目录（VSCode 工作区目录）下的 **`CMakePresets.json` 文件**指定 CMake 使用的**构建工具集**。
> [!example] `CMakePresets.json` 文件内容示例：
>
> ![[_attachment/05-工具/VSCode/VSCode配置C++开发环境.assets/IMG-VSCode配置C++开发环境-AD43D7327D4F66F876A4423C6DE195C8.png|651]]
>
>
#### 在 VSCode 中为项目自动生成 `CMakePresets.json` 文件：
对于一个全新的项目，通过以下步骤完成：
- （1）执行 `CMake: Quick Start` 命令，将**自动生成 CMake 项目构建配置**（见后文）<br> ![[_attachment/05-工具/VSCode/VSCode配置C++开发环境.assets/IMG-VSCode配置C++开发环境-88D3E708094EECFD32A605E346AADCEB.png|211]]
- （2）再次执行 `CMake: Quick Start` 命令，**==添加 `CMakePresets.json` 文件==**：
- 弹框如下：<br> ![[_attachment/05-工具/VSCode/VSCode配置C++开发环境.assets/IMG-VSCode配置C++开发环境-EEACF90E27979E0081D55BEC9B1923FF.png|486]]
- 选中 "**Create from Compilers**" 选项<br> ![[_attachment/05-工具/VSCode/VSCode配置C++开发环境.assets/IMG-VSCode配置C++开发环境-1CF4393F7D418FEE0F8C9B325828D90B.png|483]]
- 选择其中一项编译工具 <br> ![[_attachment/05-工具/VSCode/VSCode配置C++开发环境.assets/IMG-VSCode配置C++开发环境-4DA54160F52108440298A95B753AA5F3.png|480]]
> [!NOTE] 可在 VSCode CMake Tools 插件配置中关闭使用 `CMakePresets.json` 文件
>
> 
>
<br>
### 方式二：通过 CMake Kits
CMake Kits 方式由 **VSCode ==CMake Tools 插件==** 提供，对应两项配置文件：
| | 路径 | 备注 |
| -------------------- | -------------------------------------------------------------------- | ------------------------------------ |
| **系统级** tool-kits 文件 | `%LOCALAPPDATA%/CMakeTools/cmake-tools-kits.json` <br>（Windows 下路径） | **通过 `CMake: Scan for kits` 命令自动生成** |
| **项目级** tool-kits 文件 | `${workspaceFolder}/.vscode/cmake-kits.json` | **需要手动创建** |
相关命令：
- `CMake: Scan for Kits`： **扫描本机上可用的==构建工具链==并自动生成系统级 `cmake-tools-kits.json` 文件**
- `CMake: Edit User-Local CMake Kits`： **查看系统级 `cmake-tools-kits.json` 配置文件** <br> 
#### 查看 `cmake-tools-kits.json` 文件
该文件中声明了**各项 tool kits 的配置**——**所使用的编译器 `compilers`**、**对应的生成器 `preferredGenerator`**、**相关环境变量** `environmentVariables`。
该文件中配置的工具链将被 CMake 使用，指定生成器及所用编译器：
CMake 在配置项目时，将根据所选择的 tool kit，使用相对应的配置命令：
#### 生成/更新 `cmake-tools-kits.json` 文件
执行 `CMake: Scan for Kits` 命令，将根据 `PATH` 环境变量 **扫描搜索 `g++/gcc`、`clang`、`msvc` 编译工具链**，
**获取其版本信息并自动生成/更新 `cmake-tools-kits.json` 配置文件**。
执行过程如下所示：
> [!NOTE] `CMake: Scan for Kits` 命令说明[^2]
> 
<br><br><br>
# CMake 插件相关命令
<br>
# CMake 插件使用
### （1）为 VSCode 项目生成 CMake 配置
在命令面板**使用 `CMake: Quick Start` 命令**，该命令将执行以下操作：
- **自动创建 `CMakeLists.txt` 文件**
- **自动创建 `CMakePresets.json` 文件**
- **在项目根目录下自动生成一个 `build` 目录**（build 目录路径可在配置中指定）<br> 
> [!example]
>
> ![[_attachment/05-工具/VSCode/VSCode 配置使用 CMake 插件.assets/IMG-VSCode 配置使用 CMake 插件-FCFF008FBAEA31801D8A7C63CDD7079A.png|377]]
>
> ![[_attachment/05-工具/VSCode/VSCode 配置使用 CMake 插件.assets/IMG-VSCode 配置使用 CMake 插件-0CAA6A65FB2D285CAC1065A5F2C5F346.png|605]]
>
>
### （2）配置项目（configure）
使用 CMake 配置项目，**==生成构建系统==**。等价于执行 `cmake <source_dir> ` 命令。
构建前，需要先确定所用的 **编译器套件** 以及 **构建类型**：
- Select a kit：
- Select a Variant：Cmake Tools 提供了下述四种 build 方式。
选择完成后，使用 `CMake: Configure` 命令进行配置，或者在左侧 CMake 面板中直接点击 `Configure` 图标进行配置，**生成构建系统**。
输出如下：
可见，VSCode 中的 CMake 插件在运行配置时指明了以下变量：
- `CMAKE_C_COMPILER` 与 `CMAKE_CXX_COMPILER`：C/C++ 编译器路径
- `CMAKE_BUILD_TYPE`：构建类型
- `CMAKE_EXPORT_COMPILE_COMMANDS`：**构建目录下输出 `compile_commands.json` 文件**。
### （3）构建项目（build）
使用 CMake 构建项目（编译项目，生成可执行文件或库文件），等价于执行 `cmake --build ` 命令。
CMake **默认会构建所有目标**，可在左侧 CMake 窗口的 `Build` 栏中指定**构建目标**。
有多种方式可以进行构建：
- **方式一：在命令面板输入构建命令**
- `CMake:Build`： **构建所有目标**
- `CMake:Build Target`：**构建指定目标**，将弹窗以选中构建目标
- **方式二**：点击底部状态栏的 `Build` 齿轮按钮，将**构建当前指定的目标**。
- **方式三**：点击左侧 `Build` 窗口栏，将**构建当前指定的目标**。
> [!example]
> 输出的构建信息：
> 
>
> 可见，VSCode 中的 CMake 插件在构建时使用了一下选项：
> `--config`，`--target`，`-j` ，`--`。
>
<br>
### 构建、运行、调试、测试目标
在左侧 CMake 窗口中：
1. 可 **指定构建、测试、调试、运行的当前目标**。
2. 点击右侧按钮，**可执行相应操作**。
此外，在 VSCode 底部状态栏也提供了**快捷按钮**：
构建指定的目标：
调试指定的目标：
运行指定的目标：
<br><br><br>
# 参考资料
# Footnotes
[^1]: [Get started with CMake Tools on Linux](https://code.visualstudio.com/docs/cpp/CMake-linux)
[^2]: [vscode cmake tool-kits](https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/kits.md)