🔧 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 与运行时，保证命令可复现。
|
||||
|
||||
Reference in New Issue
Block a user