# cmake-template

**Repository Path**: RealCoolEngineer/cmake-template

## Basic Information

- **Project Name**: cmake-template
- **Description**: 一个CMake Project的模板仓库。
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 81
- **Forks**: 24
- **Created**: 2021-04-25
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cmake-template

## 介绍
一个CMake Project的模板仓库。

## 构建说明

构建行为统一声明在 `CMakePresets.json`（schema v6）中，直接使用 CMake 命令构建。

可用的 configure preset（Windows 主机自动切换为 `-win` 后缀变体，使用 Ninja generator）：

| Preset | 说明 |
| --- | --- |
| `host-debug` | Debug 构建，启用单元测试 |
| `host-release` | Release 构建，用于安装与打包 |
| `mcu-m4` | 交叉编译 Release 构建（Cortex-M4，需 `arm-none-eabi-gcc`），用于打包 |

```bash
# 查看当前平台可用的 preset（默认只列 configure presets）
cmake --list-presets

# 按类型列举：configure / build / test / package / workflow / all
cmake --list-presets=workflow
cmake --list-presets=all

# 各子工具的等价入口
cmake --build --list-presets      # build presets
ctest --list-presets              # test presets
cpack --list-presets              # package presets
cmake --workflow --list-presets   # workflow presets
```

> 注意：condition 平台过滤只作用于 configure presets 列表；build/test/package/workflow
> 列表会显示全部条目，但引用了被禁用 configure preset 的项在执行时会报错。


### 一条命令跑完整链（推荐）

```bash
# Debug：configure + build + test
cmake --workflow --preset host-debug

# Release：configure + build + package（ZIP 生成到 output/）
cmake --workflow --preset host-release

# 交叉编译：configure + build + package（ZIP 生成到 output/）
cmake --workflow --preset mcu-m4

# 加 --fresh 让 configure 步骤重置 cache（CMake ≥ 3.31，语义见"常用命令行选项"）
cmake --workflow --preset host-debug --fresh
```

### 分步执行

```bash
# 配置（--fresh 保证 cache 始终从 preset+参数推导）
cmake --preset host-debug --fresh

# 构建
cmake --build --preset host-debug -j 8

# 测试（自动 output-on-failure）
ctest --preset host-debug

# 安装（落盘到 output/host-release/）
cmake --preset host-release --fresh
cmake --build --preset host-release
cmake --install build/host-release

# 打包（ZIP 生成到 output/）
cpack --preset host-release
```

### 常用命令行选项

**configure 阶段（`cmake --preset <p>`）**

| 选项 | 作用 |
| --- | --- |
| `-D<VAR>=<VALUE>` | 一次性覆盖 cache 变量，优先级高于 preset 的 `cacheVariables` |
| `--fresh` | 重置 cache（需要注意细节，详细说明见下文） |
| `--log-level=DEBUG` | 提高日志级别，排查 configure 逻辑（默认 STATUS） |
| `-Wno-dev` | 屏蔽第三方库触发的开发者警告 |

`--fresh` 只在 configure 阶段生效：删除构建目录中的 `CMakeCache.txt` 和
`CMakeFiles/`，让本次配置完全从"preset 默认值 + 命令行 `-D`"重新推导。
不加 `--fresh` 时，旧 cache 中的变量会残留——例如上次用 `-DUSE_IMPORTED_LIB=ON`
配置过，之后即使不传该参数它仍是 ON；改了 `CMakePresets.json` 的
`cacheVariables` 后旧构建目录也可能带着旧值。

`--fresh` **不影响增量编译**：目标文件（`.o`）由构建系统按源文件时间戳管理，
不属于 CMake cache。三种清理语义的对照：

| 动作 | 命令 | 效果 |
| --- | --- | --- |
| 增量编译（日常默认） | `cmake --build --preset host-debug` | 只重编改动过的源文件，未改动则秒级 no-op |
| 重置配置 | `cmake --preset host-debug --fresh` | 仅重置 cache，`.o` 保留，随后构建仍是增量 |
| 全量重建 | `rm -rf build/host-debug` 后重新 configure | 从零编译所有文件 |

日常开发改完代码直接 `cmake --build --preset host-debug` 即可触发增量编译，
无需重新 configure（CMakeLists 有改动时构建系统会自动重新配置）。

`-D` 覆盖本项目变体开关的示例：

```bash
# 使用 lib/ 下的预编译 math 库（注意：预置库为 x86_64 架构）
cmake --preset host-debug --fresh -DUSE_IMPORTED_LIB=ON

# Release 构建也启用单元测试
cmake --preset host-release --fresh -DCMAKE_TEMPLATE_ENABLE_TEST=ON
```

**build 阶段（`cmake --build --preset <p>`）**

| 选项 | 作用 |
| --- | --- |
| `-j <N>` / `--parallel <N>` | 并行编译任务数，不带 N 则用尽所有核心 |
| `--target <tgt>` | 只构建指定 target（如 `demo`、`test_add`），跳过无关部分 |
| `-v` / `--verbose` | 打印完整编译命令行，排查 flags/include 路径问题 |
| `--clean-first` | 先执行 clean 再构建（保留 cache，比删目录轻量） |

**test 阶段（`ctest --preset <p>`）**

| 选项 | 作用 |
| --- | --- |
| `-R <regex>` | 只跑名称匹配的用例，如 `-R add` 只跑 test_add |
| `--rerun-failed` | 只重跑上次失败的用例 |
| `-j <N>` | 并行执行测试 |
| `-V` | 显示每个用例的完整输出（默认只在失败时输出，已由 preset 声明） |

组合示例：

```bash
# 只重编并验证 add 相关改动
cmake --build --preset host-debug --target test_add -j 8
ctest --preset host-debug -R add

# 编译报错时查看完整命令行
cmake --build --preset host-debug -v
```