Skip to content

Commit af81a5f

Browse files
LessUpLessUp
committed
docs: add GitBook integration and modernize documentation
- Add .gitbook.yaml configuration for GitBook synchronization - Add CONTRIBUTING.zh.md with Chinese contribution guidelines - Add SUMMARY.md for GitBook table of contents structure - Add docs/en/gitbook-sync.md and docs/zh/gitbook-sync.md guides - Update README.md and README.zh.md with improved badges and GitBook links - Add changelog entry for 2026-03-06 - Add unit tests for modern C++ examples module - Update examples/03-modern-cpp source files with improvements - Update build system and test configurations for new test module - Enhance integration tests and property tests for better coverage
1 parent 5beadac commit af81a5f

20 files changed

Lines changed: 500 additions & 32 deletions

‎.gitbook.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
root: ./
2+
structure:
3+
readme: README.md
4+
summary: SUMMARY.md

‎CONTRIBUTING.zh.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# 参与贡献到 C++ 高性能指南
2+
3+
感谢你对本项目的关注！本文档介绍如何为本项目贡献内容。
4+
5+
## 开始之前
6+
7+
1. Fork 本仓库
8+
2. 克隆你的 Fork：
9+
```bash
10+
git clone https://github.com/<your-username>/cpp-high-performance-guide.git
11+
```
12+
3. 创建功能分支：
13+
```bash
14+
git checkout -b feature/your-feature-name
15+
```
16+
17+
## 构建与测试
18+
19+
```bash
20+
# Debug 构建并启用测试
21+
cmake --preset=debug
22+
cmake --build build/debug
23+
ctest --preset=debug
24+
25+
# Release 构建并运行基准测试
26+
cmake --preset=release
27+
cmake --build build/release
28+
ctest --preset=release
29+
```
30+
31+
## 代码风格
32+
33+
- 遵循项目根目录中的 `.clang-format` 配置
34+
- 提交前格式化代码：
35+
```bash
36+
find examples tests benchmarks -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i
37+
```
38+
- 头文件统一使用 `#pragma once`
39+
- 代码放在 `hpc::` 命名空间层级下
40+
41+
## 添加新的示例模块
42+
43+
1. 在 `examples/` 下创建新目录，遵循命名规则：`XX-topic-name/`
44+
2. 使用统一结构：
45+
```
46+
examples/XX-topic-name/
47+
├── src/ # 带 demo main() 的源码文件
48+
├── bench/ # Google Benchmark 文件
49+
├── include/ # 可复用头文件（可选）
50+
├── CMakeLists.txt # 使用 ExampleTemplate.cmake 中的 hpc_add_example()
51+
└── README.md # 模块文档
52+
```
53+
3. 在 `examples/CMakeLists.txt` 中注册子目录
54+
4. 在 `tests/` 下补充对应测试
55+
56+
## 测试要求
57+
58+
提交 Pull Request 之前，请确保：
59+
60+
1. **所有测试通过：**
61+
```bash
62+
cmake --preset=debug && cmake --build build/debug && ctest --preset=debug
63+
```
64+
65+
2. **没有 AddressSanitizer 错误：**
66+
```bash
67+
cmake --preset=asan && cmake --build build/asan && ctest --preset=asan
68+
```
69+
70+
3. **没有 ThreadSanitizer 错误**（并发代码尤其重要）：
71+
```bash
72+
cmake --preset=tsan && cmake --build build/tsan && ctest --preset=tsan
73+
```
74+
75+
4. **没有 UndefinedBehaviorSanitizer 错误：**
76+
```bash
77+
cmake --preset=ubsan && cmake --build build/ubsan && ctest --preset=ubsan
78+
```
79+
80+
## Commit Message 建议
81+
82+
请使用清晰、可描述的提交信息：
83+
- `feat: add matrix multiplication SIMD example`
84+
- `fix: resolve false sharing in concurrent counter`
85+
- `docs: update learning path with new module`
86+
- `bench: add parameterized benchmark for prefetch distance`
87+
- `test: add property tests for lock-free queue`
88+
89+
## Pull Request 流程
90+
91+
1. 确保你的分支与 `main` 保持同步
92+
2. 确保所有 CI 检查通过
93+
3. 在 PR 描述中清楚说明本次修改的内容和原因
94+
4. 如有相关 issue，请在 PR 中引用
95+
96+
## License
97+
98+
通过提交贡献，你同意你的贡献将以 MIT License 进行许可。

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# C++ High Performance Computing Optimization Guide
22

