第 12 章：CMake 预设

12.1 概述

CMake Presets（CMake 3.19+）通过 JSON 文件定义配置、构建和测试预设，实现团队标准化的构建配置。

CMakePresets.json     ← 版本控制（团队共享）
CMakeUserPresets.json ← 个人配置（gitignore）

12.2 文件结构

{
    "version": 6,
    "cmakeMinimumRequired": {
        "major": 3,
        "minor": 21,
        "patch": 0
    },
    "configurePresets": [],
    "buildPresets": [],
    "testPresets": [],
    "packagePresets": [],
    "workflowPresets": []
}

版本对照表

Preset 版本	CMake 版本	新增特性
1	3.19	基础 configurePresets
2	3.20	buildPresets, testPresets
3	3.21	包含其他预设文件
4	3.23	packagePresets, workflowPresets
5	3.24	环境变量 INCLUDE
6	3.25	更多缓存变量类型

12.3 配置预设（Configure Presets）

12.3.1 基础预设

{
    "version": 6,
    "configurePresets": [
        {
            "name": "default",
            "displayName": "默认配置",
            "description": "默认 Debug 构建",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Debug",
                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
            }
        }
    ]
}

12.3.2 多配置预设

{
    "version": 6,
    "configurePresets": [
        {
            "name": "base",
            "hidden": true,
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build/${presetName}",
            "cacheVariables": {
                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
            }
        },
        {
            "name": "debug",
            "displayName": "Debug",
            "inherits": "base",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Debug",
                "ENABLE_SANITIZERS": "ON"
            }
        },
        {
            "name": "release",
            "displayName": "Release",
            "inherits": "base",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Release",
                "ENABLE_LTO": "ON"
            }
        },
        {
            "name": "relwithdebinfo",
            "displayName": "Release with Debug Info",
            "inherits": "base",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "RelWithDebInfo"
            }
        }
    ]
}

12.3.3 条件预设

{
    "version": 6,
    "configurePresets": [
        {
            "name": "linux-gcc",
            "displayName": "Linux GCC",
            "condition": {
                "type": "equals",
                "lhs": "${hostSystemName}",
                "rhs": "Linux"
            },
            "generator": "Ninja",
            "cacheVariables": {
                "CMAKE_C_COMPILER": "gcc",
                "CMAKE_CXX_COMPILER": "g++"
            }
        },
        {
            "name": "macos-clang",
            "displayName": "macOS Clang",
            "condition": {
                "type": "equals",
                "lhs": "${hostSystemName}",
                "rhs": "Darwin"
            },
            "generator": "Ninja",
            "cacheVariables": {
                "CMAKE_C_COMPILER": "clang",
                "CMAKE_CXX_COMPILER": "clang++"
            }
        },
        {
            "name": "windows-msvc",
            "displayName": "Windows MSVC",
            "condition": {
                "type": "equals",
                "lhs": "${hostSystemName}",
                "rhs": "Windows"
            },
            "generator": "Visual Studio 17 2022",
            "architecture": {
                "value": "x64"
            }
        }
    ]
}

12.3.4 工具链预设

{
    "version": 6,
    "configurePresets": [
        {
            "name": "arm-cross",
            "displayName": "ARM Cross Compile",
            "toolchainFile": "${sourceDir}/cmake/arm-toolchain.cmake",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build-arm",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Release"
            }
        },
        {
            "name": "vcpkg",
            "displayName": "vcpkg Toolchain",
            "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build-vcpkg"
        }
    ]
}

12.3.5 配置预设属性

属性	类型	说明
`name`	string	预设名称（必选）
`hidden`	bool	是否隐藏
`inherits`	string/array	继承的预设
`condition`	object	执行条件
`displayName`	string	显示名称
`description`	string	描述
`generator`	string	生成器
`architecture`	object	架构
`toolset`	object	工具集
`binaryDir`	string	构建目录
`cmakeExecutable`	string	CMake 可执行文件路径
`cacheVariables`	object	缓存变量
`environment`	object	环境变量
`toolchainFile`	string	工具链文件
`installDir`	string	安装目录

