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

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/{building-cpp → configuring-cmake}/examples/cmake.md

@@ -10,15 +10,17 @@ 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)
-target_compile_features(greeting PUBLIC cxx_std_23)
-set_target_properties(greeting PROPERTIES CXX_EXTENSIONS OFF)
-target_compile_options(greeting PRIVATE -Wall -Wextra -Werror)
+CompileSettings_SetCxxStandard(greeting PUBLIC c++23)
+CompileSettings_SetWarnings(greeting PRIVATE LEVEL standard)
 
 add_executable(app src/main.cpp)
-target_compile_features(app PRIVATE cxx_std_23)
-set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
+CompileSettings_SetCxxStandard(app PRIVATE c++23)
+CompileSettings_SetWarnings(app PRIVATE LEVEL standard)
 target_link_libraries(app PRIVATE greeting)
 ```
 
@@ -84,6 +86,45 @@ 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` 传播。
+
 ## 编译数据库
 
 **差**：
@@ -120,17 +161,16 @@ 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)
-if(APPLE)
-  set_target_properties(app PROPERTIES BUILD_RPATH "@loader_path/../lib")
-else()
-  set_target_properties(app PROPERTIES BUILD_RPATH "$ORIGIN/../lib")
-endif()
+LinkSettings_SetBuildRpath(app)
 ```
 
 从 `build/<compiler>/bin/app` 直接启动即可找到同级 `../lib` 下的共享库；安装场景另配 RPATH。
@@ -148,3 +188,37 @@ 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`。

package/skills/{building-cpp → configuring-cmake}/references/cmake.md

@@ -1,10 +1,12 @@
 # CMake
 
