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

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/{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)：社区警告模块的注释与命名参数写法。