@chengzhao-dev/dsh-cpp-workflow 0.3.0 → 0.5.0

package/skills/building-cpp/steps/01-build.md

@@ -2,10 +2,9 @@
 
 ## 产出
 
-一组 target-based 的 CMake 规则、一个固定的构建目录、一个可用的编译数据库。构建结果只取决于 `environment.json` 声明的组合，不取决于当前 shell 碰巧有什么。
+一个固定的构建目录、一个可用的编译数据库、一组可复现的配置与构建命令。构建结果只取决于 `environment.json` 声明的组合，不取决于当前 shell 碰巧有什么。
 
 ```text
-CMakeLists.txt
 build/
   clang/                 # compiler=clang
     compile_commands.json
@@ -14,37 +13,32 @@ build/
   compile_commands.json  # 指向上面的当前数据库
 ```
 
-## 通用情况
+## 前置
 
-先读 `environment.json`。源文件清单来自 `developing-cpp` 的定边界和定实现；定构建只把它们写进 target，不重新决定库与程序的边界。三个环境轴加语言标准分别表示：
+先读项目技能与 `environment.json`，再确认 `configuring-cmake` 已经把 target 图、公共 include、语言标准和输出目录写进 CMake。target 缺失、标准不对、include 或链接边界没写时，停止本步，转 `configuring-cmake` 的定 target 与标准；不要在这里用全局变量或临时 `-std` 绕过。
+
+## 环境
 
 | 轴 | 取值 | 含义 |
 | --- | --- | --- |
 | `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在系统 |
-| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`native` 表示 `host` 本机，`wsl` 表示 Windows 的 WSL，且只允许 `host=windows`；`windows` + `native` 本版本不支持 |
+| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`wsl` 只允许 `host=windows`；`windows` + `native` 本版本不支持 |
 | `compiler` | `clang` / `gcc` | 用哪个编译器；一次只配一个 |
 | `standard` | `c++11`–`c++23` | 一个工程一个语言标准；新工程默认 `c++23`，已有工程按原声明 |
 
-环境轴为空、`standard` 非法或组合非法（如 `host=linux` + `build_host=wsl`、`host=windows` + `build_host=native`）时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。`windows` + `native` 只给一句「本版本不能在 Windows 原生壳里构建」，不要建议改 WSL、不要提出补 PowerShell 脚本。
+环境轴为空、`standard` 非法或组合非法时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。`windows` + `native` 只给一句「本版本不能在 Windows 原生壳里构建」。
 
-构建规则：
+## 规则
 
-- CMake 最低 3.20；`project(... LANGUAGES CXX)`；只有确有 C 源时才写 `LANGUAGES C CXX`。新工程默认标准 C++23；已有工程按 `environment.json` 的 `standard` 或现有 target 声明，不擅自升降。
-- 生成器固定单配置 Ninja，不用 Ninja Multi-Config：同一源文件会写多条命令，clangd 默认只取第一条，容易读错数据库（clangd#2026）；构建目录固定 `build/clang` 或 `build/gcc`。
-- 一个 configure 只用一个编译器：`-DCMAKE_CXX_COMPILER=clang++` 或 `g++`。
-- 程序 target 固定叫 `app`；库 target 用组件名，程序链接库。库与程序分开，不把 `main()` 编进库。
-- 用 `target_include_directories`、`target_compile_features`、`target_link_libraries` 表达依赖；禁止全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 污染所有 target。
-- 库的公共 include 根用 `PUBLIC`；实现私有头用 `PRIVATE`；测试 target 只链接被测库的公共接口。头文件按 Google 规则从仓库根写完整路径，构建时把仓库根加入搜索路径，不要改成组件的 `include/` 根后再写裸文件名。
-- `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)`；Ninja 生成器下会产出 `compile_commands.json`。
-- 输出目录统一：可执行文件到 `build/<compiler>/bin`，库到 `build/<compiler>/lib`；不要用源码目录当输出目录。
-- 开启 `CMAKE_EXPORT_COMPILE_COMMANDS` 后，把 `build/<compiler>/compile_commands.json` 符号链接到 `build/compile_commands.json`，让 clangd 默认能找到当前数据库。本插件固定产出 `build/<compiler>/` 并在 `build/` 下维护链接，不生成 `out/build/`，也不把两套构建根混用。
-- 目标标准写在 target 上：`target_compile_features(app PRIVATE cxx_std_23)`；库用 `PUBLIC` 传播标准。再加 `set_target_properties(... CXX_STANDARD 23 CXX_STANDARD_REQUIRED ON CXX_EXTENSIONS OFF)`：meta-feature 只保证“至少”，`CXX_STANDARD_REQUIRED` 防 decay，`CXX_EXTENSIONS OFF` 把 `-std=gnu++23` 收成 `-std=c++23`。configure 后读 `compile_commands.json` 的最后一个 `-std=`，必须与 `environment.json` 的 `standard` 一致。
-- 工程确有 C 源时才写 `LANGUAGES C CXX`，并且 `CMAKE_C_COMPILER` 与 `CMAKE_CXX_COMPILER` 必须来自同一套编译器（`clang`/`clang++` 或 `gcc`/`g++`）；没有 C 源时只启用 CXX。
-- 不写 `file(GLOB ...)`；源文件显式列出，新增文件时改 CMake。
-- 不加 `-march=native`、`-ffast-math` 等改变语义或可移植性的选项；警告选项按团队约定统一加。
-- 配置阶段不隐式下载依赖；需要 GoogleTest 时由项目显式选择固定版本、带哈希的 `FetchContent`，或使用项目自带的 cmake 模块，只把下载用于测试依赖。
+- 生成器固定单配置 Ninja，不用 Ninja Multi-Config：同一源文件会写多条命令，clangd 默认只取第一条，容易读错数据库；构建目录固定 `build/clang` 或 `build/gcc`。
+- 一个 configure 只用一个编译器：`-DCMAKE_CXX_COMPILER=clang++` 或 `g++`；确有 C 源时 C 编译器与 C++ 编译器同属一套。
+- `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)` 由 `configuring-cmake` 写在顶层；Ninja 下产出 `compile_commands.json`。
+- 输出目录由 `configuring-cmake` 统一设到 `build/<compiler>/bin` 与 `build/<compiler>/lib`；本步只核对，不重复设。
+- 配置后把 `build/<compiler>/compile_commands.json` 符号链接到 `build/compile_commands.json`，让 clangd 默认能找到当前数据库；换编译器时重建链接。
+- 不写全局 `CMAKE_CXX_FLAGS`、`include_directories()` 或 `add_definitions()`；这些属于 target 契约，发现就转 `configuring-cmake`。
+- 配置阶段不隐式下载依赖；测试框架由项目显式选择固定版本、带哈希的 `FetchContent`，或使用项目自带模块。
 
-命令形状：
+## 命令
 
 ```bash
 cmake -S . -B build/clang -G Ninja \
