@chengzhao-dev/dsh-cpp-workflow 0.1.1 → 0.2.0

package/skills/building-cpp/references/environment.md

@@ -1,20 +1,22 @@
 # 环境组合
 
-环境是**声明**，不是探测结果。项目技能 `cpp-workflow-project` 的 `environment.json` 写清楚三个轴；构建规则、工具配置和检查都按这个声明执行。声明为空或组合非法时，先修声明，不要靠猜。
+环境是**声明**，不是探测结果。项目技能 `cpp-workflow-project` 的 `environment.json` 写清楚三个环境轴和一个语言标准；构建规则、工具配置和检查都按这个声明执行。声明为空或组合非法时，先修声明，不要靠猜。
 
-## 三个轴
+## 四个轴
 
 | 轴 | 取值 | 说明 |
 | --- | --- | --- |
 | `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在的系统 |
 | `build_host` | `native` / `wsl` | 编译在哪执行；`wsl` 只对 `host=windows` 合法 |
 | `compiler` | `clang` / `gcc` | 一次只配一个；不支持 MSVC、clang-cl，也不把 C 编译器单独作为一个轴 |
+| `standard` | `c++11` / `c++14` / `c++17` / `c++20` / `c++23` | 一个工程一个标准；新工程默认 `c++23`，旧声明缺字段时也按 `c++23` 处理 |
 
 ```json
 {
   "host": "windows",
   "build_host": "wsl",
-  "compiler": "clang"
+  "compiler": "clang",
+  "standard": "c++23"
 }
 ```
 
@@ -24,8 +26,6 @@
 | --- | --- | --- | --- | --- |
 | windows | wsl | clang | 合法 | 是（WSL 内跑 POSIX 脚本） |
 | windows | wsl | gcc | 合法 | 是 |
-| windows | native | clang | 合法 | 否：缺 POSIX 壳（本版无 PowerShell 脚本） |
-| windows | native | gcc | 合法 | 否：缺 POSIX 壳（本版无 PowerShell 脚本） |
 | linux | native | clang | 合法 | 是 |
 | linux | native | gcc | 合法 | 是 |
 | macos | native | clang | 合法 | 是 |
@@ -33,12 +33,13 @@
 
 非法组合：
 
-- `host` 不是三个值之一，或 `build_host` / `compiler` 不是两个值之一。
-- 三个轴任意为空、缺失、写成数组或同时写两个值。
+- `host`、`build_host`、`compiler` 不是各自允许的值，或 `standard` 不在 `c++11`–`c++23` 内。
+- 三个环境轴任意为空、缺失、写成数组或同时写两个值；`standard` 缺失或为空时按默认 `c++23` 处理并给出提示（视为声明升级，不覆盖已写出的 `c++11`–`c++20`）。
 - `host=linux` / `host=macos` + `build_host=wsl`。
+- `host=windows` + `build_host=native`：本版本不支持，静态校验直接返回失败。
 - `compiler=msvc`、`compiler=clang-cl`、`compiler=c`。
 
-`windows` + `native` 是合法声明，但本版本**没有** PowerShell 构建脚本。`--live` 会明确报告「缺的是 shell，不是编译器」；不要为了让它通过把 `build_host` 改成 `wsl`，也不要临时写一个脚本伪装成已支持。
+`windows` + `native` 不再作为「合法但不能构建」的声明保留。声明校验直接返回 `ok: false`，`issues` 只有一句「本版本不能在 Windows 原生壳里构建」；不要建议改 WSL，也不要临时写 PowerShell 脚本伪装成已支持。
 
 ## 工具角色
 
@@ -56,11 +57,12 @@
 
 ## 版本与能力
 
-- **C++20**：编译器必须支持 `-std=c++20`；CMake ≥ 3.20（C++20 标准属性从 3.12 起可用）。
-- **clang-format / clang-tidy**：≥ 16。`BreakAfterAttributes` 在 16 才支持，15 及以下没有该选项。
+- **标准**：新工程默认 C++23，可声明 `c++11`–`c++23`；编译器必须支持对应的 `-std=c++NN`。CMake ≥ 3.20；C++11/14 的 `cxx_std_*` 需要 CMake ≥ 3.8，但本工作流统一按 3.20 起步。`CXX_STANDARD_REQUIRED ON` 防止标准 decay；C++23 的库设施（如 `std::print`）以实际编译器/标准库为准。
+- **clang-format / clang-tidy**：≥ 16。这是本工作流的工具基线；低于该版本时检查器报告具体角色和版本。
 - **clang 模式同版本**：`clang++`、`clang-format`、`clang-tidy`、`clangd` 必须是同一 LLVM 主版本。混装 17 的 clangd 与 18 的 clang-format 会出现诊断与格式化不一致。Apple Clang 也按这条核对；若工具版本对不上，报告的是具体角色和版本，不要为了通过而改声明。
-- **gcc 模式**：检查器不拿 GCC 的主版本去比 Clang 工具；`clang-format` / `clang-tidy` 仍要 ≥ 16，`clangd` 只要求可用。`g++` 必须是真的 GCC，不能是 Apple clang 的别名。GCC 需要自带 C++20 `<format>` 的标准库；版本过旧时先升级工具链，不要改检查器绕过。
+- **gcc 模式**：检查器不拿 GCC 的主版本去比 Clang 工具；`clang-format` / `clang-tidy` 仍要 ≥ 16，`clangd` 只要求可用。`g++` 必须是真的 GCC，不能是 Apple clang 的别名。GCC 需要自带 C++23 `<print>` / `std::expected` 的标准库；版本过旧时先升级工具链，或把项目标准降到实际可用的档位，不要改检查器绕过。
 - **Apple Clang**：`/usr/bin/clang++` 通常是 Apple Clang；clangd 需能经 `xcrun` 找到 SDK。不要混用 Homebrew LLVM 与 Xcode 资源目录，也不要把 Homebrew 路径写死。
+- **调试器**：VSCode 的 `CMake: Debug` 由 CMake Tools 调 C/C++ 扩展的 `cppdbg`；clang 模式要 `lldb`，gcc 模式要 `gdb`。调试器不在 `--live` 的编译器角色核对里，也不写进 `environment.json`；缺它时是调试启动失败，不是构建声明失败。
 
 ## 构建目录
 
@@ -76,7 +78,7 @@
 
 `<skill-dir>/scripts/checking-environment.mjs` 做两件事：
 
-1. **静态**（默认）：读 `environment.json`，检查三个轴和组合。轴为空或组合非法时以退出码 2 结束，不查找任何可执行文件。
+1. **静态**（默认）：读 `environment.json`，检查三个环境轴、`standard` 和组合。轴为空或组合非法时以退出码 2 结束，不查找任何可执行文件。
 2. **活动**（`--live`）：先做声明校验，再核对当前进程是否在声明的 build host 上，然后查 PATH、角色和版本。声明本身不合法时仍以退出码 2 结束；声明合法但活动核对失败时以退出码 3 结束。
 
 ```bash
