@chengzhao-dev/dsh-cpp-workflow 0.0.0-stage → 0.1.1

package/skills/building-cpp/assets/templates/projects/static-library/CMakeLists.txt

@@ -0,0 +1,18 @@
+cmake_minimum_required(VERSION 3.20)
+project({{PROJECT_NAME}} 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")
+
+enable_testing()
+
+add_subdirectory(greeting)
+
+add_executable(app src/main.cpp)
+target_compile_features(app PRIVATE cxx_std_20)
+set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
+target_link_libraries(app PRIVATE greeting)
+target_compile_options(app PRIVATE -Wall -Wextra -Werror)
+
+add_test(NAME app_smoke COMMAND app)

package/skills/building-cpp/assets/templates/projects/static-library/greeting/CMakeLists.txt

@@ -0,0 +1,5 @@
+add_library(greeting STATIC src/greeting.cpp)
+target_include_directories(greeting PUBLIC include)
+target_compile_features(greeting PUBLIC cxx_std_20)
+set_target_properties(greeting PROPERTIES CXX_EXTENSIONS OFF)
+target_compile_options(greeting PRIVATE -Wall -Wextra -Werror -Wold-style-cast -Wshadow)

package/skills/building-cpp/assets/templates/projects/static-library/greeting/include/greeting.h

@@ -0,0 +1,10 @@
+#pragma once
+
+#include <string>
+#include <string_view>
+
+namespace greeting {
+
+[[nodiscard]] std::string MakeGreeting(std::string_view name);
+
+}  // namespace greeting

package/skills/building-cpp/assets/templates/projects/static-library/greeting/src/greeting.cpp

@@ -0,0 +1,13 @@
+#include "greeting.h"
+
+#include <format>
+#include <string>
+#include <string_view>
+
+namespace greeting {
+
+std::string MakeGreeting(std::string_view name) {
+  return std::format("Hello, {}!", name);
+}
+
+}  // namespace greeting

package/skills/building-cpp/assets/templates/projects/static-library/src/main.cpp

@@ -0,0 +1,8 @@
+#include <iostream>
+
+#include "greeting.h"
+
+int main() {
+  std::cout << greeting::MakeGreeting("C++20") << '\n';
+  return 0;
+}

package/skills/building-cpp/examples/cmake.md

@@ -0,0 +1,150 @@
+# 正反例：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")
+
+add_library(greeting STATIC greeting/src/greeting.cpp)
+target_include_directories(greeting PUBLIC greeting/include)
+target_compile_features(greeting PUBLIC cxx_std_20)
+set_target_properties(greeting PROPERTIES CXX_EXTENSIONS OFF)
+target_compile_options(greeting PRIVATE -Wall -Wextra -Werror)
+
+add_executable(app src/main.cpp)
+target_compile_features(app PRIVATE cxx_std_20)
+set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
+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
+# 没开导出
+```
+
+```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
+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()
+```
+
+从 `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>/` 下。

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

@@ -0,0 +1,125 @@
+# 正反例：环境组合
+
+## 合法声明
+
+```json
+{
+  "host": "windows",
+  "build_host": "wsl",
+  "compiler": "clang"
+}
+```
+
+在 WSL 内执行 `running-build.sh clang`；构建目录 `build/clang`。
+
+```json
+{
+  "host": "linux",
+  "build_host": "native",
+  "compiler": "gcc"
+}
+```
+
+在 Linux 上执行 `running-build.sh gcc`；构建目录 `build/gcc`。
+
+## 非法声明
+
+**轴为空**：
+
+```json
+{
+  "host": "linux",
+  "build_host": "",
+  "compiler": "gcc"
+}
+```
+
+声明校验以退出码 2 失败，不查找 `g++`。先让用户填 `build_host`。
+
+**组合非法**：
+
+```json
+{
+  "host": "linux",
+  "build_host": "wsl",
+  "compiler": "clang"
+}
+```
+
+WSL 只对 `host=windows` 合法；不要通过改 `host` 来绕过，先确认工程到底跑在哪。
+
+**同时写两个编译器**：
+
+```json
+{
+  "host": "linux",
+  "build_host": "native",
+  "compiler": ["clang", "gcc"]
+}
+```
+
+一个 configure 只允许一个编译器；拆成两次声明或两个工程。
+
+## Windows 原生
+
+```json
+{
+  "host": "windows",
+  "build_host": "native",
+  "compiler": "clang"
+}
+```
+
+声明合法，但本版本没有 PowerShell 构建脚本。`--live` 输出类似：
+
+```text
+声明合法，但 Windows 原生构建缺少 POSIX 构建脚本；缺的是 shell，不是编译器。
+```
+
+不要把 `build_host` 改成 `wsl` 来「让它过」；要么补脚本，要么换到 WSL 并更新声明。
+
+## GCC 模式不比较 GCC 主版本
+
+```text
+g++ 14.1.0
+clang-format 18.1.8
+clang-tidy 18.1.8
+clangd 18.1.8
+```
+
+通过：检查器只要求 `g++` 是真的 GCC，`clang-format` / `clang-tidy` ≥ 16，`clangd` 可用。不要拿 GCC 的主版本去要求 Clang 工具，也不要因为版本号不同就换成一套不存在的 `gcc-format`。若 GCC 的标准库太旧、`<format>` 不可用，升级工具链，而不是改检查器。
+
+## macOS 的 `g++` 别名
+
+```json
+{
+  "host": "macos",
+  "build_host": "native",
+  "compiler": "gcc"
+}
+```
+
+`/usr/bin/g++` 实际是 Apple clang 的别名；`--live` 应报告「声明的 g++ 实际是 Apple clang」。安装真正的 GCC（如 Homebrew `gcc`）并把 `g++` 指向它，或把声明改成 `compiler=clang`。
+
+## 版本不一致
+
+```text
+clang++ 18.1.8
+clang-format 16.0.6
+clang-tidy 16.0.6
+clangd 16.0.6
+```
+
+clang 模式要求四者同主版本；这里 18 与 16 不一致，`--live` 失败。统一到同一 LLVM 发行版，不要只升级编译器。
+
+## 声明校验与活动校验
+
+```bash
+# CI / Windows 开发机：只读声明，不需要工具链
+node scripts/checking-environment.mjs --project .
+
+# build host 上：核对构建宿主、PATH 和版本
+node scripts/checking-environment.mjs --project . --live
+```
+
+不带 `--live` 时永远不探测 PATH；不要把活动校验塞进每次构建，构建脚本已经隐含了工具存在性。

package/skills/building-cpp/examples/tooling.md

@@ -0,0 +1,155 @@
+# 正反例：工具配置
+
+## `query-driver` 放错位置
+
+**差**：
+
+```yaml
+# .clangd
+CompileFlags:
+  CompilationDatabase: build/clang
+  Add:
+    - --query-driver=/usr/bin/clang++
+```
+
+`--query-driver` 是 clangd 的命令行参数，不是 `.clangd` 的 YAML 键；写在这里不会生效。
+
+**好**：
+
+```yaml
+# .clangd
+CompileFlags:
+  CompilationDatabase: build/clang
+```
+
+```jsonc
+// .vscode/settings.json
+{
+  "clangd.arguments": [
+    "--query-driver=/usr/bin/clang++",
+    "--header-insertion=never",
+    "--background-index"
+  ]
+}
+```
+
+## 编译数据库指错目录
+
+**差**：
+
+```yaml
+CompileFlags:
+  CompilationDatabase: build/clang   # 项目已切到 GCC，这里仍读 clang 的数据库
+```
+
+**好**：
+
+```yaml
+CompileFlags:
+  CompilationDatabase: build/gcc
+```
+
+`.clangd` 的目录必须与 `environment.json` 的 `compiler` 一致；默认 clang 用 `build/clang`，切换 GCC 时改成 `build/gcc`，不要两套配置并存。
+
+## 配置文件堆策略头
+
+**差**：
+
+```yaml
+# 本项目遵循 Google C++ Style Guide，详见 docs/...
+# 所有检查必须通过，禁止 NOLINT，禁止 ...
+ColumnLimit: 100
+```
+
+**好**：
+
+```yaml
+# 100 列：模板和格式化串在 80 列下换行过碎。
+ColumnLimit: 100
+```
+
+配置注释解释取值，不重复策略；策略在技能文档里。
+
+## 整族关闭检查
+
+**差**：
+
+```yaml
+Checks: >
+  -*,
+  bugprone-*
+```
+
+只留一族，其他全关，且没有理由。
+
+**好**：
+
+```yaml
+Checks: >
+  -*,
+  clang-analyzer-*,
+  bugprone-*,
+  cppcoreguidelines-*,
+  google-*,
+  modernize-*,
+  performance-*,
+  readability-*
+CheckOptions:
+  # 团队用 100 列，tidy 的列宽判断跟随 clang-format。
+  readability-identifier-length.MinimumVariableNameLength: 2
+```
+
+保留主体；关闭项逐条写理由。
+
+## tidy 扫描系统头
+
+**差**：
+
+```bash
+clang-tidy -p build/clang --system-headers src/main.cpp
+```
+
+系统头也参与诊断，出现大量第三方告警。
+
+**好**：
+
+```bash
+clang-tidy -p build/clang --header-filter="^$(pwd -P)/(include|src)/" \
+  --warnings-as-errors='*' src/main.cpp
+```
+
+`--header-filter` 只列项目顶层目录，避免把第三方头纳入；系统头默认排除。工程有别的顶层目录时按实际替换。
+
+## 构建脚本里自动格式化
+
+**差**：
+
+```bash
+clang-format -i src/*.cpp   # 构建时悄悄改源码
+```
+
+**好**：
+
+```bash
+clang-format --dry-run --Werror "${sources[@]}"   # 只检查
+```
+
+需要自动修复时单独运行 `clang-format -i`，由人确认 diff。
+
+## 版本混装
+
+**差**：
+
+```text
+clang++ 18, clang-format 17, clangd 16
+```
+
+格式化与诊断不同版本，CI 与本地结果不一致。
+
+**好**：
+
+```text
+clang++ 18.1.8, clang-format 18.1.8, clang-tidy 18.1.8, clangd 18.1.8
+```
+
+同主版本；`--live` 会核对。Apple Clang 与 Homebrew 工具不同版本时，仍按同一 LLVM 主版本要求处理，不要强行降级或改声明绕过。

package/skills/building-cpp/references/build-script.md

@@ -0,0 +1,63 @@
+# 构建脚本
+
+`assets/templates/projects/common/running-build.sh` 是 POSIX build-host 脚本，适用于 Linux、macOS 和 Windows + WSL。Windows 原生组合（`build_host=native`）本版本没有 PowerShell 版本；这是已知缺口，不是编译器问题。
+
+## 用法
+
+```bash
+./running-build.sh clang
+./running-build.sh gcc
+```
+
+- 参数是编译器名，只接受 `clang` / `gcc`；省略时默认 `clang`。
+- 脚本以自身所在目录为工程根；把它放在工程根，从其他目录调用时会先 `cd` 到脚本目录。
+- 构建目录由参数决定：`build/clang` 或 `build/gcc`；不要用环境变量临时改目录。
+- 脚本不安装依赖、不下载工具、不改 PATH；缺工具时让命令失败，由 `building-cpp` 的通过检查分诊。
+
+## 结构
+
+1. **shebang + 文件头**：说明用途、支持的 build host、参数。
+2. **严格模式与目录**：`set -euo pipefail`；`cd "$(dirname "$0")"`；`readonly BUILD_DIR`、`readonly APP_NAME="app"`。
+3. **输出辅助**：`header()` 打印阶段名，`err()` 打印到 stderr；`trap ERR` 打印失败命令。
+4. **configure**：每次运行都重新 configure，不复用缓存；传 `-G Ninja`、`-DCMAKE_BUILD_TYPE=Debug`、`-DCMAKE_C_COMPILER`、`-DCMAKE_CXX_COMPILER`、`-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`。C 与 C++ 使用同一套编译器；没有 C 语言的工程会忽略 C 编译器设置。
+5. **build**：`cmake --build "$BUILD_DIR"`。
+6. **编译数据库链接**：先 `rm -f build/compile_commands.json`，再 `ln -s "${COMPILER}/compile_commands.json" build/compile_commands.json`；不用 `ln -n`，它在 BSD/macOS 上不可移植。
+7. **format**：收集项目源码，`clang-format --dry-run --Werror`；没有源文件时跳过。
+8. **tidy**：`clang-tidy -p "$BUILD_DIR" --warnings-as-errors='*'` 扫描项目源文件；`--header-filter` 由脚本从项目根和顶层目录生成，绝对路径和相对路径都只放行项目自身头文件。不要用 clang-tidy 19 才加入的 `--exclude-header-filter`，最低支持版本是 16。
+9. **test**：`ctest --test-dir "$BUILD_DIR" --output-on-failure`；没有测试时 CTest 成功。
+10. **run**：`(cd "$BUILD_DIR/bin" && "./$APP_NAME")`；共享库的运行时路径由定构建的 CMake RPATH 负责，不在脚本里设全局 `LD_LIBRARY_PATH`。
+
+最后一行是 `main "$@"`；函数定义在 `main()` 之前，`set` / `readonly` 在最前。
+
+## 关键约束
+
+- 只用 POSIX shell + Bash 数组；不要依赖 `mapfile`（macOS 自带 Bash 3.2 没有）。
+- 路径含空格时全部加引号；`find -print0` 配 `read -d ''`。
+- `set -u` 下空数组展开会报错；先判 `${#sources[@]}` 再传给工具。
+- 不把 `clang-format -i` 放进脚本；检查阶段只读。
+- 不在脚本里设全局 `LD_LIBRARY_PATH`；共享库的运行时路径由 CMake 的 RPATH 设置。
+- 不 `sudo`、不 `apt install`、不 `pip install`。
+- 失败时保留原始命令输出；不要在脚本里 `2>/dev/null` 吞掉诊断。
+- 脚本自身用 `bash -n` 检查语法；文件权限保持可执行。
+
+## 失败分诊
+
+| 输出 | 先看 | 回到 |
+| --- | --- | --- |
+| `CMake Error ... CXX compiler` | `environment.json`、`--live` | `building-cpp` 的定构建 / 通过检查 |
+| `ninja: error: ... missing and no known rule` | 源文件是否在 CMake 中列出 | 定构建 |
+| `fatal error: ... No such file` | `target_include_directories` | 定构建 |
+| `undefined reference` | `target_link_libraries`、库 target 名 | 定构建 |
+| `clang-format` 差异 | 源码排版 | 定工具配置 |
+| `clang-tidy` 命名/类型诊断 | 声明或实现 | `developing-cpp` 的定声明 / 定实现 |
+| `CTest` 失败 | 测试断言、行为句 | `developing-cpp` 的定行为 / 定实现 |
+| 运行时报找不到 `.so` | RPATH / `LD_LIBRARY_PATH` | 定构建 |
+
+## 验收
+
+- `bash -n running-build.sh` 通过。
+- 在声明的 build host 上，`./running-build.sh clang` 与 `./running-build.sh gcc` 都能从 configure 走到 run。
+- 从工程根直接 `./build/clang/bin/app` 能启动（共享库场景由 RPATH 保证）。
+- 切换编译器后 `build/compile_commands.json` 指向新数据库。
+- 调用者的 `LD_LIBRARY_PATH` 在脚本结束后不变。
+- Windows 原生：没有脚本时明确报告缺口，不伪造通过。