@@ -56,23 +50,16 @@ rm -f build/compile_commands.json
 ln -s clang/compile_commands.json build/compile_commands.json
 ```
 
-GCC 模式把目录和编译器换成 `build/gcc`、`g++`。工程确有 C 源时，再补 `-DCMAKE_C_COMPILER=clang` 或 `gcc`，和 C++ 编译器同属一套。每次构建都重新 configure；不要依赖上一次的缓存。
+GCC 模式把目录和编译器换成 `build/gcc`、`g++`。每次构建都重新 configure；不要依赖上一次缓存。
 
 ## 情况
 
-**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名，默认标准 C++23；四套模板已按 `__cplusplus` 条件使用 `std::format`，把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降到 C++11–C++20 后仍应能构建，降完跑 `references/standards/README.md` 的五档矩阵。模板源码是 `.cc`，头文件用路径式 `#define` 守卫；新增文件沿用 `.cc` / `.h`，已有工程保持原有扩展名。
-
-**已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让通过检查的项目入口跑通，保留可回退点。
-
-**库 + 程序**：库 target 的 `PUBLIC` include 根按项目约定设置；本工作流把仓库根作为源码根，程序按 `#include "component/include/name.h"` 包含公共头，不直接包含库的 `src/`。静态库与动态库的接口相同；动态库额外设置运行时库路径。
+**新工程**：从 `../assets/templates/projects/` 选形态；模板缺 target 时先转 `configuring-cmake`，target 齐了再 configure。
 