@@ -89,7 +91,7 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
 约束：
 
 - 只读：不安装、不下载、不改 PATH、不写项目文件。
-- `--live` 在 `host=windows` + `build_host=native` 下直接报告「缺 POSIX 壳；本版没有 PowerShell 构建脚本」，不继续找编译器。
+- `--live` 在 `host=windows` + `build_host=native` 下不会继续：声明校验已经失败，错误是「本版本不能在 Windows 原生壳里构建」。
 - WSL 模式要求当前进程在 WSL 内（`WSL_DISTRO_NAME` / `WSL_INTEROP` 或 `/proc/version` 含 Microsoft）；只在 Linux 上但不在 WSL 时失败。
 - macOS 上声明 `compiler=gcc` 时，`g++ --version` 若显示 Apple clang，按「不是真正的 GCC」失败。
 - 没有 `--live` 时不做任何 PATH 探测，CI 和 Windows 开发机都能做声明校验。
@@ -102,3 +104,5 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
 | 2 | 声明缺失、轴为空、组合非法 |
 | 3 | 活动校验失败：不在声明的 build host、角色缺失、版本不符 |
 | 1 | 脚本自身错误：参数错误或内部异常 |
+
+各标准对应的编译器、库设施和工具档位见 [standards/README.md](standards/README.md)。

package/skills/building-cpp/references/linking.md