3-
[![Build](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/build.yml/badge.svg)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/build.yml)
4-
[![Benchmarks](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/benchmark.yml/badge.svg)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/benchmark.yml)
5-
[![Sanitizers](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/sanitizers.yml/badge.svg)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/sanitizers.yml)
3+
[中文版本](README.zh.md) | [GitBook Sync Guide](docs/en/gitbook-sync.md)
4+
5+
[![Build](https://img.shields.io/github/actions/workflow/status/LessUp/cpp-high-performance-guide/build.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=Build)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/build.yml)
6+
[![Benchmarks](https://img.shields.io/github/actions/workflow/status/LessUp/cpp-high-performance-guide/benchmark.yml?branch=main&style=for-the-badge&logo=speedtest&logoColor=white&label=Benchmarks)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/benchmark.yml)
7+
[![Sanitizers](https://img.shields.io/github/actions/workflow/status/LessUp/cpp-high-performance-guide/sanitizers.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=Sanitizers)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/sanitizers.yml)
68

79
A comprehensive collection of high-performance computing optimization examples and best practices for modern C++20.
810

@@ -138,6 +140,7 @@ firefox flamegraph.svg
138140

139141
- [Learning Path](docs/en/learning-path.md) - Recommended order for studying examples
140142
- [Profiling Guide](docs/en/profiling-guide.md) - How to profile and analyze performance
143+
- [GitBook Sync Guide](docs/en/gitbook-sync.md) - Connect this repository to GitBook for online reading
141144

142145
## Contributing
143146

‎README.zh.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# C++ 高性能计算优化指南
22

3-
[![Build](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/build.yml/badge.svg)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/build.yml)
4-
[![Benchmarks](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/benchmark.yml/badge.svg)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/benchmark.yml)
5-
[![Sanitizers](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/sanitizers.yml/badge.svg)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/sanitizers.yml)
3+
[English Version](README.md) | [GitBook 接入指南](docs/zh/gitbook-sync.md)
4+
5+
[![Build](https://img.shields.io/github/actions/workflow/status/LessUp/cpp-high-performance-guide/build.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=Build)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/build.yml)
6+
[![Benchmarks](https://img.shields.io/github/actions/workflow/status/LessUp/cpp-high-performance-guide/benchmark.yml?branch=main&style=for-the-badge&logo=speedtest&logoColor=white&label=Benchmarks)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/benchmark.yml)
7+
[![Sanitizers](https://img.shields.io/github/actions/workflow/status/LessUp/cpp-high-performance-guide/sanitizers.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=Sanitizers)](https://github.com/LessUp/cpp-high-performance-guide/actions/workflows/sanitizers.yml)
68

79
面向现代 C++20 的高性能计算优化示例与最佳实践合集。
810

@@ -138,6 +140,7 @@ firefox flamegraph.svg
138140

139141
- [学习路径](docs/zh/learning-path.md) - 推荐的学习顺序
140142
- [性能分析指南](docs/zh/profiling-guide.md) - 如何进行性能剖析与分析
143+
- [GitBook 接入指南](docs/zh/gitbook-sync.md) - 将当前仓库同步到 GitBook 以供在线阅读
141144

142145
## 贡献
143146

‎SUMMARY.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Table of contents
2+
3+
* [C++ High Performance Computing Optimization Guide](README.md)
4+
* [中文版本](README.zh.md)
5+
* [Contributing](CONTRIBUTING.md)
6+
* [参与贡献](CONTRIBUTING.zh.md)
7+
* [Learning Path](docs/en/learning-path.md)
8+
* [Profiling Guide](docs/en/profiling-guide.md)
9+
* [GitBook Sync Guide](docs/en/gitbook-sync.md)
10+
* [学习路径](docs/zh/learning-path.md)
11+
* [性能分析指南](docs/zh/profiling-guide.md)
12+
* [GitBook 接入指南](docs/zh/gitbook-sync.md)
13+
* [01 - Modern CMake](examples/01-cmake-modern/README.md)
14+
* [02 - Memory & Cache Optimization](examples/02-memory-cache/README.md)
15+
* [03 - Modern C++ Features](examples/03-modern-cpp/README.md)
16+
* [04 - SIMD Vectorization](examples/04-simd-vectorization/README.md)
17+
* [05 - Concurrency](examples/05-concurrency/README.md)

‎changelog/2026-03-06.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# 2026-03-06
2+
3+
## 变更
4+
5+
### 代码与测试修复
6+
- 修复 `tests/property/benchmark_properties.cpp` 的跨平台临时文件问题：
7+
- 用 `std::filesystem::temp_directory_path()` 替代硬编码 `/tmp/`。
8+
- 新增统一的临时文件路径生成函数。
9+
- 调整 property 测试入口位置：
10+
- `tests/property/concurrency_properties.cpp`
11+
- `tests/property/simd_properties.cpp`
12+
- 将 `main()` 移动到文件末尾，避免测试定义出现在入口函数之后。
13+
- 补强 `tests/integration/build_system_test.py`：
14+
- 在原有目录级命令检查基础上，新增 target-based CMake 使用检查。
15+
- 新增示例模块结构完整性检查（`CMakeLists.txt`、`README.md`、`src/`）。
16+
17+
### 现代 C++ 模块补齐
18+
- 新增 `tests/unit/modern_cpp/` 目录。
19+
- 新增 `tests/unit/modern_cpp/CMakeLists.txt`。
20+
- 新增 `tests/unit/modern_cpp/modern_cpp_examples_test.cpp`，覆盖：
21+
- 编译期 factorial / hash / prime 工具
22+
- move semantics 中的拷贝/移动行为
23+
- `reserve()` 对分配次数的影响
24+
- ranges 结果与原始循环的一致性
25+
- 更新 `tests/unit/CMakeLists.txt`，接入 `modern_cpp` 单测。
26+
- 为 `examples/03-modern-cpp/` 下 4 个示例源文件添加 `HPC_TEST_MODE` 宏保护，方便单测复用实现而不引入重复 `main()`。
27+
28+
### 构建系统改进
29+
- 更新 `examples/CMakeLists.txt`：
30+
- 为 5 个示例模块新增独立构建开关。
31+
- 支持按模块启用/禁用示例子目录。
32+
33+
### 文档与 README 优化
34+
- 新增 `CONTRIBUTING.zh.md` 中文贡献指南。
35+
- 优化 `README.md`：
36+
- 保持英文为默认入口。
37+
- 新增中文跳转链接。
38+
- 将 Build / Benchmarks / Sanitizers 徽章替换为更醒目的 `for-the-badge` 样式。
39+
- 新增 GitBook 同步指南入口。
40+
- 优化 `README.zh.md`：
41+
- 新增英文跳转链接。
42+
- 同步优化 3 个 GitHub Actions 徽章。
43+
- 新增 GitBook 接入指南入口。
44+
45+
### GitBook 在线阅读准备
46+
- 新增 `.gitbook.yaml`：
47+
- 显式声明首页为 `README.md`。
48+
- 显式声明目录为 `SUMMARY.md`。
49+
- 新增 `SUMMARY.md`，为 GitBook 提供稳定目录结构。
50+
- 新增双语 GitBook 接入说明：
51+
- `docs/en/gitbook-sync.md`
52+
- `docs/zh/gitbook-sync.md`
53+
- 仓库现已具备通过 GitBook Git Sync 方式在线阅读的结构基础。
54+
55+
### Windsurf MCP 配置修复
56+
- 修复 `c:\Users\shuai\.codeium\windsurf\mcp_config.json`：
57+
- 启用 `context7`
58+
- 保留并规范 `fetch`
59+
- 规范 `filesystem`
60+
- 为 `git` 增加仓库范围限制
61+
- 将 GitHub MCP 统一为官方 `@modelcontextprotocol/server-github` 形式
62+
- 在写入前自动备份原文件为 `mcp_config.json.bak`
63+
64+
## 原因
65+
66+
- 消除 Windows 环境下的测试路径兼容性问题。
67+
- 提升 property 测试文件结构可维护性。
68+
- 补齐 `modern_cpp` 模块的单元测试覆盖和中文贡献文档。
69+
- 让 README 的默认语言、双语跳转和 CI 状态展示更清晰。
70+
- 让仓库能够以 GitBook Git Sync 的方式更顺畅地接入在线文档空间。
71+
- 让 Windsurf 的 MCP 配置更接近官方推荐写法，并提高可用性。
72+
73+
## 后续建议
74+
75+
- 建议尽快轮换当前 GitHub Personal Access Token，避免继续使用已暴露在配置文件中的凭证。
76+
- 建议在 Windsurf 中刷新 MCP 列表，并逐项检查 `context7`、`fetch`、`filesystem`、`git`、`github` 是否成功加载。
77+
- 建议在 GitBook 后台选择 `GitHub -> GitBook` 执行首次同步，以当前仓库 Markdown 内容作为在线文档来源。

‎docs/en/gitbook-sync.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# GitBook Sync Guide
2+
3+
This repository is prepared for GitBook online reading using Git Sync.
4+
5+
## Recommended Setup
6+
7+
1. Create or open a GitBook space.
8+
2. In the space header, choose `Configure`.
9+
3. Select `GitHub Sync`.
10+
4. Authenticate your GitHub account.
11+
5. Install the GitBook GitHub App for the account or organization that owns this repository.
12+
6. Select the repository `LessUp/cpp-high-performance-guide`.
13+
7. Select the branch you want to sync, usually `main`.
14+
8. For the initial import, choose `GitHub -> GitBook` if the repository already contains the documentation.
15+
16+
## Repository Configuration
17+
18+
This repository already includes the following files for GitBook:
19+
20+
- `.gitbook.yaml`
21+
- `SUMMARY.md`
22+
- `README.md`
23+
- Markdown documentation under `docs/`
24+
25+
## Content Structure
26+
27+
GitBook will use:
28+
29+
- `README.md` as the first page
30+
- `SUMMARY.md` as the table of contents
31+
32+
The `.gitbook.yaml` file explicitly defines this structure.
33+
34+
## Notes
35+
36+
- Do not edit the readme entry page from the GitBook UI when Git Sync is enabled. Keep `README.md` managed from the repository.
37+
- If you do not manually customize the table of contents in GitBook, `SUMMARY.md` will be used directly.
38+
- If you later move your docs under another root folder, update `.gitbook.yaml` accordingly.

‎docs/zh/gitbook-sync.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# GitBook 接入指南
2+
3+
当前仓库已经为通过 Git Sync 接入 GitBook 做好了在线阅读准备。
4+
5+
## 推荐接入方式
6+
7+
1. 创建或打开一个 GitBook Space。
8+
2. 在 Space 顶部选择 `Configure`。
9+
3. 选择 `GitHub Sync`。
10+
4. 完成 GitHub 账户授权。
11+
5. 为当前仓库所属账号或组织安装 GitBook GitHub App。
12+
6. 选择仓库 `LessUp/cpp-high-performance-guide`。
13+
7. 选择需要同步的分支，通常是 `main`。
14+
8. 如果仓库里已经有 Markdown 文档，首次同步建议选择 `GitHub -> GitBook`。
15+
16+
## 仓库内已准备的文件
17+
18+
当前仓库已经包含以下 GitBook 需要识别的文件：
19+
20+
- `.gitbook.yaml`
21+
- `SUMMARY.md`
22+
- `README.md`
23+
- `docs/` 下的 Markdown 文档
24+
25+
## 内容结构
26+
27+
GitBook 将使用：
28+
29+
- `README.md` 作为首页
30+
- `SUMMARY.md` 作为目录导航
31+
32+
这些入口已经在 `.gitbook.yaml` 中显式声明。
33+
34+
## 注意事项
35+
36+
- 启用 Git Sync 后，不要优先在 GitBook UI 中修改首页 readme，避免与仓库内的 `README.md` 冲突。
37+
- 如果你没有在 GitBook 中手工调整目录，`SUMMARY.md` 会直接作为目录来源。
38+
- 如果你后续把文档迁移到其他根目录，需要同步更新 `.gitbook.yaml`。

‎examples/03-modern-cpp/src/compile_time.cpp‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,7 @@ void demonstrate_primes() {
297297

298298
} // namespace hpc::compile_time
299299

300+
#ifndef HPC_TEST_MODE
300301
int main() {
301302
std::cout << "=== Compile-Time Computation Demo ===\n\n";
302303

@@ -307,3 +308,4 @@ int main() {
307308

308309
return 0;
309310
}
311+
#endif

‎examples/03-modern-cpp/src/move_semantics.cpp‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,7 @@ void demonstrate_return_value() {
281281

282282
} // namespace hpc::move_semantics
283283

284+
#ifndef HPC_TEST_MODE
284285
int main() {
285286
std::cout << "=== Move Semantics Performance Demo ===\n";
286287

@@ -296,3 +297,4 @@ int main() {
296297

297298
return 0;
298299
}
300+
#endif

0 commit comments

Comments
 (0)