-**测试**：`enable_testing()` 放在顶层，`add_subdirectory(tests)` 在 `add_subdirectory(<component>)` 之后；测试 target 用 `add_test(NAME ... COMMAND ...)` 注册。没有测试时不要为了「看起来完整」加空测试。
+**已有工程**：先读现有 `CMakeLists.txt`，只核对 target、标准与输出目录；不改与当前任务无关的 target，大改前先让现有构建跑通。
 
-**CMakePresets**：如果项目使用 preset，名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令，不要两套并存。
+**测试**：`enable_testing()` 与 `add_subdirectory(tests)` 的顺序由 `configuring-cmake` 定；本步只跑 CTest，不在没有测试时加空测试。
 
-## 正反例指针
+**CMakePresets**：如果项目使用 preset，名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令。
 
-- 全局 include、GLOB、把 `main()` 编进库：`examples/cmake.md`。
-- 正确的最小库 + 程序：`examples/cmake.md`「最小可用形状」。
-- target 与目录的完整说明：`references/cmake.md`。
-- 五档标准的下限、降档替换和工具映射：`references/standards/README.md`。
+下一步：构建可用后，进 `steps/02-tooling.md` 配格式、静态检查与 clangd。

package/skills/building-cpp/steps/02-tooling.md

@@ -13,8 +13,8 @@
 - `.clangd` 的 `CompilationDatabase` 指向 `build/<compiler>`；切换编译器时同步改，不能留旧目录。**不要写 `-std`**：它会覆盖 `compile_commands.json`，把 C++23 工程降成旧标准；标准只由构建声明和编译数据库决定。
 - `--query-driver` 是 clangd 的命令行参数，写在 `.vscode/settings.json` 的 `clangd.arguments` 里，不是 `.clangd` 的 YAML 键。它告诉 clangd 允许执行哪个编译器驱动来取系统头路径；路径写绝对路径，并与 `environment.json` 的编译器一致。
 - 首次复制时按轴替换三处：`compiler=clang` 用 `CompilationDatabase: build/clang`、`--query-driver=/usr/bin/clang++` 和 `cmake.debugConfig` 的 `MIMode: lldb` / `miDebuggerPath: /usr/bin/lldb`；`compiler=gcc` 用 `build/gcc`、`/usr/bin/g++` 和 `MIMode: gdb` / `/usr/bin/gdb`。只复制模板而不改这三处，GCC 模式会指向错误的数据库、驱动或调试器。原工程已有的 `.clangd` 不覆盖；要改先征得同意。
-- `.clang-format` 只保留 `Language: Cpp`、`BasedOnStyle: Google`、`Standard: Latest`（clang-format 21/22 不接受 `c++23`）。列宽 80、每级 2 空格、不用 tab、包含顺序都取 Google 预设；不要覆盖 `ColumnLimit`、`TabWidth`、`IncludeCategories` 或指针对齐。需要新规则时先改 `references/google-cpp-style.md` 并说明理由。
-- `.clang-tidy` 用 `Checks: '-*, google-*, readability-identifier-naming'`，保留 `WarningsAsErrors: '*'` 和 `FormatStyle: file`。`google-*` 覆盖 Google 风格能静态检查的部分；`readability-identifier-naming` 只配项目确实统一的命名项：类型/枚举/别名/模板参数 PascalCase，变量/参数/成员 snake_case，类成员尾随 `_`，结构体成员不尾随，常量 `k` + PascalCase。不要设 `FunctionCase`，Google 允许 `count()` / `set_count()` 这类访问器；不要重新打开 `cppcoreguidelines-*` 整包或 `portability-avoid-pragma-once`。
+- `.clang-format` 保留 `Language: Cpp`、`BasedOnStyle: Google` 和 `Standard`：模板资产写 `Latest`；工程按 `environment.json` 声明 C++11–C++20 时，把 `Standard` 改成 `c++NN`（映射见 `references/standards/README.md`）。clang-format 21/22 的 `Standard` 不接受 `c++23`，所以 C++23 工程仍写 `Latest`。列宽 80、每级 2 空格、不用 tab、包含顺序都取 Google 预设；不要覆盖 `ColumnLimit`、`TabWidth`、`IncludeCategories` 或指针对齐。需要新规则时先改 `references/google-cpp-style.md` 并说明理由。
+- `.clang-tidy` 用 `Checks: '-*, google-*, portability-avoid-pragma-once, readability-identifier-naming'`，保留 `WarningsAsErrors: '*'` 和 `FormatStyle: file`。`google-*` 覆盖 Google 风格能静态检查的部分；`readability-identifier-naming` 只配项目确实统一的命名项：类型/枚举/别名/模板参数 PascalCase，变量/参数/成员 snake_case，类成员尾随 `_`，结构体成员不尾随，常量 `k` + PascalCase。不要设 `FunctionCase`，Google 允许 `count()` / `set_count()` 这类访问器；`portability-avoid-pragma-once` 要打开，因为工程统一用路径式守卫；不要重新打开 `cppcoreguidelines-*` 整包。
 - `.clang-tidy` 关闭项和例外必须写理由；不要借 `-*` 之后再打开 `cppcoreguidelines-*` 这类非 Google 整族检查。
 - `.vscode/extensions.json` 推荐 clangd、CMake Tools 与 C/C++ 扩展；`.vscode/settings.json` 固定 clangd 参数、CMake 构建目录和 `cmake.debugConfig`。配置、构建、运行和调试只从 CMake Tools 进入，不写 `tasks.json` 或 `launch.json`；C/C++ 扩展只作为 CMake 快速调试的后端，IntelliSense 关闭，避免和 clangd 并行。配置注释用 JSONC 的 `//`，贴在被解释的键上方。
 - 配置注释写「为什么这样设」，不写「这一项是什么」；不写策略头、不指向文档路径。