@@ -15,25 +15,25 @@
 - 链接：把多个目标文件和库合并，解析符号引用。`undefined reference` 在这一步失败。
 - 加载：程序启动时由动态加载器找到共享库；`error while loading shared libraries` 在这一步失败。
 
-`g++ -c file.cpp` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
+`g++ -c file.cc` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
 
 ## 头文件、声明与定义
 
 - `#include` 是文本替换，不是模块导入；头文件只放声明、`inline` 定义、模板和 `constexpr` 定义。
-- 普通函数的定义放 `.cpp`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
-- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cpp`。
+- 普通函数的定义放 `.cc`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
+- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cc`。
 - 只用到声明时不要包含完整定义；前置声明可以减少编译依赖，但不能替代需要完整类型的场景（继承、成员对象、按值返回）。
-- 每个头文件自包含：单独编译一个只包含该头文件的 `.cpp` 应通过。用 `#pragma once` 防止重复包含。
+- 每个头文件自包含：单独编译一个只包含该头文件的 `.cc` 应通过。用路径式 `#define` 守卫防止重复包含，不用 `#pragma once`。
 
 ## `undefined reference` 分诊
 
 | 现象 | 常见原因 | 修法 |
 | --- | --- | --- |
-| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cpp` 没加入 target | 补定义，或把源文件加入 `target_sources` |
+| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cc` 没加入 target | 补定义，或把源文件加入 `target_sources` |
 | 只有某个平台失败 | 条件编译把定义排除了 | 检查宏和平台分支，保证每个平台都有定义 |
 | 第三方库符号缺失 | 没链接库，或库顺序不对 | `target_link_libraries` 加库；CMake 会处理顺序 |
 | C++ 符号被当成 C 符号 | 头文件缺少 `extern \"C\"` | C 接口头加 `extern \"C\"`，C++ 调用方也可见 |
-| 模板成员未定义 | 模板定义在 `.cpp`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
+| 模板成员未定义 | 模板定义在 `.cc`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
 | 静态库中的目标文件没被拉入 | 链接器只取被引用符号所在的目标文件 | 确认符号确实被引用，或改用对象库/共享库 |
 
 先看链接器报的完整符号名和来源文件，不要只看第一行。

package/skills/building-cpp/references/standards/README.md