12.4 构建预设（Build Presets）

12.4.1 基础构建预设

{
    "version": 6,
    "buildPresets": [
        {
            "name": "default",
            "configurePreset": "debug"
        },
        {
            "name": "release",
            "configurePreset": "release"
        },
        {
            "name": "release-parallel",
            "configurePreset": "release",
            "jobs": 8,
            "verbose": false
        }
    ]
}

12.4.2 构建预设属性

属性	类型	说明
`name`	string	预设名称
`inherits`	string/array	继承的预设
`configurePreset`	string	关联的配置预设
`inheritConfigureEnvironment`	bool	继承配置环境
`jobs`	int	并行任务数
`targets`	string/array	构建目标
`configuration`	string	构建配置
`cleanFirst`	bool	先清理
`verbose`	bool	详细输出
`nativeToolOptions`	array	原生工具选项

12.4.3 目标特定预设

{
    "version": 6,
    "buildPresets": [
        {
            "name": "libs-only",
            "configurePreset": "debug",
            "targets": ["mylib", "mylib2"]
        },
        {
            "name": "docs",
            "configurePreset": "debug",
            "targets": "docs"
        },
        {
            "name": "tests-only",
            "configurePreset": "debug",
            "targets": "all"
        }
    ]
}

12.5 测试预设（Test Presets）

12.5.1 基础测试预设

{
    "version": 6,
    "testPresets": [
        {
            "name": "default",
            "configurePreset": "debug",
            "output": {
                "outputOnFailure": true,
                "verbosity": "verbose"
            }
        },
        {
            "name": "quick",
            "configurePreset": "debug",
            "filter": {
                "include": {
                    "label": "fast"
                },
                "exclude": {
                    "label": "slow"
                }
            }
        },
        {
            "name": "ci",
            "configurePreset": "release",
            "output": {
                "outputOnFailure": true,
                "outputJUnitFile": "${sourceDir}/test-results.xml"
            }
        }
    ]
}

12.5.2 测试预设属性

属性	类型	说明
`name`	string	预设名称
`configurePreset`	string	关联的配置预设
`filter`	object	测试过滤器
`output`	object	输出选项
`execution`	object	执行选项

12.6 包预设（Package Presets）

{
    "version": 6,
    "packagePresets": [
        {
            "name": "default",
            "configurePreset": "release",
            "generators": ["TGZ", "DEB"],
            "variables": {
                "CPACK_PACKAGE_CONTACT": "[email protected]"
            }
        }
    ]
}

12.7 工作流预设（Workflow Presets）

{
    "version": 6,
    "workflowPresets": [
        {
            "name": "full",
            "steps": [
                { "type": "configure", "name": "release" },
                { "type": "build", "name": "release" },
                { "type": "test", "name": "ci" }
            ]
        }
    ]
}

12.8 变量展开

12.8.1 支持的变量

变量	说明
`${sourceDir}`	源码目录
`${sourceParentDir}`	父目录
`${sourceDirName}`	源码目录名
`${presetName}`	当前预设名
`${generator}`	生成器名称
`${hostSystemName}`	主机系统名
`${env:VAR}`	环境变量
`$penv{VAR}`	路径环境变量

12.8.2 环境变量

{
    "version": 6,
    "configurePresets": [
        {
            "name": "custom-env",
            "generator": "Ninja",
            "environment": {
                "CC": "gcc-13",
                "CXX": "g++-13",
                "MY_CUSTOM_PATH": "/opt/custom",
                "PATH": "$penv{PATH}:/opt/tools/bin"
            },
            "cacheVariables": {
                "CMAKE_PREFIX_PATH": "$env{MY_CUSTOM_PATH}"
            }
        }
    ]
}

12.9 条件系统

12.9.1 条件类型

{
    "condition": {
        "type": "equals",
        "lhs": "${hostSystemName}",
        "rhs": "Linux"
    }
}