-目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`，可复用的 CMake 片段在 `assets/cmake/`：`applying-warnings.cmake` 管警告选项，`fetching-googletest.cmake` 取测试框架，`setting-rpath.cmake` 设运行时库路径。
+目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；工程模板仍由 `building-cpp` 提供，在 `../../building-cpp/assets/templates/projects/`，可复用的 CMake 函数在本技能的 `assets/cmake/`：`CompileSettings.cmake` 收标准与警告，`LinkSettings.cmake` 收构建期 RPATH 与 GoogleTest 依赖。
 
 ## 排版
 
-CMake 没有官方风格指南。这里跟随 Google 自家项目的 `cmake-format` 配置：缩进 2 个空格、行宽 80、不用 tab。来源是 [or-tools 的 .cmake-format.py](https://github.com/google/or-tools/blob/stable/.cmake-format.py) 与 [draco 的 .cmake-format.py](https://github.com/google/draco/blob/master/.cmake-format.py)，两处都设 `tab_size=2`、`line_width=80`。命令行、列表和注释都按这个宽度换行；`CMakeLists.txt` 与 `*.cmake` 一视同仁。
+CMake 没有单独的官方风格指南文档，但官方仓库的 [.editorconfig](https://raw.githubusercontent.com/Kitware/CMake/master/.editorconfig) 明确规定：`CMakeLists.txt`、`*.cmake`、`*.rst` 使用 `indent_size = 2`、`indent_style = space`。这是官方代码风格的直接依据。行宽 80 列来自社区 `cmake-format` 约定（[or-tools](https://github.com/google/or-tools/blob/stable/.cmake-format.py)、[draco](https://github.com/google/draco/blob/master/.cmake-format.py) 都设 `tab_size=2`、`line_width=80`），不是 CMake 官方强制值。命令行、列表和注释都按项目约定的宽度换行；`CMakeLists.txt` 与 `*.cmake` 一视同仁。
+
+注释不用 `#[[.rst:`。那层标记只属于要进 CMake 手册的模块：Kitware 在 [documentation.rst](https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst) 里用 `.. command::` 与参数段，供 Sphinx 从源码抽进手册；本仓的模块不进手册，读者也读不懂这层标记。公开函数上方写中文 `#` 契约：第一句说功能，空一行写边界，再用 `:param 名字:` 标位置参数、`:keyword 名字:` 标 `cmake_parse_arguments` 的关键字；CMake 函数没有返回值，不写 `:return:`，也不把 C++ 的 `@param`、`@return` 搬进来。字段取自 [CMinx](https://cmakepp.github.io/CMinx/documenting/function.html)；本仓不跑 CMinx，注释保持普通 `#` 行。签名留在 `function()` 那一行，同一文件的函数组之间用一条 `#---` 短横线分隔；行注释只写原因，不画 `#===...===#` 方框。官方 [GoogleTest.cmake](https://github.com/Kitware/CMake/blob/master/Modules/GoogleTest.cmake) 在一个文件里放多个测试函数，可作“文件按职责聚合”的参照；社区 [CompilerWarnings.cmake](https://github.com/cpp-best-practices/cmake_template/blob/main/cmake/CompilerWarnings.cmake) 在每个警告 flag 后写它抓什么问题，可作参数注释的参照。
 
 Shell 脚本用 2 个空格缩进、不用 tab，来源是 [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html#indentation)。
 
@@ -19,14 +21,12 @@ project({{PROJECT_NAME}} VERSION 0.1.0 LANGUAGES CXX)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
+# 先把 assets/cmake/ 里的 CompileSettings.cmake 复制到工程的 cmake/。
+include(CompileSettings)
+
 add_executable(app src/main.cpp)
-target_compile_features(app PRIVATE cxx_std_23)
-set_target_properties(app PROPERTIES
-  CXX_STANDARD 23
-  CXX_STANDARD_REQUIRED ON
-  CXX_EXTENSIONS OFF
-)
-target_compile_options(app PRIVATE -Wall -Wextra -Werror)
+CompileSettings_SetCxxStandard(app PRIVATE c++23)
+CompileSettings_SetWarnings(app PRIVATE LEVEL standard)
 ```
 
 ### 库 + 程序
@@ -40,42 +40,56 @@ 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")
 
+# 先把 assets/cmake/ 里的 CompileSettings.cmake 复制到工程的 cmake/。
+include(CompileSettings)
+
 add_subdirectory(greeting)
 
 add_executable(app src/main.cpp)
-target_compile_features(app PRIVATE cxx_std_23)
-set_target_properties(app PROPERTIES
-  CXX_STANDARD 23
-  CXX_STANDARD_REQUIRED ON
-  CXX_EXTENSIONS OFF
-)
+CompileSettings_SetCxxStandard(app PRIVATE c++23)
+CompileSettings_SetWarnings(app PRIVATE LEVEL standard)
 target_link_libraries(app PRIVATE greeting)
-target_compile_options(app PRIVATE -Wall -Wextra -Werror)
 ```
 
 ```cmake
 # greeting/CMakeLists.txt
 add_library(greeting STATIC src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
-target_compile_features(greeting PUBLIC cxx_std_23)
-set_target_properties(greeting PROPERTIES
-  CXX_STANDARD 23
-  CXX_STANDARD_REQUIRED ON
-  CXX_EXTENSIONS OFF
-)
-target_compile_options(greeting PRIVATE -Wall -Wextra -Werror -Wold-style-cast -Wshadow)
+CompileSettings_SetCxxStandard(greeting PUBLIC c++23)
+CompileSettings_SetWarnings(greeting PRIVATE LEVEL standard)
 ```
 
 - 库的 `PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..` 让程序能从仓库根写 `#include "greeting/include/greeting.h"`，不需要程序再写 include 路径。
-- `cxx_std_23` 用 `PUBLIC` 从库传播；程序自己再加一次也无害。`CXX_STANDARD_REQUIRED ON` 防止 CMake 在编译器不支持时静默 decay；显式 `CXX_STANDARD` 与 `standard` 保持一致。
-- `CXX_EXTENSIONS OFF` 把 `-std=gnu++23` 收成 `-std=c++23`，与 Google 的「不用非标准扩展」一致；每个 target 都要设。configure 后检查 `compile_commands.json` 的最后一条 `-std=`，不能是 `gnu++NN`。
+- 标准用 `CompileSettings_SetCxxStandard`：库用 `PUBLIC` 传播，程序用 `PRIVATE`；函数内部同时写 `target_compile_features` 与 `CXX_STANDARD` 三属性。
+- `CXX_STANDARD_REQUIRED ON` 防止 CMake 在编译器不支持时静默 decay；`CXX_EXTENSIONS OFF` 把 `-std=gnu++NN` 收成 `-std=c++NN`。configure 后检查 `compile_commands.json` 的最后一条 `-std=`。
 - 程序 target 固定 `app`；库 target 用组件名。
 
+## 标准与复用
+
+C++11–C++23 的两层声明、可见性、常见错误与验证见 `references/cxx-standard.md`。通用函数 `CompileSettings_SetCxxStandard(target visibility c++NN)` 在 `assets/cmake/CompileSettings.cmake`：
+
+```cmake
+CompileSettings_SetCxxStandard(app PRIVATE c++23)
+CompileSettings_SetCxxStandard(greeting PUBLIC c++20)
+```
+
+函数名不绑定单一标准；新增档位只改函数里的支持列表。模块何时抽、文件怎么放、怎么导入与测试见 `references/modules.md`。
+
+## 警告等级
+
+`cmake/CompileSettings.cmake` 的 `CompileSettings_SetWarnings(<target> <visibility> LEVEL basic|standard|strict)` 把常用 flag 收成三档；`visibility` 用 `PRIVATE` 或 `INTERFACE`，`PRIVATE` 不向使用方传播。警告与标准写在同一份编译设置模块里。
+
+- `basic`：`-Wall -Wextra`；适合刚开始接 CI 的旧代码。
+- `standard`：`basic` 加 `-Werror`、`-Wshadow`、`-Wold-style-cast`、`-Wpedantic`、`-Wnon-virtual-dtor`、`-Woverloaded-virtual`；默认档。
+- `strict`：`standard` 加 `-Wconversion`、`-Wsign-conversion`、`-Wcast-align`、`-Wcast-qual`、`-Wformat=2`、`-Wundef`、`-Wdouble-promotion`、`-Wimplicit-fallthrough`、`-Wnull-dereference`；适合新代码或质量闸门。
+
+MSVC 分支用 `/W4`、`/permissive-`、`/WX`；其他编译器直接报错，避免静默地没有警告。警告是 target 的 `PRIVATE` 选项，库不把自己的策略强加给消费者。
+
 ## target-based 规则
 
 - 每个 target 自己声明 include、标准、编译选项、链接库；不要用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料。
 - `target_include_directories(<target> PUBLIC|PRIVATE <dir>)`：公共头给 `PUBLIC`，私有实现目录给 `PRIVATE`。
-- `target_compile_features(<target> PUBLIC cxx_std_23)`：标准是 target 属性，不是全局开关。
+- `target_compile_features(<target> PUBLIC cxx_std_NN)`：标准是 target 属性，不是全局开关；优先调用项目 `cmake/` 里的标准函数。
 - `target_link_libraries(<target> PRIVATE|PUBLIC <lib>)`：实现依赖用 `PRIVATE`，接口依赖用 `PUBLIC`。
 - 不要 `file(GLOB ...)`；显式列源文件，新增文件时改 CMake，构建系统才知道。`CONFIGURE_DEPENDS` 依赖构建系统每次检查目录，跨生成器行为也不完全一致，不作为工程规则。
 - 不把 `main()` 编进库；程序只做装配和 I/O。
@@ -119,16 +133,14 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 ## 共享库运行时路径
 
 ```cmake
-if(APPLE)
-  set_target_properties(app PROPERTIES BUILD_RPATH "@loader_path/../lib")
-else()
-  set_target_properties(app PROPERTIES BUILD_RPATH "$ORIGIN/../lib")
-endif()
+include(LinkSettings)
+LinkSettings_SetBuildRpath(app)
 ```
 
+- 函数按平台写 `BUILD_RPATH`：Linux 用 `$ORIGIN/../lib`，Apple 用 `@loader_path/../lib`。
 - 只对需要直接运行构建产物的程序设置；安装规则另算。
 - 不要用全局 `LD_LIBRARY_PATH` 包装所有命令；共享库的运行时路径由 target 的 RPATH 设置，不在脚本里全局改寻库路径。
-- `$ORIGIN` 在 CMake 字符串里要转义成 `\$ORIGIN` 吗？在双引号里 `$ORIGIN` 会被 CMake 当变量；写成 `"$ORIGIN/../lib"` 在 CMake 中 `$ORIGIN` 不是 `${...}`，不会被展开，保持字面量。若遇到展开问题，用 `"\$ORIGIN/../lib"`。
+- `$ORIGIN` 在 CMake 双引号里不是 `${...}`，不会被展开，保持字面量；若遇到展开问题，用 `"\$ORIGIN/../lib"`。
 
 ## 标准库与编译器一致
 
@@ -147,21 +159,15 @@ endif()
 
 ## GoogleTest
 
-需要测试框架时，用固定版本的 `FetchContent`：
+需要测试框架时，用固定版本的 `LinkSettings_FetchGoogleTest`：
 
 ```cmake
-include(FetchContent)
-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)
+include(LinkSettings)
+LinkSettings_FetchGoogleTest()
 ```
 
-- 版本固定，不用 `master`；URL 和哈希写在一起，避免供应链漂移。
-- 只在 `tests/` 需要时拉取；库和程序不依赖测试框架。
+- 函数内部固定 GoogleTest v1.17.0 的 URL 与 SHA-256，避免供应链漂移；版本升级只改一处。
+- 只在 `tests/` 需要时调用；库和程序不依赖测试框架。
 - 没有网络时，项目可以自带 vendored 副本；不要构建时静默跳过测试。
 
 ## 模板选择

package/skills/configuring-cmake/references/cxx-standard.md

@@ -0,0 +1,67 @@
+# C++ 标准与 CMake
+
+目标：一个 target 只声明一个标准，声明在 target 上，编译数据库里的实际参数与声明一致。
+
+## 两层声明
+
+CMake 有两套相关机制，必须同时写：
+
+- `target_compile_features(target visibility cxx_std_NN)`：声明目标至少需要该标准。它是 meta-feature，编译器默认标准更高时可能不产生 `-std=`；只写这一项，不能保证实际使用哪个标准。
+- `CXX_STANDARD NN` + `CXX_STANDARD_REQUIRED ON` + `CXX_EXTENSIONS OFF`：把请求标准写死，禁止不可用时静默降级，并关闭 `gnu++NN` 扩展。
+
+| `standard` | meta-feature | `CXX_STANDARD` | `__cplusplus` | CMake 最低版本 |
+| --- | --- | --- | --- | --- |
+| `c++11` | `cxx_std_11` | `11` | `201103L` | 3.1 |
+| `c++14` | `cxx_std_14` | `14` | `201402L` | 3.1 |
+| `c++17` | `cxx_std_17` | `17` | `201703L` | 3.8 |
+| `c++20` | `cxx_std_20` | `20` | `202002L` | 3.12 |
+| `c++23` | `cxx_std_23` | `23` | `202302L` | 3.20 |
+
+`cxx_std_23` 与 `CXX_STANDARD 23` 都要求 CMake 3.20；工程 `cmake_minimum_required` 低于该版本时先升最低版本，不要悄悄降到 C++20。
+
+## 通用函数
+
+`assets/cmake/CompileSettings.cmake` 提供：
+
+```cmake
+CompileSettings_SetCxxStandard(app PRIVATE c++23)
+CompileSettings_SetCxxStandard(greeting PUBLIC c++20)
+```
+
+第一个参数是已由 `add_library` 或 `add_executable` 创建的目标，第二个是 `PUBLIC` / `PRIVATE` / `INTERFACE`，第三个是 `c++11`–`c++23`。函数内部做三步：校验目标与参数，调用 `target_compile_features`，再设置 `CXX_STANDARD` 三属性。
+
+扩展新标准时改函数里的 `supported_standards` 与错误提示；不要在目标目录复制第二份三属性。
+
+## 可见性
+
+- 库的公共接口需要该标准时用 `PUBLIC`，链接者自动继承。
+- 程序、测试、实现文件用 `PRIVATE`。
+- `INTERFACE` 只用于纯头文件 target；不要用它绕过「标准应写在有源文件的目标上」。
+- `target_compile_features` 重复调用会追加特性；同一目标不要同时写两个不同标准。
+
+## 常见错误
+
+| 写法 | 问题 |
+| --- | --- |
+| 只写 `target_compile_features(... cxx_std_23)` | 编译器默认更高时可能不加 `-std`，实际标准不可见 |
+| 只写 `CXX_STANDARD 23`，不写 `CXX_STANDARD_REQUIRED` | 编译器不支持时静默降级 |
+| 不写 `CXX_EXTENSIONS OFF` | 得到 `-std=gnu++23`，用了非标准扩展 |
+| 用 `CMAKE_CXX_STANDARD` 全局设一次 | 所有 target 被同一个值绑住，无法按组件降档 |
+| 在 `CMAKE_CXX_FLAGS` 里手写 `-std=c++23` | 与 target 属性冲突，数据库不可信 |
+| 把 `cxx_std_23` 写成 `cxx_std_2023` | meta-feature 名字错误，configure 失败 |
+
+## 验证
+
+configure 后读 `build/<compiler>/compile_commands.json`，取最后一条 `-std=`：
+
+```bash
+grep -o -- '-std=[^ ]*' build/clang/compile_commands.json | sort -u
+```
+
+输出必须只有一条，且等于 `-std=c++NN`；出现 `gnu++NN`、两条不同值或没有 `-std=` 都回第 1 步。`CXX_STANDARD_REQUIRED ON` 与 `CXX_EXTENSIONS OFF` 同时存在时，主流编译器会给出精确的 `-std=c++NN`；仍以数据库为准，不靠猜。
+
+## 官方依据
+
+- [`target_compile_features`](https://cmake.org/cmake/help/latest/command/target_compile_features.html)：meta-feature、scope 与追加语义。
+- [`CXX_STANDARD`](https://cmake.org/cmake/help/latest/prop_tgt/CXX_STANDARD.html)：支持值、3.20 起支持 23、`CXX_STANDARD_REQUIRED` 与 `CXX_EXTENSIONS`。
+- [`cmake-compile-features(7)`](https://cmake.org/cmake/help/latest/manual/cmake-compile-features.7.html)：meta-feature 的「至少」语义与编译器默认标准。

package/skills/configuring-cmake/references/modules.md

@@ -0,0 +1,105 @@
+# CMake 模块与函数
+
+目标：同一段构建逻辑只有一份权威，函数可导入、可校验、可测试，目标目录只表达差异。
+
+## 何时抽
+
+抽函数的条件是「已经真实复用」或「需要统一校验」，不是「看起来可以复用」：
+
+- 至少两个 target 或两个子目录重复同一段语义，并且这段语义已经稳定。
+- 标准、警告、RPATH 这类横切规则需要一处升级、全仓生效。
+- 逻辑有独立失败路径，需要 `message(FATAL_ERROR)` 把输入错误挡在 configure 阶段。
+
+一次性三行属性、仍在频繁变化的实验代码、只服务一个 target 的私有设置不抽；等第二次复用出现再抽。
+
+## 文件布局
+
+```text
+project/
+  CMakeLists.txt
+  cmake/
+    CompileSettings.cmake
+    LinkSettings.cmake
+  component/
+    CMakeLists.txt
+  apps/
+    CMakeLists.txt
+```
+
+- 一个文件放一组语义相近的函数，不为每个函数建单独文件；文件过大或出现无关职责时再拆。
+- 文件名用 UpperCamelCase，与 CMake 官方 `Modules/` 一致；按职责命名，例如 `CompileSettings.cmake`、`LinkSettings.cmake`。不用 kebab-case，也不用现在分词。
+- 函数名用 `<ModuleName>_` 加 PascalCase：`CompileSettings_SetCxxStandard`、`LinkSettings_FetchGoogleTest`。前缀取模块文件名的原样大小写，复制到工程后不改名。
+- 工程自己新增、不准备回流的函数才用项目前缀加 snake_case，例如 `my_project_do_something`。
+- 只有项目真的需要时才建 `cmake/`；一个函数都没有时不建空目录。
+
+## 导入
+
+根 `CMakeLists.txt` 在 `project()` 之后、`add_subdirectory()` 之前：
+
+```cmake
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+include(CompileSettings)
+```
+
+- `CMAKE_MODULE_PATH` 只在根追加一次。
+- 子目录只调用函数，不重复 `include()`；重复导入靠模块里的 `include_guard(GLOBAL)` 兜底。
+- 模块名与文件名一致；改名时全仓搜索旧 `include()` 与旧函数名。
+- 不使用 `include()` 执行有副作用的脚本；模块只定义函数。
+
+## 函数契约
+
+```cmake
+include_guard(GLOBAL)
+
+function(CompileSettings_SetCxxStandard target visibility standard)
+  if(NOT TARGET ${target})
+    message(FATAL_ERROR "目标 ${target} 尚未创建")
+  endif()
+  # 校验 visibility 与 standard，再设置 target 属性。
+endfunction()
+
+# 同一文件的第二组函数前再放一条 #--- 分隔线。
+function(CompileSettings_SetWarnings target visibility level)
+  # 校验 LEVEL，再调用 target_compile_options。
+endfunction()
+```
+
+规则：
+
+- 参数顺序稳定，调用处不靠位置猜；参数多时在注释里列出类型与取值范围。
+- 先校验目标存在、可见性合法、标准在支持列表内，再调用 `target_*`。
+- 失败用 `FATAL_ERROR`，消息带函数名与非法值；不要 `WARNING` 后继续。
+- 只改传入 target 的属性；不写全局变量，不读环境变量，不下载依赖。`LinkSettings_FetchGoogleTest` 是唯一例外，调用点限制在测试需要它的时候。
+- 函数体保持幂等：同一目标重复调用不产生两份冲突属性。
+
+## 契约注释
+
+公开函数上方写中文 `#` 契约：一句功能、空行、边界，再用 `:param` 标位置参数、`:keyword` 标关键字参数；不写 `#[[.rst:` 与 `.. command::`，那是进 CMake 手册的模块才用的标记。同一文件的函数组之间用一条 `#---` 分隔，行注释只写原因，不画 `#===...===#` 方框。完整写法见 `references/cmake.md`。
+
+## 测试
+
+模块不能只在真实工程里碰运气。建一个临时最小工程，复制模块并覆盖：
+
+1. 合法目标 + 合法可见性 + 每个支持的标准，configure 与构建成功。
+2. 未创建的目标，configure 失败且消息可读。
+3. 非法可见性、非法标准，configure 失败。
+4. 重复 `include()` 不报函数重定义。
+5. `compile_commands.json` 出现对应 `-std=`。
+
+测试完删除临时工程；不把测试用 `CMakeLists.txt` 留在仓库。真实工程里的验证由 `steps/03-check.md` 完成。
+
+## 迁移旧模块
+
+1. 先在新位置建立函数与文件，保留旧入口一个提交周期（如果项目要求兼容）。
+2. 全仓搜索旧函数名与旧 `include()`，逐个替换。
+3. 删除旧文件，更新 `docs/architecture.md` 的职责表与结构检查。
+4. 重新 configure；缓存里残留的旧模块不会自动消失，必要时删构建目录。
+
+## 官方依据
+
+- [`function()`](https://cmake.org/cmake/help/latest/command/function.html)：函数在调用时执行，拥有自己的作用域。
+- [`include_guard()`](https://cmake.org/cmake/help/latest/command/include_guard.html)：按目录或全局防止重复导入。
+- [`CMAKE_MODULE_PATH`](https://cmake.org/cmake/help/latest/variable/CMAKE_MODULE_PATH.html)：`include()` 的模块搜索路径。
+- [CMake Source Code Guide](https://github.com/Kitware/CMake/blob/master/Help/dev/source.rst)：只规定 C++ 风格，没有 CMake 语言风格章节。
+- [Modules/GoogleTest.cmake](https://github.com/Kitware/CMake/blob/master/Modules/GoogleTest.cmake)：官方模块的括号文档块、行注释与 `#---` 函数分隔实例。
+- [cpp-best-practices CompilerWarnings.cmake](https://github.com/cpp-best-practices/cmake_template/blob/main/cmake/CompilerWarnings.cmake)：社区警告模块的注释与命名参数写法。

package/skills/configuring-cmake/steps/01-targets.md

@@ -0,0 +1,53 @@
+# 第 1 步：定 target 与标准
+
+## 产出
+
+一张明确的 target 图、一组 target 属性、一个与 `environment.json` 一致的语言标准。构建结果只取决于声明的组合，不取决于当前 shell 的默认值。
+
+## 通用情况
+
+先读 `environment.json` 的 `standard`，再把它映射成两层：
+
+| `standard` | `target_compile_features` | `CXX_STANDARD` | CMake 最低版本 |
+| --- | --- | --- | --- |
+| `c++11` | `cxx_std_11` | `11` | 3.1 |
+| `c++14` | `cxx_std_14` | `14` | 3.1 |
+| `c++17` | `cxx_std_17` | `17` | 3.8 |
+| `c++20` | `cxx_std_20` | `20` | 3.12 |
+| `c++23` | `cxx_std_23` | `23` | 3.20 |
+
+target 规则：
+
+- 程序 target 固定叫 `app`；库 target 用组件名，程序链接库；不把 `main()` 编进库。
+- 每个 target 自己声明 include、标准、编译选项和链接库；公共头用 `PUBLIC`，实现目录用 `PRIVATE`。
+- 用 `target_include_directories`、`target_compile_features`、`target_link_libraries`；禁止全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS`。
+- 源文件显式列出；不写 `file(GLOB ...)`，新增文件时改 CMake。
+- `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)`；可执行文件输出到 `build/<compiler>/bin`，库到 `build/<compiler>/lib`。
+- 需要直接运行构建产物的共享库程序，设 `BUILD_RPATH "$ORIGIN/../lib"`；Apple 用 `@loader_path/../lib`。
+- 标准用项目 `cmake/` 里的 `CompileSettings_SetCxxStandard(target visibility c++NN)`；没有这个函数时先从 `assets/cmake/CompileSettings.cmake` 复制并导入，不要在每个 target 重复三属性。
+- 警告用同一份 `CompileSettings.cmake` 里的 `CompileSettings_SetWarnings(target visibility LEVEL basic|standard|strict)`；`visibility` 用 `PRIVATE` 或 `INTERFACE`，不要在每个 target 重复 `-Wall` 列表。
+
+## 命令形状
+
+```bash
+cmake -S . -B build/clang -G Ninja \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_CXX_COMPILER=clang++ \
+  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+GCC 模式把目录和编译器换成 `build/gcc`、`g++`。一个 configure 只用一个编译器；CMake 最低 3.20，低于目标标准所需版本时先升 `cmake_minimum_required`，不要静默降标准。
+
+## 情况
+
+**新工程**：工程模板仍由 `building-cpp` 提供，从 `../../building-cpp/assets/templates/projects/` 选形态，只复制目标工程缺的文件；模板里的 `{{PROJECT_NAME}}` 换成真实工程名，再按本节改 target 与标准。
+
+**已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让现有构建跑通，保留可回退点。
+
+**库 + 程序**：库的公共 include 用 `PUBLIC` 传播；程序不直接包含库的 `src/`。静态库与动态库的 target 写法相同，动态库额外设运行时路径。
+
+**测试**：确有第二个消费者时再加 `enable_testing()` 与 `add_subdirectory(tests)`；测试 target 只链接被测库的公共接口，没有测试时不加空测试。
+
+**预设**：使用 preset 时名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令，不要两套并存。
+
+下一步：target 图稳定后，进 `steps/02-modules.md` 决定哪些片段抽成函数。

package/skills/configuring-cmake/steps/02-modules.md

@@ -0,0 +1,37 @@
+# 第 2 步：定模块与函数
+
+## 产出
+
+一个可以重复导入的 `cmake/` 模块，或一份明确不抽函数的理由。模块只定义函数，目标目录不再复制同一段配置。
+
+## 什么时候抽
+
+- 同一段 CMake 在至少两个 target 或两个子目录重复出现，且语义已经稳定。
+- 标准、警告、RPATH 这类横切规则需要一处升级、全仓生效。
+- 逻辑有独立失败路径，需要 `message(FATAL_ERROR)` 把非法输入挡在 configure 阶段。
+
+一次性三行属性、仍在频繁变化的实验片段、只服务一个 target 的私有设置不抽；等第二次真实复用再抽。
+
+## 文件与命名
+
+- 一个文件放一组语义相近的函数，不为每个函数建单独文件；文件过大或出现无关职责时再拆。
+- 文件名用 UpperCamelCase，按职责命名，例如 `CompileSettings.cmake`、`LinkSettings.cmake`。
+- 函数名用 `<ModuleName>_` 加 PascalCase，例如 `CompileSettings_SetCxxStandard`；前缀取模块文件名的原样大小写，复制到工程后不改名。
+- 工程自己新增、不准备回流的函数才用项目前缀加 snake_case。
+- 模块开头写 `include_guard(GLOBAL)`，避免重复导入时重定义函数。
+
+## 导入
+
+根 `CMakeLists.txt` 在 `project()` 之后、`add_subdirectory()` 之前追加一次 `CMAKE_MODULE_PATH`，再 `include()` 需要的模块。子目录只调用函数，不再次导入。
+
+## 契约
+
+- 公开函数上方写中文 `#` 契约：一句功能、空行、边界，再用 `:param` / `:keyword` 标参数；不写 `#[[.rst:` 与 `.. command::`。
+- 完整写法见 `references/cmake.md`；签名留在 `function()` 那一行。
+- 签名、警告等级与错误消息以 `assets/cmake/` 和 `references/modules.md` 为准；本步不复制第二份。
+- 普通函数只改传入 target 的属性，不写全局变量、不读环境变量、不下载依赖；唯一例外是 `LinkSettings_FetchGoogleTest`，只在测试需要时调用。
+- 先校验 target、可见性与标准，再调用 `target_*` 或 `set_target_properties`；失败用 `FATAL_ERROR`，消息带函数名与非法值。
+
+## 退出
+
+模块可被根文件导入且函数签名稳定后，进 `steps/03-check.md` 跑 configure、构建与数据库核对。排版、2 空格与注释形态按 `references/cmake.md`。

package/skills/configuring-cmake/steps/03-check.md

@@ -0,0 +1,39 @@
+# 第 3 步：通过检查
+
+## 产出
+
+一次干净的 configure、一次构建、一份与 `environment.json` 一致的编译数据库。检查只回答「target 契约是否成立」，完整的格式化、静态检查、CTest 与运行由 `building-cpp` 的通过检查接手。
+
+## 命令
+
+```bash
+cmake -S . -B build/clang -G Ninja \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_CXX_COMPILER=clang++ \
+  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+cmake --build build/clang
+```
+
+GCC 模式把目录和编译器换成 `build/gcc`、`g++`。每次检查都重新 configure，不依赖上一次缓存；同一构建目录只放同一编译器的配置。
+
+## 核对项
+
+- **target 图**：`app` 链接库，库的公共 include 用 `PUBLIC`；没有把 `main()` 编进库。
+- **标准**：读 `build/clang/compile_commands.json` 的最后一个 `-std=`，必须与 `environment.json` 的 `standard` 一致，不能是 `gnu++NN` 或更高默认标准。
+- **没有全局污染**：全仓搜索 `include_directories`、`add_definitions`、`CMAKE_CXX_FLAGS`、`file(GLOB`，命中就回第 1 步。
+- **模块导入**：根 `CMakeLists.txt` 只导入一次；函数名与文件名可追溯；删除旧模块后没有残留 `include()`。
+- **排版**：`CMakeLists.txt` 与 `*.cmake` 无 tab、2 空格缩进、UTF-8 无 BOM、LF；抽查 80 列以上的行是否有必要。
+- **产物位置**：可执行文件在 `build/<compiler>/bin`，库在 `build/<compiler>/lib`；源码目录没有新增构建产物。
+
+## 失败分流
+
+| 现象 | 回哪一步 |
+| --- | --- |
+| 找不到 target、链接失败、include 路径不对 | 第 1 步 |
+| 目标标准没有生效、`-std` 与声明不一致 | 第 1 步，必要时重读 `references/cxx-standard.md` |
+| 函数参数没校验、模块重复导入、旧模块残留 | 第 2 步 |
+| 只是 clang-format、clang-tidy、CTest 或运行失败 | 转 `building-cpp` 的通过检查 |
+
+## 边界
+
+本步不替代 `building-cpp`：不安装工具链，不改 `running-build.sh`，不跑 `clang-tidy` 或 CTest。检查通过的判据是 configure 与构建成功、数据库标准正确、结构规则无命中；完整的工具链检查仍由 `building-cpp` 的通过检查给出。

package/skills/developing-cpp/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 ## 适用场景
 
-管 `.h` / `.hpp` / `.cpp` / `.cc` 里换一台机器也不会改的内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。文件槽位与守卫以 `references/file-template.md` 为准；排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文采用 C++ Core Guidelines 的 Error handling，作为开发阶段的源码指导；它不进入插件运行时。`CMakeLists.txt`、`cmake/`、`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 只开 `building-cpp`。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `building-cpp` 的定构建，把文件写进 CMake，再决定是否定工具配置，最后通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
+管 `.h` / `.hpp` / `.cpp` / `.cc` 里换一台机器也不会改的内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。文件槽位与守卫以 `references/file-template.md` 为准；排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文采用 C++ Core Guidelines 的 Error handling，作为开发阶段的源码指导；它不进入插件运行时。`CMakeLists.txt` 与 `cmake/` 开 `configuring-cmake`；`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 开 `building-cpp`。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `configuring-cmake` 把文件写进 CMake，再开 `building-cpp` 定工具配置并通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
 
 存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令。没有项目技能时门禁不会放出本技能，不要猜项目约定。