package/skills/configuring-cmake/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: configuring-cmake
+description: 在 C++11–C++23 工程里编写或重构 CMake 时使用：CMakeLists.txt、cmake 模块、target 与属性、依赖与输出目录、语言标准与编译选项、2 空格排版；新工程默认 C++23。改 .h/.cpp 源码先开 developing-cpp；只配置、构建或跑工具链时开 building-cpp。不用于 Quarto、Python 或非 C++ 文档。
+metadata:
+  short-description: CMake 配置三步
+---
+
+# configuring-cmake
+
+## 适用场景
+
+管 `CMakeLists.txt`、`cmake/` 下的模块、`target_*` 命令、目标属性、include 与链接边界、输出目录、共享库运行时路径、`FetchContent`、preset 与安装导出。函数体、类型、命名、异常和源码注释只开 `developing-cpp`；配置完成后要跑构建、格式化、静态检查或入口脚本时开 `building-cpp`。
+
+一次改动同时碰到源码和 CMake 时先开 `developing-cpp` 定行为与边界，再用本技能把源文件、库和程序写进 target，最后到 `building-cpp` 跑检查。只改一个 target 的 include、链接或标准时走增量修正；新工程、新组件、换语言标准或抽公共函数时走整段重构。
+
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。`environment.json` 的 `standard` 是 target 标准的唯一来源；缺失、非法或与现有 target 不一致时停在定 target，不猜标准。构建目录、编译器和工具版本由 `building-cpp` 的定构建负责，本技能只写 target 契约。
+
+## 两种走法
+
+| 走法 | 什么时候用 | 怎么做 |
+| --- | --- | --- |
+| 增量修正 | 一个 target 的 include、链接、标准、输出目录或一条属性不对 | 先读现有 `CMakeLists.txt`，只改这一处，不动无关 target 和全局设置 |
+| 整段重构 | 新工程、新组件、抽公共函数、换语言标准或整理目录 | 同样三步；先定 target 图与标准，再定模块与函数，最后跑完整检查 |
+
+共同不变量：不发明项目没有声明的 target、标准、编译器或目录；不覆盖已有 `CMakeLists.txt`；不用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料；不写 `file(GLOB ...)`；不把 `main()` 编进库；库与程序不下载依赖，只有测试需要时调用 `LinkSettings_FetchGoogleTest`。后一步发现前一步没做完，退回那一步。
+
+## 步骤
+
+| 步 | 名称 | 文件 | 一句话 |
+| --- | --- | --- | --- |
+| 1 | 定 target 与标准 | `steps/01-targets.md` | target 图、PUBLIC/PRIVATE、标准、输出目录与编译数据库 |
+| 2 | 定模块与函数 | `steps/02-modules.md` | 何时抽函数、文件与命名、导入、注释与 2 空格排版 |
+| 3 | 通过检查 | `steps/03-check.md` | configure、构建、编译数据库与实际 `-std` 核对 |
+
+每步只打开同号的一个步骤文件。判不准才打开 `examples/cmake.md`；`references/cmake.md` 保存 target、链接、输出、RPATH、依赖与反模式的完整条文，`references/cxx-standard.md` 保存 C++11–C++23 的标准映射，`references/modules.md` 保存函数与模块契约。可复制的函数在 `assets/cmake/`：`CompileSettings.cmake` 放标准与警告，`LinkSettings.cmake` 放构建期 RPATH 与 GoogleTest 依赖；一个文件按性质收一组函数。
+
+五档标准的语言设施、工具映射与降档仍由 `building-cpp/references/standards/` 维护；本技能只负责这些标准在 CMake 里怎么写。
+
+### 四类改动
+
+先认这次改的是哪一类，再决定从哪一步进；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做。
+
+| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
+| --- | --- | --- | --- |
+| 写作 | 新增 target、改公共 include 或链接边界、换语言标准 | 第 1 步 | `steps/01-targets.md`、`references/cxx-standard.md` |
+| 布局 | 抽函数、拆模块、调导入位置 | 第 2 步 | `steps/02-modules.md`、`references/modules.md` |
+| 排版 | 只改 2 空格、行宽或注释形态 | 第 2 步的契约写法 | `references/cmake.md`、`references/modules.md` |
+| 润色 | 只改函数名、注释措辞或错误消息 | 第 2 步 | `references/modules.md` |
+
+## 完成判据
+
+- target 图显式：程序 target 叫 `app`，库 target 用组件名，程序链接库，库的公共 include 用 `PUBLIC`；没有全局 include、全局编译选项或 GLOB。
+- 每个 target 的标准来自 `environment.json`；`target_compile_features` 与 `CXX_STANDARD`、`CXX_STANDARD_REQUIRED ON`、`CXX_EXTENSIONS OFF` 同时存在，live 的 `compile_commands.json` 最后一条 `-std=` 与声明一致，不是 `gnu++NN`。
+- 复用的 CMake 函数放在 `cmake/` 模块里，文件名用 UpperCamelCase，函数名用 `<ModuleName>_` 加 PascalCase，有目标与参数校验，根 `CMakeLists.txt` 通过 `CMAKE_MODULE_PATH` 导入；没有重复片段和未使用的旧模块。
+- 公开函数上方写中文 `#` 契约：一句功能、空行、边界，再用 `:param` / `:keyword` 标参数；不写 `#[[.rst:` 与 `.. command::`，完整写法见 `references/cmake.md`；函数组之间用 `#---`，不画 `#===...===#` 方框。
+- `CMakeLists.txt` 与 `*.cmake` 用 UTF-8 无 BOM、LF、2 空格缩进、不用 tab；行宽按团队约定，默认 80 列。
+- configure 与构建通过，构建产物不落在源码目录；没有改源码语义，也没有覆盖已有工程文件。