@@ -0,0 +1,165 @@
+# 语言标准档案
+
+本工作流默认 **C++23**，但一个工程只选一个 `standard`，不为同一份源码承诺“同时兼容 C++11–C++23”。标准是项目级事实，写在 `.agents/skills/cpp-workflow-project/environment.json`。
+
+每个标准单独一个目录：`c++11/`、`c++14/`、`c++17/`、`c++20/`、`c++23/`。目录里放这一档自己的编译器下限、语言/库设施、CMake 片段和工具映射；模板仍然只有一套公共骨架，靠 `__cplusplus` 条件选择实现，不复制五份模板。
+
+Google C++ Style Guide 上游仍写 “target C++20”，本工作流默认 C++23 是一处明确偏离；Google 的排版、命名、头文件和异常之外的规则不变。异常政策仍按 [exceptions.md](../../../developing-cpp/references/exceptions.md)。
+
+## 选择标准
+
+| 标准 | 目录 | 一句话 |
+| --- | --- | --- |
+| C++11 | [c++11/README.md](c++11/README.md) | 老工具链、老库仍要维护时的最低档 |
+| C++14 | [c++14/README.md](c++14/README.md) | 需要 `make_unique`、泛型 lambda，但还不想上 C++17 |
+| C++17 | [c++17/README.md](c++17/README.md) | 需要 `string_view`、`optional`、`if constexpr` 的稳定基线 |
+| C++20 | [c++20/README.md](c++20/README.md) | 需要 concepts、ranges、`std::format` 的现代基线 |
+| C++23 | [c++23/README.md](c++23/README.md) | 本工作流默认；需要 `print`、`expected` 等设施时选它 |
+
+新工程写 `c++23`；已有工程按现有 `CMakeLists.txt` 和编译器能力选，不为了“统一”擅自升降。降档前先读对应目录的“不能假设”和“降档要改什么”。
+
+## 三个规划粒度
+
+| 粒度 | 先看 | 产出 |
+| --- | --- | --- |
+| 项目 | 本页选择表、编译器/库门槛 | `environment.json` 的 `standard`，以及“为什么选这档” |
+| target | 该档的 `cmake-snippet.cmake` | `cxx_std_*`、`CXX_STANDARD`、`CXX_STANDARD_REQUIRED`、`CXX_EXTENSIONS` |
+| 代码/工具 | 该档 README 的“能用/不能假设/降档” | 设施替换、`.clang-format` 档位、`.clangd` 不写 `-std` |
+| 验证 | 本页验证矩阵、`scripts/checking-standard-matrix.sh` | configure/build/CTest 和 `compile_commands.json` 的精确 `-std` |
+
+每个标准目录都按这四层写；不要只在项目层改 `standard`，却在 target 层留着 C++23 的 `cxx_std_23`。
+
+## 共用矩阵
+
+| `standard` | CMake meta-feature | `CXX_STANDARD` | `__cplusplus` | clang-format 21/22 | 模板实用下限（含标准库设施） |
+| --- | --- | --- | --- | --- | --- |
+| `c++11` | `cxx_std_11` | 11 | `201103L` | `c++11` | GCC 4.8 / Clang 3.4 |
+| `c++14` | `cxx_std_14` | 14 | `201402L` | `c++14` | GCC 5 / Clang 3.4 |
+| `c++17` | `cxx_std_17` | 17 | `201703L` | `c++17` | GCC 7 / Clang 5 |
+| `c++20` | `cxx_std_20` | 20 | `202002L` | `c++20` | GCC 13 / Clang 16（`std::format`） |
+| `c++23` | `cxx_std_23` | 23 | `202302L` | `Latest` | GCC 13 / Clang 17（模板只用 `std::format`） |
+
+“语言核心最低编译器”只保证语法和核心库；标准库设施要单独看：
+
+| 设施 | 标准 | 额外门槛 |
+| --- | --- | --- |
+| `std::string_view`、`std::optional`、`std::variant`、`if constexpr` | C++17 | 随语言核心 |
+| `std::format` | C++20 | libstdc++ 13+；libc++ 14+（特性宏到 19 才稳定） |
+| `std::print`、`std::expected`、`std::stacktrace` | C++23 | `std::print`：libstdc++ 14+、libc++ 19+；`std::expected` 随各库 C++23 实现；`std::stacktrace` 还要链接对应库 |
+
+Clang/GCC 的 “Partial” 状态意味着 C++23 不是全量实现。用到具体设施前，先查：
+
+- [GCC C++ status](https://gcc.gnu.org/projects/cxx-status.html)
+- [Clang C++ status](https://clang.llvm.org/cxx_status.html)
+- [cppreference C++23 compiler support](https://en.cppreference.com/w/cpp/compiler_support/23)
+
+## 共用规则
+
+### CMake
+
+每个 target 同时写 meta-feature 和精确属性；片段见各标准目录的 `cmake-snippet.cmake`，把 target 名换成实际 target：
+
+```cmake
+target_compile_features(app PRIVATE cxx_std_23)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 23
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)
+```
+
+- `cxx_std_23` 是“至少”，会向依赖它的 target 传播。
+- `CXX_STANDARD` 是请求值；`CXX_STANDARD_REQUIRED ON` 防止编译器不支持时静默 decay。
+- `CXX_EXTENSIONS OFF` 把 `-std=gnu++23` 收成 `-std=c++23`。
+- configure 后读 `compile_commands.json` 的最后一个 `-std=`；必须是 `-std=c++NN`，不能是 `gnu++NN`。
+- CMake 最低 3.20（模板统一要求）；只单独使用低档片段时，C++11/14 的 `cxx_std_*` meta-feature 最低 3.8，C++20 为 3.12。C++23 的 `CXX_STANDARD 23` 自 3.20 才有。
+
+### clang-format
+
+clang-format 21/22 的 `Standard` 只到 `c++20`。映射：
+
+| 声明 | 配置 |
+| --- | --- |
+| `c++11`–`c++20` | 对应 `Standard: c++NN` |
+| `c++23` | `Standard: Latest`（21/22 没有 `c++23`） |
+| `c++26`（未来） | 工具支持时写 `c++26`，否则 `Latest` |
+
+不要为了“看起来精确”写 `c++23`；clang-format 21 会报 `unknown enumerated scalar` 并退出 1。
+
+### clangd
+
+`.clangd` **不写 `-std`**。clangd 从 `compile_commands.json` 读标准；写死 `-std=c++20` 会把 C++23 工程降级，表现为 `<print>` 不存在、`if consteval` 解析失败。
+
+只保留：
+
+```yaml
+CompileFlags:
+  CompilationDatabase: build/clang
+```
+
+切换编译器时改目录；没有数据库时先回到定构建生成。
+
+### clang-tidy
+
+`.clang-tidy` 不写标准，标准来自编译数据库。检查项保持 Google 基线：
+
+```yaml
+Checks: '-*, google-*, readability-identifier-naming'
+WarningsAsErrors: '*'
+FormatStyle: file
+```
+
+低标准工程不要为了通过检查去打开 `cppcoreguidelines-*` 整包；那会把 C++ Core Guidelines 的现代写法带进 C++11 代码。
+
+### 标准库
+
+默认用系统默认标准库。需要 libc++ 时，在 CMake 工具链文件或 target 选项里显式写：
+
+```cmake
+target_compile_options(app PRIVATE -stdlib=libc++)
+target_link_options(app PRIVATE -stdlib=libc++)
+```
+
+不要只写进某个人的 `.clangd` 或 shell 脚本；换机器后不可复现。
+
+## 降档时改什么
+
+默认模板按 `__cplusplus` 条件使用 `std::format`；选低标准仍不是只改一个数字：
+
+| 从默认 C++23 降到 | 必须处理 |
+| --- | --- |
+| `c++20` | `std::print` → `std::format` + `std::cout`；`std::expected` → `std::optional`/结果类型 |
+| `c++17` | 再去掉 `std::format`，用 `std::ostringstream`；去掉 `std::span`、`std::bit_cast` |
+| `c++14` | 去掉 `std::string_view`、`[[nodiscard]]`、结构化绑定、`if constexpr`、`std::optional` |
+| `c++11` | 再去掉通用 lambda、`std::make_unique`、`std::index_sequence`、`constexpr` 放宽用法 |
+
+每个标准目录里的“不能假设”和“降档要改什么”是该档的检查清单；模板只保证自身能构建，不替项目代码做兼容层。
+
+## 验证矩阵
+
+| 标准 | configure | build | run | compile_commands `-std` | clang-format | clangd |
+| --- | --- | --- | --- | --- | --- | --- |
+| `c++11` | 必测 | 必测 | 必测 | `c++11` | `c++11` | 读 DB |
+| `c++14` | 必测 | 必测 | 必测 | `c++14` | `c++14` | 读 DB |
+| `c++17` | 必测 | 必测 | 必测 | `c++17` | `c++17` | 读 DB |
+| `c++20` | 必测 | 必测 | 必测 | `c++20` | `c++20` | 读 DB |
+| `c++23` | 必测 | 必测 | 必测 | `c++23` | `Latest` | 读 DB |
+
+本仓库在 WSL（clang 21.1.8、CMake 4.2.3、Ninja 1.13.2）上跑过四套模板 × 五档共 20 个构建：single、multi、static-library、shared-library 全部 configure/build/CTest 通过，`compile_commands.json` 都得到精确的 `-std=c++11/14/17/20/23`。模板用 `__cplusplus` 条件选择 `std::format` 或字符串拼接，默认仍交付 C++23。可复现脚本：[checking-standard-matrix.sh](../../../../scripts/checking-standard-matrix.sh)。
+
+## 新增标准
+
+增加 C++26 或更高标准时，不复制模板，按这个顺序做：
+
+1. 新建 `standards/c++26/`，写 `README.md`，复制对应档的 `cmake-snippet.cmake` 并改数字。
+2. 更新本页矩阵和 `checking-environment.mjs` 的 `STANDARDS`。
+3. 确认 CMake 的 `CXX_STANDARD 26`、clang-format 的 `Standard` 能力、编译器/标准库门槛。
+4. 在四套模板 × 新档上跑 configure/build/CTest，并在 `compile_commands.json` 核对 `-std=c++26`。
+5. 只在新档稳定后改默认；默认变更属于发布说明里要写清的破坏性变化。
+
+## 相关文件
+
+- [environment.md](../environment.md)：四轴声明与校验。
+- [cmake.md](../cmake.md)：CMake 形状与排版。
+- [static-analysis.md](../static-analysis.md)：clang-format / clang-tidy / clangd 分工。
+- [01-build.md](../../steps/01-build.md)：定构建步骤。

package/skills/building-cpp/references/standards/c++11/README.md

@@ -0,0 +1,50 @@
+# C++11 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++11` |
+| CMake meta-feature | `cxx_std_11` |
+| `CXX_STANDARD` | `11` |
+| `__cplusplus` | `201103L` |
+| clang-format 21/22 | `Standard: c++11` |
+| 模板实用下限 | GCC 4.8 / Clang 3.4 |
+
+## 最重要的三件事
+
+1. 代码只用 C++11 子集：没有 `std::make_unique`、通用 lambda、`std::string_view`、`std::optional`、`if constexpr`。
+2. CMake 同时写 `cxx_std_11` 和 `CXX_STANDARD 11`，并开 `CXX_STANDARD_REQUIRED ON`；只写 `cxx_std_11` 可能被更高默认标准满足。
+3. 验证时读 `compile_commands.json`，确认实际是 `-std=c++11`，不是 `gnu++11` 或更高的 `-std`。
+
+## 本档能用
+
+- `auto`、范围 `for`、lambda、右值引用与移动语义。
+- `std::unique_ptr`、`std::shared_ptr`、`std::thread`、`std::chrono`。
+- `enum class`、`override` / `final`、变参模板、`constexpr` 的受限用法。
+- `std::array`、`std::unordered_map` / `unordered_set`。
+
+## 本档不能假设
+
+- 没有 `std::make_unique`、泛型 lambda、变量模板、返回类型推导。
+- 没有 `std::string_view`、`std::optional`、`std::variant`、`if constexpr`、结构化绑定。
+- 没有 `[[nodiscard]]`、`std::filesystem`、`std::format`、`std::print`。
+- 不要用 C++14 的放宽 `constexpr` 写循环或多语句函数。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。新建工程仍建议 CMake ≥ 3.20；低版本工具链只影响 `CXX_STANDARD` 的可用性，不影响本工作流的目录约定。
+
+## 工具
+
+- `.clang-format`：`Standard: c++11`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：仍用 Google 基线；不要打开 `cppcoreguidelines-*` 整包。
+
+## 降档/升级
+
+这是最低档，没有“再降”的路径。从 C++14 降到这里时，先去掉 `std::make_unique`、泛型 lambda、返回类型推导和变量模板；`std::unique_ptr<T>(new T(...))` 只作为过渡，不要在新代码里扩散。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++11`，不能是 `gnu++11`。模板的 `__cplusplus` 分支在 C++11 下应走字符串拼接实现。

package/skills/building-cpp/references/standards/c++11/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++11：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_11)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 11
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)

package/skills/building-cpp/references/standards/c++14/README.md

@@ -0,0 +1,48 @@
+# C++14 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++14` |
+| CMake meta-feature | `cxx_std_14` |
+| `CXX_STANDARD` | `14` |
+| `__cplusplus` | `201402L` |
+| clang-format 21/22 | `Standard: c++14` |
+| 模板实用下限 | GCC 5 / Clang 3.4 |
+
+## 最重要的三件事
+
+1. C++14 只多出 `std::make_unique`、泛型 lambda、放宽的 `constexpr` 等；不要顺手用 C++17 的 `string_view`/`optional`。
+2. `std::make_unique` 是这一档最常用的替换点，但不要把 C++11 的 `std::unique_ptr(new T)` 直接当成跨档写法。
+3. 同样用 `CXX_STANDARD 14` + `REQUIRED ON` 锁定模式，并检查 `compile_commands.json` 是 `-std=c++14`。
+
+## 本档能用
+
+- C++11 的全部内容。
+- `std::make_unique`、泛型 lambda、变量模板、返回类型推导。
+- 二进制字面量、数字分隔符、放宽的 `constexpr`、`std::integer_sequence`。
+
+## 本档不能假设
+
+- 没有 `std::string_view`、`std::optional`、`std::variant`、`if constexpr`、结构化绑定。
+- 没有 `[[nodiscard]]`、`std::filesystem`、`std::format`、`std::print`。
+- 不要把结构化绑定或 `if constexpr` 写进 C++14 代码再靠编译器扩展通过。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。
+
+## 工具
+
+- `.clang-format`：`Standard: c++14`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：仍用 Google 基线；命名规则不要引入 C++17 属性。
+
+## 降档/升级
+
+从 C++17 降到这里时，把 `string_view` 改成 `const std::string&`，把 `optional` 改成 `bool` + 输出参数或项目结果类型，把 `if constexpr` 改成标签分派或重载。升级到 C++17 后也不要立刻把公共接口全改成 `string_view`，先看调用方生命周期。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++14`。模板在 C++14 下应走字符串拼接实现。

package/skills/building-cpp/references/standards/c++14/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++14：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_14)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 14
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)

package/skills/building-cpp/references/standards/c++17/README.md

@@ -0,0 +1,49 @@
+# C++17 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++17` |
+| CMake meta-feature | `cxx_std_17` |
+| `CXX_STANDARD` | `17` |
+| `__cplusplus` | `201703L` |
+| clang-format 21/22 | `Standard: c++17` |
+| 模板实用下限 | GCC 7 / Clang 5（语言核心） |
+
+## 最重要的三件事
+
+1. `std::string_view`/`std::optional`/`std::variant`/`if constexpr` 是这一档的主力；它们不能出现在 C++11/14 档案里。
+2. 还没有 `std::format`；字符串拼接/`ostringstream` 仍是这一档的默认写法。
+3. `std::filesystem` 在旧 GCC 上要额外链接 `stdc++fs`，先查工具链再写进 CMake。
+
+## 本档能用
+
+- C++14 的全部内容。
+- `std::string_view`、`std::optional`、`std::variant`、`std::any`。
+- `if constexpr`、结构化绑定、`[[nodiscard]]`、内联变量、嵌套命名空间。
+- `std::filesystem`、并行算法（库实现和链接方式另看）。
+
+## 本档不能假设
+
+- 没有 concepts、ranges、`std::format`、`std::span`、`std::bit_cast`。
+- 没有 `std::print`、`std::expected`、`std::stacktrace`。
+- `std::filesystem` 在 GCC 8 需要额外链接 `stdc++fs`，GCC 9 起才稳定；不要把“语言核心达标”当成文件系统库也达标。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。用到 `std::filesystem` 且工具链较老时，在 target 上补 `stdc++fs`，不要全局加链接选项。
+
+## 工具
+
+- `.clang-format`：`Standard: c++17`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：Google 基线；`[[nodiscard]]` 可以开始用于公共查询。
+
+## 降档/升级
+
+从 C++20 降到这里时，把 concepts 改成 `enable_if`/重载，把 ranges 改成迭代器算法，把 `std::format` 改成 `std::ostringstream`。升级到 C++20 后先确认 `std::format` 的库门槛（libstdc++ 13+ / libc++ 14+），不要只看编译器版本。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++17`。模板在 C++17 下仍走字符串拼接实现。

package/skills/building-cpp/references/standards/c++17/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++17：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_17)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 17
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)

package/skills/building-cpp/references/standards/c++20/README.md

@@ -0,0 +1,49 @@
+# C++20 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++20` |
+| CMake meta-feature | `cxx_std_20` |
+| `CXX_STANDARD` | `20` |
+| `__cplusplus` | `202002L` |
+| clang-format 21/22 | `Standard: c++20` |
+| 模板实用下限 | GCC 13 / Clang 16（`std::format`） |
+
+## 最重要的三件事
+
+1. `std::format` 是这一档的库门槛：libstdc++ 13+，libc++ 14+（特性宏到 19 才稳定），不是有 `-std=c++20` 就自动可用。
+2. concepts/ranges/`std::span`/`std::bit_cast` 可以用；`std::print`、`std::expected`、`if consteval` 仍不能假设。
+3. 模板在 `__cplusplus >= 202002L` 时切到 `std::format`；降回 C++17 时必须把它换回 `std::ostringstream`。
+
+## 本档能用
+
+- C++17 的全部内容。
+- concepts、requires、ranges、`std::span`、`std::bit_cast`、`std::source_location`。
+- `std::format`、协程、`std::jthread`、三路比较。
+- 模块语法（工具链支持不完整，模板不使用）。
+
+## 本档不能假设
+
+- 没有 `std::print`、`std::expected`、`std::stacktrace`、`if consteval`、显式对象参数。
+- `std::format` 不只看语言核心：libstdc++ 13+；libc++ 14+ 实现完成，但特性宏到 19 才稳定。
+- 模块、协程的构建支持因编译器/构建系统而异；模板不依赖它们。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。模板从这一档开始会在 `__cplusplus >= 202002L` 时使用 `std::format`，此前用字符串拼接。
+
+## 工具
+
+- `.clang-format`：`Standard: c++20`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：Google 基线；不要为了 concepts 打开一整族非 Google 检查。
+
+## 降档/升级
+
+从 C++23 降到这里时，把 `std::print` 改成 `std::format` + `std::cout`，把 `std::expected` 改成 `std::optional` 或项目结果类型，去掉 `if consteval`。升级到 C++23 后仍要逐项确认库实现，不要因为 `-std=c++23` 通过就假定 `print`/`stacktrace` 可用。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++20`。模板在 C++20 下应走 `std::format` 分支。

package/skills/building-cpp/references/standards/c++20/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++20：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_20)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 20
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)

package/skills/building-cpp/references/standards/c++23/README.md

@@ -0,0 +1,50 @@
+# C++23 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++23` |
+| CMake meta-feature | `cxx_std_23` |
+| `CXX_STANDARD` | `23` |
+| `__cplusplus` | `202302L` |
+| clang-format 21/22 | `Standard: Latest` |
+| 模板实用下限 | GCC 13 / Clang 17（模板只用 `std::format`） |
+
+## 最重要的三件事
+
+1. C++23 在 GCC/Clang 上仍是 Partial；`std::print` 要 libstdc++ 14+/libc++ 19+，`std::stacktrace` 还要链接库。
+2. clang-format 21/22 不认识 `c++23`，配置写 `Standard: Latest`；`.clangd` 不写 `-std`，否则会把编译数据库降回 C++20。
+3. 模板默认 23，但模板只强依赖 `std::format`；不要因为默认 23 就在公共头里用 `std::expected`/`std::print`，先确认所有 target 和库门槛。
+
+## 本档能用
+
+- C++20 的全部内容。
+- `std::print` / `std::println`、`std::expected`、`std::stacktrace`。
+- `if consteval`、显式对象参数（deducing this）、`std::mdspan`、`std::flat_map`。
+- ranges 的 C++23 增补（工具链实现为准）。
+
+## 本档不能假设
+
+- C++23 在 GCC/Clang 上仍是 Partial：具体设施要查编译器状态页，不能只看 `-std=c++23`。
+- `std::print` 的库门槛是 libstdc++ 14+ / libc++ 19+；`std::stacktrace` 还要链接对应库，链接失败不是语法错误。
+- `std::expected` 的 monadic 接口、`std::flat_map` 等设施在旧标准库上可能缺失。
+- 模板只用 `std::format`，不会因为默认 C++23 就强依赖 `print`/`stacktrace`。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。默认模板的 `cxx_std_23` 和 `CXX_STANDARD 23` 必须与 `environment.json` 的 `standard` 一致。
+
+## 工具
+
+- `.clang-format`：`Standard: Latest`（21/22 不接受 `c++23`；`Latest` 按工具支持的最高标准解析）。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读；写死 `-std=c++20` 会让 `<print>` 和 `if consteval` 解析失败。
+- `.clang-tidy`：Google 基线；不要因为 C++23 就打开 `cppcoreguidelines-*` 整包。
+
+## 降档/升级
+
+从 C++23 降到 C++20 见 [C++20 档案](../c++20/README.md)。升级到 C++26 前先确认 CMake 3.25+、编译器/标准库支持、clang-format 的 `c++26` 枚举；新增目录流程见[标准索引](../README.md#新增标准)。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++23`。模板在 C++23 下走 `std::format` 分支；若使用 `print`/`stacktrace`，另做链接测试。

package/skills/building-cpp/references/standards/c++23/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++23：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_23)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 23
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)