类型	说明
`const`	常量布尔值
`equals`	字符串相等
`notEquals`	字符串不等
`inList`	在列表中
`notInList`	不在列表中
`matches`	正则匹配
`notMatches`	正则不匹配
`anyOf`	任一条件为真
`allOf`	所有条件为真
`not`	取反

12.9.2 复合条件

{
    "name": "linux-debug",
    "condition": {
        "type": "allOf",
        "conditions": [
            {
                "type": "equals",
                "lhs": "${hostSystemName}",
                "rhs": "Linux"
            },
            {
                "type": "equals",
                "lhs": "$env{CI}",
                "rhs": "true"
            }
        ]
    }
}

12.10 使用命令

# 列出所有预设
cmake --list-presets
cmake --list-presets=all        # 包括隐藏的
cmake --list-build-presets
cmake --list-test-presets

# 使用配置预设
cmake --preset debug

# 使用构建预设
cmake --build --preset release

# 使用测试预设
cmake --test --preset quick

# 覆盖预设参数
cmake --preset debug -DENABLE_TESTS=ON

12.11 CMakeUserPresets.json

{
    "version": 6,
    "configurePresets": [
        {
            "name": "local-dev",
            "inherits": "debug",
            "binaryDir": "${sourceDir}/build-local",
            "cacheVariables": {
                "ENABLE_CCACHE": "ON"
            },
            "environment": {
                "CCACHE_DIR": "/home/user/.ccache"
            }
        }
    ]
}

CMakeUserPresets.json 应加入 .gitignore。

12.12 业务场景

场景：完整的 CI 预设配置

{
    "version": 6,
    "configurePresets": [
        {
            "name": "ci-base",
            "hidden": true,
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build",
            "cacheVariables": {
                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
                "BUILD_TESTING": "ON"
            }
        },
        {
            "name": "ci-linux",
            "inherits": "ci-base",
            "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Linux" },
            "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
        },
        {
            "name": "ci-windows",
            "inherits": "ci-base",
            "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Windows" },
            "generator": "Visual Studio 17 2022"
        }
    ],
    "buildPresets": [
        { "name": "ci-build", "configurePreset": "ci-linux", "jobs": 4 }
    ],
    "testPresets": [
        {
            "name": "ci-test",
            "configurePreset": "ci-linux",
            "output": { "outputOnFailure": true }
        }
    ],
    "workflowPresets": [
        {
            "name": "ci",
            "steps": [
                { "type": "configure", "name": "ci-linux" },
                { "type": "build", "name": "ci-build" },
                { "type": "test", "name": "ci-test" }
            ]
        }
    ]
}

12.13 注意事项

问题	说明
版本兼容性	确保 CMake 版本支持 preset 版本
CMakeUserPresets.json	加入 `.gitignore`
变量展开	`$env{}` 在配置时展开
generator 必须匹配	build preset 必须与 configure preset 生成器一致
hidden 预设	不能直接使用，只能被继承

12.14 扩展阅读

上一章：第 11 章 — 安装与打包 | 下一章：第 13 章 — 高级特性 →

强曰为道

第 12 章：CMake 预设

第 12 章：CMake 预设

12.1 概述

12.2 文件结构

版本对照表

12.3 配置预设（Configure Presets）

12.3.1 基础预设

12.3.2 多配置预设

12.3.3 条件预设

12.3.4 工具链预设

12.3.5 配置预设属性

12.4 构建预设（Build Presets）

12.4.1 基础构建预设

12.4.2 构建预设属性

12.4.3 目标特定预设

12.5 测试预设（Test Presets）

12.5.1 基础测试预设

12.5.2 测试预设属性

12.6 包预设（Package Presets）

12.7 工作流预设（Workflow Presets）

12.8 变量展开

12.8.1 支持的变量

12.8.2 环境变量

12.9 条件系统

12.9.1 条件类型

12.9.2 复合条件

12.10 使用命令

12.11 CMakeUserPresets.json

12.12 业务场景

场景：完整的 CI 预设配置

12.13 注意事项

12.14 扩展阅读