package/skills/configuring-cmake/assets/cmake/CompileSettings.cmake

@@ -0,0 +1,126 @@
+# CompileSettings
+#
+# 在一个目标上设置 C++ 语言标准与警告等级。
+#
+# 用 include(CompileSettings) 载入。两个函数都只改传入的目标，
+# 不建全局变量，也不下载依赖。
+include_guard(GLOBAL)
+
+#-------------------------------------------------------------------------------
+# 让一个目标使用指定的 C++ 标准。
+#
+# :param target: 已经存在的 CMake 目标。
+# :param visibility: 取 PUBLIC、PRIVATE 或 INTERFACE。
+# :param standard: 取 c++11、c++14、c++17、c++20 或 c++23。
+function(CompileSettings_SetCxxStandard target visibility standard)
+  if(NOT TARGET "${target}")
+    message(FATAL_ERROR
+      "CompileSettings_SetCxxStandard: target '${target}' does not exist")
+  endif()
+
+  if(NOT visibility MATCHES "^(PUBLIC|PRIVATE|INTERFACE)$")
+    message(FATAL_ERROR
+      "CompileSettings_SetCxxStandard: visibility must be "
+      "PUBLIC, PRIVATE, or INTERFACE")
+  endif()
+
+  set(supported_standards c++11 c++14 c++17 c++20 c++23)
+  if(NOT standard IN_LIST supported_standards)
+    message(FATAL_ERROR
+      "CompileSettings_SetCxxStandard: standard must be one of "
+      "${supported_standards}")
+  endif()
+
+  # c++23 -> 23：两种声明使用同一个编号。
+  string(SUBSTRING "${standard}" 3 -1 number)
+  target_compile_features("${target}" "${visibility}" "cxx_std_${number}")
+  set_target_properties("${target}" PROPERTIES
+    CXX_STANDARD "${number}"
+    CXX_STANDARD_REQUIRED ON
+    CXX_EXTENSIONS OFF
+  )
+endfunction()
+
+#-------------------------------------------------------------------------------
+# 给一个目标加上编译警告。
+#
+# 只改传入的目标。PRIVATE 不向使用方传播。
+#
+# :param target: 已经存在的 CMake 目标。
+# :param visibility: 取 PRIVATE 或 INTERFACE。
+# :keyword LEVEL: 可省略。取 basic、standard 或 strict；
+#   省略时按 standard。
+function(CompileSettings_SetWarnings target visibility)
+  cmake_parse_arguments(PARSE_ARGV 2 arg "" "LEVEL" "")
+
+  if(arg_UNPARSED_ARGUMENTS)
+    message(FATAL_ERROR
+      "CompileSettings_SetWarnings: unexpected arguments: "
+      "${arg_UNPARSED_ARGUMENTS}")
+  endif()
+
+  if(NOT TARGET "${target}")
+    message(FATAL_ERROR
+      "CompileSettings_SetWarnings: target '${target}' does not exist")
+  endif()
+
+  if(NOT visibility MATCHES "^(PRIVATE|INTERFACE)$")
+    message(FATAL_ERROR
+      "CompileSettings_SetWarnings: visibility must be PRIVATE or INTERFACE")
+  endif()
+
+  if(NOT arg_LEVEL)
+    set(arg_LEVEL standard)
+  endif()
+
+  if(MSVC)
+    set(basic_warnings /W4)
+    set(standard_warnings ${basic_warnings} /permissive- /WX)
+    set(strict_warnings
+      ${standard_warnings}
+      /w14242 /w14254 /w14263 /w14265 /w14287 /w14296
+      /w14311 /w14545 /w14546 /w14547 /w14549 /w14555
+      /w14619 /w14640 /w14826
+    )
+  elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
+    set(basic_warnings -Wall -Wextra)
+    set(standard_warnings
+      ${basic_warnings}
+      -Werror              # 把告警当错误
+      -Wshadow             # 变量遮蔽
+      -Wold-style-cast     # C 风格转换
+      -Wpedantic           # 非标准扩展
+      -Wnon-virtual-dtor   # 有虚函数但析构非虚
+      -Woverloaded-virtual
+    )
+    set(strict_warnings
+      ${standard_warnings}
+      -Wcast-align
+      -Wcast-qual
+      -Wconversion
+      -Wsign-conversion
+      -Wdouble-promotion
+      -Wformat=2
+      -Wimplicit-fallthrough
+      -Wnull-dereference
+      -Wundef
+    )
+  else()
+    message(FATAL_ERROR
+      "CompileSettings_SetWarnings: unsupported compiler "
+      "'${CMAKE_CXX_COMPILER_ID}'")
+  endif()
+
+  if(arg_LEVEL STREQUAL "basic")
+    set(warnings ${basic_warnings})
+  elseif(arg_LEVEL STREQUAL "standard")
+    set(warnings ${standard_warnings})
+  elseif(arg_LEVEL STREQUAL "strict")
+    set(warnings ${strict_warnings})
+  else()
+    message(FATAL_ERROR
+      "CompileSettings_SetWarnings: LEVEL must be basic, standard, or strict")
+  endif()
+
+  target_compile_options("${target}" "${visibility}" ${warnings})
+endfunction()

