🔧 chore(cpp): align conventions and formatter config
This commit is contained in:
@@ -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/平台差异）。
|
||||
- 对路径、换行、编码、大小写敏感等行为要明确约束并在文档/测试中覆盖。
|
||||
|
||||
+17
-11
@@ -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=<windows-build-profile> -pr:h=<windows-host-profile> -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/<app_or_tool> <args>`
|
||||
- 或：`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 与运行时，保证命令可复现。
|
||||
|
||||
+10
-5
@@ -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 和运行时。
|
||||
|
||||
## 权威来源
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user