From 1d5304e7b6620a6a6c1bf6953951fec22e782a29 Mon Sep 17 00:00:00 2001 From: csh Date: Wed, 15 Jul 2026 16:31:15 +0800 Subject: [PATCH] :wrench: chore(cpp): align conventions and formatter config --- docs/cpp/code_style.md | 16 +++++++--------- docs/cpp/toolchain.md | 28 +++++++++++++++++----------- rulesets/cpp/index.md | 15 ++++++++++----- templates/cpp/.clang-format | 4 ++-- 4 files changed, 36 insertions(+), 27 deletions(-) diff --git a/docs/cpp/code_style.md b/docs/cpp/code_style.md index 07234505..3e80d571 100644 --- a/docs/cpp/code_style.md +++ b/docs/cpp/code_style.md @@ -36,23 +36,21 @@ cpp/ `export module my_project.net.http;` - 避免在同一模块内混用“头文件边界”和“模块边界”造成可见性混乱；对外 API 优先通过 `export` 暴露。 -- 工程约束：新增/删除/重命名 `.cppm`（或变更 - `export module ...`）时，必须同步更新构建系统的模块清单（例如 CMake 的 - `target_sources(FILE_SET CXX_MODULES ...)`），否则容易出现“本地能编、CI/他人机器不能编”的漂移。 +- 工程约束：新增、删除、移动、重命名 `.cppm` 或改变其所属 target 时，必须同步更新 + CMake `FILE_SET CXX_MODULES`。变更 `export module ...` 名称时更新全部 `import`；仅当文件 + 路径或所属 target 同时变化时才更新 file-set。 ## 2. 格式（Formatting） ### 2.1 clang-format（必选） -- 本仓库/标准默认：`clang-format` + Google 风格。 +- 本仓库格式以 `templates/cpp/.clang-format` 为准；其中的配置属于对 Google 风格的项目级覆盖。 - 建议在项目根目录提供 `.clang-format` 并纳入 CI/本地钩子。 -- 列宽建议与本 Playbook 其他语言保持一致：默认 100（可按项目调整，但要全仓一致）。 - 模板：`templates/cpp/.clang-format`（参考 `tsl-devkit/lsp-server/.clang-format` 并做了最小化泛化）。 ### 2.2 通用格式约定 -- 缩进使用空格，单次缩进 4 空格（Google）。 - 不做“空格对齐排版”（避免 diff 噪音），用缩进表达结构。 - 头文件 include 顺序建议（从上到下）： 1. 本文件对应头（如有） @@ -73,8 +71,8 @@ cpp/ ## 5. Windows 支持 -- 本规范假设 **不做原生 Windows 开发环境支持**；Windows 产物通过 - **Linux 上的 Clang 交叉编译工具链**获得（工具链路径/三元组等由项目的 Conan - profile 或 toolchain 文件定义）。 +- Windows 目标必须在原生 Windows 环境完成构建和测试，并固定经过验证的编译器、SDK 与运行时。 +- Linux + Clang 交叉编译仅作为附加验证，不能替代原生 Windows 验证；项目必须明确记录目标三元组、 + ABI 与运行时。 - 如需条件编译，优先用标准特性检测与最小化条件编译，并写清动机（例如 ABI/平台差异）。 - 对路径、换行、编码、大小写敏感等行为要明确约束并在文档/测试中覆盖。 diff --git a/docs/cpp/toolchain.md b/docs/cpp/toolchain.md index 728fa59c..94bc03a0 100644 --- a/docs/cpp/toolchain.md +++ b/docs/cpp/toolchain.md @@ -7,18 +7,23 @@ ### 1.1 编译器与标准 - C++ 标准：C++23（含 Modules） -- 编译器： - - 目标平台：Windows（通过 Linux 交叉编译） +- 目标平台：Windows +- 原生验证： + - 主机平台：Windows + - 工具链：项目固定并验证的 MSVC 或 clang-cl 版本 + - 要求：必须完成构建和测试 +- 附加交叉验证： - 主机平台：Linux - - 工具链：`clang <版本>`（交叉编译；具体 clang 可执行路径由 Conan - profile 配置） + - 工具链：`clang <版本>`（具体可执行路径由 Conan profile 配置） - 目标三元组（示例）：`x86_64-w64-mingw32` / `aarch64-w64-mingw32` + - 明确记录目标 ABI 与运行时；交叉验证不能替代原生 Windows 验证 ### 1.2 构建系统 - CMake：`>= 4.0` - 生成器： - - Linux：`Ninja` + - Windows 原生：项目固定的 `Ninja` 或 Visual Studio 生成器 + - Linux 交叉编译：`Ninja` ### 1.3 依赖管理（Conan，推荐） @@ -49,7 +54,8 @@ ### 2.1 最小构建（必须能跑） - Conan 生成（推荐，示例）： - - `CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing` + - Windows 原生：`conan install . -pr:b= -pr:h= -of build/windows-native --build=missing` + - Linux 交叉验证：`CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing` - 配置（示例）： - `cmake --preset conan-release` - 构建（示例）： @@ -57,8 +63,9 @@ ### 2.2 运行冒烟（建议） -- `build/ ` -- 或：`cmake --build build -t run_smoke`（如项目提供自定义 target） +- Windows 原生环境必须运行项目测试，例如： + `ctest --preset conan-release --output-on-failure`。 +- Linux 交叉编译可以执行额外的编译期检查；未在目标运行时执行的产物不能代替原生测试。 ### 2.3 格式化检查（建议） @@ -86,6 +93,5 @@ - `CMakeUserPresets.json` 不是强制标准，仅作为一种推荐落地方式（模板见 `templates/cpp/CMakeUserPresets.json`）。 -不在本 Playbook 中强制规定工具链分发方式（例如某种特定打包形态）；只要求把交叉编译所需的 -`compiler_executables`、triplet、system_name 等写进 Conan -profile，保证命令可复现。 +不在本 Playbook 中强制规定工具链分发方式（例如某种特定打包形态）。原生与交叉编译 profile +必须记录所需的 `compiler_executables`、triplet、system_name、ABI 与运行时，保证命令可复现。 diff --git a/rulesets/cpp/index.md b/rulesets/cpp/index.md index 5f736918..503cc74c 100644 --- a/rulesets/cpp/index.md +++ b/rulesets/cpp/index.md @@ -16,11 +16,16 @@ ## C++ 核心约定（不可违反） -- 语言标准：C++23；优先使用 Modules；避免裸指针、`new/delete`、C 风格字符串 -- 代码风格：Google C++ Style Guide；使用项目 `.clang-format`；头文件保护用 `#pragma once` -- 命名规范：文件 `lower_with_under.cpp/.h/.cppm`；类型 `CapWords`；函数/变量 `lower_with_under`；常量 `kCapWords`；成员 `lower_with_under_`；命名空间 `lower_with_under` -- Modules 工程：模块名点分层 `lower_snake_case`；接口文件 `.cppm`；修改 `export module` 必须更新 CMake module file-set -- 构建与依赖：Conan 需提供 `conan-release`/`conan-debug`；`conan install` + `cmake --preset ...`；Windows 通过 Linux + Clang 交叉编译验证 +- 使用 C++23，关闭编译器扩展，并固定经过验证的 CMake、编译器和 Conan 2 版本。 +- 新增的项目内部组件优先使用 Modules；第三方库、C API、平台接口及工具链不支持的场景允许使用头文件。 +- 使用 RAII 管理资源；禁止拥有所有权的裸指针以及直接使用 `new/delete`。非空借用使用引用，可空借用允许使用 `T*`。 +- 内部字符串和缓冲区优先使用 `std::string`、`std::string_view` 和 `std::span`；C 风格接口仅限互操作边界。 +- 以项目 `.clang-format` 和命名规则为准；相对 Google C++ Style Guide 的差异属于明确的项目级覆盖。 +- 头文件使用 `#pragma once`。 +- 模块名采用点分 `lower_snake_case`，接口文件使用 `.cppm`。 +- 新增、删除、移动模块接口文件或改变所属 target 时，更新 CMake `FILE_SET CXX_MODULES`；模块改名时更新全部 `import`。 +- 提供明确的 Conan build/host profiles 和可复现的 Release/Debug preset，不依赖生成器的隐式命名。 +- Windows 必须进行原生 Windows 构建和测试；Linux + Clang 交叉编译仅作为附加验证，并明确目标 ABI 和运行时。 ## 权威来源 diff --git a/templates/cpp/.clang-format b/templates/cpp/.clang-format index 6f94096c..c1928399 100644 --- a/templates/cpp/.clang-format +++ b/templates/cpp/.clang-format @@ -4,6 +4,7 @@ BasedOnStyle: Google # Keep consistent with the repo-wide 100 char guidance (adjust per-project if needed). ColumnLimit: 100 +IndentWidth: 4 AccessModifierOffset: -4 AlignEscapedNewlines: Left @@ -37,11 +38,10 @@ IncludeCategories: KeepEmptyLinesAtTheStartOfBlocks: false MacroBlockBegin: "BEGIN_TEST_METHOD_PROPERTIES|BEGIN_MODULE|BEGIN_TEST_CLASS|BEGIN_TEST_METHOD" MacroBlockEnd: "END_TEST_METHOD_PROPERTIES|END_MODULE|END_TEST_CLASS|END_TEST_METHOD" -NamespaceIndentation: All +NamespaceIndentation: None PointerAlignment: Left ReflowComments: false SortIncludes: false SpaceAfterTemplateKeyword: false SpacesInAngles: false SpacesInContainerLiterals: false -