package/skills/configuring-cmake/assets/cmake/LinkSettings.cmake

@@ -0,0 +1,48 @@
+# LinkSettings
+#
+# 设置构建期运行时路径，并为测试取回 GoogleTest。
+#
+# 用 include(LinkSettings) 载入。LinkSettings_FetchGoogleTest 是本文件
+# 唯一会下载的函数，只在测试需要时调用。
+include_guard(GLOBAL)
+
+#-------------------------------------------------------------------------------
+# 让 build/bin 里的程序找到同级 build/lib 下的库。
+#
+# 只改构建树，不改安装后的 RPATH。
+#
+# :param target: 已经存在的 CMake 目标。
+function(LinkSettings_SetBuildRpath target)
+  if(NOT TARGET "${target}")
+    message(FATAL_ERROR
+      "LinkSettings_SetBuildRpath: target '${target}' does not exist")
+  endif()
+
+  if(APPLE)
+    set_target_properties("${target}" PROPERTIES
+      BUILD_RPATH "@loader_path/../lib")
+  else()
+    set_target_properties("${target}" PROPERTIES BUILD_RPATH "$ORIGIN/../lib")
+  endif()
+endfunction()
+
+#-------------------------------------------------------------------------------
+# 取回 GoogleTest 并让其 target 可用。
+#
+# 固定 v1.17.0 与 SHA-256；只在 tests 目录调用，库与程序代码不调用。
+function(LinkSettings_FetchGoogleTest)
+  include(FetchContent)
+
+  if(POLICY CMP0135)
+    cmake_policy(SET CMP0135 NEW)
+  endif()
+
+  FetchContent_Declare(
+    googletest
+    URL https://codeload.github.com/google/googletest/tar.gz/refs/tags/v1.17.0
+    URL_HASH
+      SHA256=65fab701d9829d38cb77c14acdc431d2108bfdbf8979e40eb8ae567edf10b27c
+  )
+  set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+  FetchContent_MakeAvailable(googletest)
+endfunction()

