CMake Presets教程

在使用 CMake 作为构建工具的时候, 对于一个稍微大一点的项目, 存在有很多的选项. 比如 Debug 版本还是 Release 版本, 是否开启特定选项, 是否开启测试等等. 这些通常是作为命令行参数传递进去的. 但是很多程序员并不在命令行中作开发, 更多的是使用 IDE 来进行开发. 不同的 IDE 的设置参数的方式不同, 这对于多方协同的开发来说, 有些不方便.

CMake Presets 就提供了一种解决这个问题的方式. 它允许你定义一个配置文件(CMakePresets.json), 将对 CMake 的传递参数写入到该文件, 然后在 IDE 中加载这个配置文件, 然后就可以使用 IDE 的界面来设置参数了. 这样不论是在命令行,还是 IDE 中都能很方便的使用相同参数. 目前支持的 IDE 有: CLion/Visual Studio/VS Code.

如何使用

创建一个 CMakePresets.json 文件. 用户也可以创建一个本地的CMakeUserPresets.json文件, 来做本地化适配. 但这个文件不应该被添加到 git 仓库中.
写入配置, 配置方法见后.
重新打开项目, 重新加载项目.

CMakePresets.json 文件结构

包含如下字段:

version: 必填字段. 配置文件格式(schema)版本号, 目前是一个整数. 不同版本的 CMake 支持的版本不一样. 详细列表请查看官网文档.
cmakeMinimumRequired: 可选字段. 表示对 CMake 版本的最低要求.
configurePresets: 可选字段. 用于配置 CMake 的参数. 这个是经常使用的字段.
buildPresets: 可选字段. 用于构建的参数. 最低要求版本 2.
testPresets: 可选字段. 用于测试的参数. 最低要求版本 2.
packagePresets: 可选字段, 用于打包的参数. 最低要求版本 6.
workflowPresets: 可选字段. 用于工作流的参数. 最低要求版本 6.

这些字段的详细配置介绍起来枯燥乏味, 这里针对使用场景来介绍如何使用.

配置样例

设置 CMake 命令行参数

{"configurePresets": [{"name": "linux-base","description": "Default CMake configure preset","generator": "Ninja","binaryDir": "/tmp/build","cacheVariables": {"CMAKE_BUILD_TYPE": "Debug","CMAKE_EXPORT_COMPILE_COMMANDS": "YES","CMAKE_TOOLCHAIN_FILE": "/home/vscode/vcpkg/scripts/buildsystems/vcpkg.cmake"},"condition": {"type": "equals","lhs": "${hostSystemName}","rhs": "Linux"}}]
}

上述的配置等价于:

cmake -S . \-B /tmp/build-G Ninja \-DCMAKE_BUILD_TYPE=Debug \-DCMAKE_EXPORT_COMPILE_COMMANDS=YES \-DCMAKE_TOOLCHAIN_FILE=/home/vscode/ vcpkg/scripts/buildsystems/vcpkg.cmake

并且该选项只在 Linux 系统下生效. 这是通过condition字段实现的. 同样的, 你可以写出只在 Windows 可用的配置.

配置工作流

下面的配置创建了一个从配置到运行测试的工作流. 在前面的 configurePresets 我们需要依次配置:

buildPresets
testPresets
workflowPresets

{"configurePresets": [{"name": "linux-base","description": "Default CMake configure preset","generator": "Ninja","binaryDir": "/tmp/build","cacheVariables": {"CMAKE_BUILD_TYPE": "Debug","CMAKE_EXPORT_COMPILE_COMMANDS": "YES","CMAKE_TOOLCHAIN_FILE": "/home/vscode/vcpkg/scripts/buildsystems/vcpkg.cmake"},"condition": {"type": "equals","lhs": "${hostSystemName}","rhs": "Linux"}}],"buildPresets": [{"name": "linux-base-build","configurePreset": "linux-base"}],"testPresets": [{"name": "linux-base-test","configurePreset": "linux-base","output": {"outputOnFailure": true},"execution": {"noTestsAction": "error","stopOnFailure": true}}],"workflowPresets": [{"name": "default","steps": [{"type": "configure","name": "linux-base"},{"type": "build","name": "linux-base-build"},{"type": "test","name": "linux-base-test"}]}]
}

在 VS Code 中, 可以点击run workflow即可运行上述的工作流.

在命令行触发:

cmake --workflow --preset default

示例项目仓库: https://github.com/yangxinghai/cmake-presets-tutorial

IDE 中使用

CLion 目前支持使用 CMakePresets.json 做配置和构建.
- 1. 打开 Settings -> Advanced Settings -> Automatically import CMake Presets
- 1. 启用配置: Settings | Build, Execution, Deployment | CMake
VS Code 目前的支持比较完整, 可以直接运行工作流. VS Code 中需要使用C/C++ Extension Pack来做到支持.