package/skills/configuring-cmake/examples/cmake.md

@@ -0,0 +1,224 @@
+# 正反例：CMake
+
+## 最小可用形状
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(greeter VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+
+# 先把 assets/cmake/ 里的 CompileSettings.cmake 复制到工程的 cmake/。
+include(CompileSettings)
+
+add_library(greeting STATIC greeting/src/greeting.cpp)
+target_include_directories(greeting PUBLIC greeting/include)
+CompileSettings_SetCxxStandard(greeting PUBLIC c++23)
+CompileSettings_SetWarnings(greeting PRIVATE LEVEL standard)
+
+add_executable(app src/main.cpp)
+CompileSettings_SetCxxStandard(app PRIVATE c++23)
+CompileSettings_SetWarnings(app PRIVATE LEVEL standard)
+target_link_libraries(app PRIVATE greeting)
+```
+
+程序只写 `#include "greeting.h"`；公共 include 根由库的 `PUBLIC` 传过来。
+
+## 全局 include
+
+**差**：
+
+```cmake
+include_directories(include greeting/include)
+add_executable(app src/main.cpp greeting/src/greeting.cpp)
+```
+
+问题：所有 target 共享 include，边界消失；程序直接编译库源码，测试无法只链接库。
+
+**好**：
+
+```cmake
+target_include_directories(greeting PUBLIC greeting/include)
+target_link_libraries(app PRIVATE greeting)
+```
+
+## GLOB
+
+**差**：
+
+```cmake
+file(GLOB SOURCES "src/*.cpp")
+add_executable(app ${SOURCES})
+```
+
+新增文件不触发重新配置；不同机器上的文件集合可能不同。
+
+**好**：
+
+```cmake
+add_executable(app
+  src/main.cpp
+  src/task_list.cpp
+  src/task_parser.cpp
+)
+```
+
+显式列表，新增文件时改 CMake；diff 能看出变化。
+
+## 把 `main()` 编进库
+
+**差**：
+
+```cmake
+add_library(core STATIC src/main.cpp src/core.cpp)
+add_executable(app src/main.cpp)   # 重复定义
+```
+
+**好**：
+
+```cmake
+add_library(core STATIC src/core.cpp)
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE core)
+```
+
+库不依赖 `main()`；测试链接库时不会碰到入口。
+
+## 标准只写一半
+
+**差**：
+
+```cmake
+target_compile_features(app PRIVATE cxx_std_20)
+# 没写 CXX_STANDARD_REQUIRED；编译器不支持时可能静默降级
+set_target_properties(app PROPERTIES CXX_STANDARD 20)
+```
+
+问题：meta-feature 只保证“至少”，`CXX_STANDARD` 又允许 decay，实际标准可能不是 20。
+
+**好**：
+
+```cmake
+CompileSettings_SetCxxStandard(app PRIVATE c++20)
+```
+
+两套声明同时写；`CXX_STANDARD_REQUIRED ON` 禁止降级，`CXX_EXTENSIONS OFF` 把 `gnu++20` 收成 `c++20`。
+
+## 警告等级
+
+**差**：
+
+```cmake
+target_compile_options(app PRIVATE -Wall -Wextra -Werror)
+target_compile_options(core PRIVATE -Wall -Wextra -Werror)
+# 每个 target 复制一遍；想加 -Wshadow 时要逐处改
+```
+
+**好**：
+
+```cmake
+CompileSettings_SetWarnings(app PRIVATE LEVEL standard)
+CompileSettings_SetWarnings(core PRIVATE LEVEL strict)
+```
+
+`basic` 只开 `-Wall -Wextra`；`standard` 加 `-Werror`、`-Wshadow`、`-Wold-style-cast`、`-Wpedantic`、`-Wnon-virtual-dtor`、`-Woverloaded-virtual`；`strict` 再加转换、格式化与可移植性告警。警告只作用于传入 target，不通过 `INTERFACE` 传播。
+
+## 编译数据库
+
+**差**：
+
+```cmake
+# 没开导出
+```
+
+```bash
+clang-tidy src/main.cpp   # 没有编译参数，头路径和标准都不对
+```
+
+**好**：
+
+```cmake
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+```
+
+```bash
+cmake -S . -B build/clang -G Ninja -DCMAKE_CXX_COMPILER=clang++
+rm -f build/compile_commands.json
+ln -s clang/compile_commands.json build/compile_commands.json
+clang-tidy -p build/clang src/main.cpp
+```
+
+## 共享库运行时路径
+
+**差**：
+
+```bash
+LD_LIBRARY_PATH=build/clang/lib ./build/clang/bin/app   # 每次运行都要包一层
+```
+
+**好**：
+
+```cmake
+# LinkSettings.cmake 提供 RPATH 与 GoogleTest 依赖函数。
+include(LinkSettings)
+
+add_library(greeting SHARED greeting/src/greeting.cpp)
+set_target_properties(greeting PROPERTIES
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE greeting)
+LinkSettings_SetBuildRpath(app)
+```
+
+从 `build/<compiler>/bin/app` 直接启动即可找到同级 `../lib` 下的共享库；安装场景另配 RPATH。
+
+## 输出目录
+
+**差**：可执行文件生成在源码根，`git status` 出现 `app`、`*.o`。
+
+**好**：
+
+```cmake
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+```
+
+构建产物全在 `build/<compiler>/` 下。
+
+## 注释
+
+**差**：
+
+```cmake
+#[[.rst:
+CompileSettings_SetWarnings
+---------------------------
+
+.. command:: CompileSettings_SetWarnings(target visibility)
+
+:param target: 目标。
+@param visibility: 可见性。
+@return: 无。
+]]
+```
+
+`#[[.rst:` 与 `.. command::` 是给要进 CMake 手册的模块用的抽取标记，本仓模块不进手册；`@param`、`@return` 是 C++ 的 Doxygen 标签，CMake 里不用。CMake 函数也没有返回值，`:return:` 同样不写。
+
+**好**：
+
+```cmake
+# 给一个目标加上编译警告。
+#
+# 只改传入的目标。PRIVATE 不向使用方传播。
+#
+# :param target: 已经存在的 CMake 目标。
+# :param visibility: 取 PRIVATE 或 INTERFACE。
+# :keyword LEVEL: 可省略。取 basic、standard 或 strict；省略时按 standard。
+function(CompileSettings_SetWarnings target visibility)
+```
+
+普通 `#` 行，签名留在 `function()` 那一行；位置参数用 `:param`，`cmake_parse_arguments` 的关键字用 `:keyword`。