diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 455e4c244..d6f24c61e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,8 +106,6 @@ documents/vol2-modern-features/ # 卷二目录 4. **标题层级**：不超过 4 级（`####`） 5. **篇幅**：每篇文章控制在 1500-3000 字 -详细写作风格请参考 `.claude/writting_style.md`。 - ## 自定义 Vue 组件 文档站注册了若干自定义 Vue 组件，可在 Markdown 中直接使用。 diff --git a/README.en.md b/README.en.md index 7a774953c..f2227d529 100644 --- a/README.en.md +++ b/README.en.md @@ -18,28 +18,37 @@ --- - -![English Coverage](https://img.shields.io/badge/en_coverage-100%25-green.svg) 420/420 docs translated - - ## What This Project Is -`Tutorial_AwesomeModernCPP` is a continuously updated modern C++ learning project. It is not a collection of disconnected syntax notes: it connects language fundamentals, the standard library, modern features, engineering practice, and domain applications into one learning path, with compilable CMake examples for key concepts. +

A systematic modern C++ tutorial — from syntax to silicon, bringing modern C++ to the desktop, STM32 embedded, and industrial open-source projects.

+ +10 volumes, 350+ articles, from C/C++ fundamentals through concurrency, performance, engineering, and domain practice — every key concept backed by a CMake example verified in CI, not an unbuildable snippet stranded in an article. -It is designed for: +

+ articles + C++ standard + embedded + examples +

-- Learners building a systematic C/C++ foundation without relying on fragmented notes. -- C or embedded developers who want to use modern C++ in real engineering work. -- C++ developers who want to strengthen concurrency, performance, build systems, debugging, and source-code reading skills. +**Who is it for?** New to C/C++ · C or embedded background · Already know C++, want engineering depth ## Highlights -- **10-volume curriculum**: fundamentals, modern features, standard library, advanced topics, concurrency, performance, engineering, domains, open-source study, and lecture notes. -- **Compilable examples**: code samples are organized as CMake projects and validated in CI, not only shown as isolated snippets. -- **Embedded direction**: STM32F1 practice projects, resource constraints, peripheral abstraction, cross-compilation, and linker scripts. -- **Engineered docs site**: built with VitePress, with search, navigation, dark mode, local preview, and GitHub Pages deployment. -- **Bilingual content and reference cards**: Chinese-first content now has full English translation coverage, plus a C++98 to C++23 feature reference index. -- **Community articles hub**: Supports community draft submissions, editorial review and inclusion, and subsequent integration into the main content, lowering the barrier for article contributions. + + + + + + + + + + + + + +

🔧 From syntax to silicon

Go beyond desktop C++ — hands-on STM32F1 embedded: register access, interrupt safety, zero-overhead abstraction, cross-compilation & linker scripts.

⚡ Real, runnable examples

CMake projects validated in CI — not unbuildable snippets stranded in articles.

📚 One complete path

10 volumes, 350+ articles — fundamentals → modern features → standard library → advanced → concurrency → performance → engineering → domains.

🚀 C++23 current

Covers and practices concepts, coroutines, ranges and more — not stuck at C++11.

🔍 Read real code, real talks

Vol.9 studies Chromium (e.g. OnceCallback); Vol.10 is reading notes on CppCon and other talks.

🌐 Engineered + bilingual

VitePress (search / dark mode / GitHub Pages auto-deploy) + Chinese main line + English translation + C++98→23 reference cards.
## Start Here @@ -69,63 +78,13 @@ pnpm preview # Visit http://localhost:4173/Tutorial_AwesomeModernCPP/ ``` -## Content Map - -```mermaid -graph LR - V1["Vol.1 Fundamentals"] --> V2["Vol.2 Modern Features"] - V2 --> V3["Vol.3 Standard Library"] - V2 --> V4["Vol.4 Advanced Topics"] - V2 --> V5["Vol.5 Concurrency"] - V2 --> V6["Vol.6 Performance"] - V2 --> V7["Vol.7 Engineering"] - V2 --> V8["Vol.8 Domain Applications"] - V8 --> EMB["Embedded / Networking / GUI / Data / Algorithms"] - V2 --> V9["Vol.9 Open Source Study"] - V2 --> V10["Vol.10 Courses and Talks"] - V2 --> REF["C++ Reference / Compilation / Projects"] -``` - -
-Volume details and progress +## Content Guide -| Module | Content | Status | -|--------|---------|--------| -| [Vol.1: C++ Fundamentals](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol1-fundamentals/) | C crash course, types, control flow, functions, pointers, classes, template basics, memory, and exceptions | Completed | -| [Vol.2: Modern C++ Features](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol2-modern-features/) | Move semantics, smart pointers, constexpr, lambdas, structured bindings, error handling, filesystem | Completed | -| [Vol.3: Standard Library In Depth](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol3-standard-library/) | array, span, circular buffers, intrusive containers, custom allocators, type-safe register access | Partially available, pending rewrite | -| [Vol.4: Advanced Topics](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol4-advanced/) | Templates, CRTP, coroutines, if constexpr, spaceship operator, Modules, C++20/23/26 features | Partially available, pending rewrite | -| [Vol.5: Concurrency](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol5-concurrency/) | Thread lifecycle, mutexes, condition variables, atomics, lock-free structures, thread pools, coroutine I/O, Actor/Channel | In progress | -| [Vol.6: Performance](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol6-performance/) | Compiler optimization, performance and size evaluation, AVX/AVX2, assembly reading, benchmarking | Partially available, pending rewrite | -| [Vol.7: Engineering Practice](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol7-engineering/) | CMake, cross-compilation, compiler options, linker scripts, file I/O, WSL, MSVC debugging | Partially available, pending rewrite | -| [Vol.8: Domain Applications](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol8-domains/) | Embedded development, networking, GUI and graphics, data storage, algorithms and data structures | Planned, with embedded content already expanded | -| [Vol.9: Open Source Project Study](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol9-open-source-project-learn/) | Source-code study of real projects such as Chromium OnceCallback | In progress | -| [Vol.10: Courses and Talk Notes](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/vol10-open-lecture-notes/) | Notes and secondary learning material from CppCon and other courses or conference talks | In progress | -| [C++ Feature Reference Cards](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/cpp-reference/) | C++98 to C++23 quick reference for language, containers, memory, concurrency, and templates | In progress | -| [Compilation & Linking In Depth](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/compilation/) | Preprocessing, assembly, static libraries, dynamic libraries, symbol visibility, runtime loading | Completed | -| [Capstone Projects](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/projects/) | Hand-rolled STL components, mini HTTP server, GUI framework, embedded OS, and other projects | Planned | -| [Community Articles](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/community/) | Community draft submissions, editorially reviewed articles, and integration into the main content | Under construction | +The visual roadmap (ten-volume content map + learning paths by background) is integrated into the "Project Roadmap" section on the online docs home page: -
+→ [View the visual roadmap online](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/#roadmap) -## Learning Paths - -```mermaid -flowchart TD - Start(["Your starting point"]) - NewCPP["New to C/C++"] --> V1["Vol.1: Fundamentals"] --> V2["Vol.2: Modern Features"] - CEmbedded["C or embedded background"] --> V2 --> Embedded["Vol.8: Embedded Development"] - CPP["Existing C++ experience"] --> Pick["Choose by goal"] - Pick --> Concurrency["Vol.5: Concurrency"] - Pick --> Performance["Vol.6: Performance"] - Pick --> Engineering["Vol.7: Engineering"] - Pick --> Source["Vol.9: Open Source Study"] - V2 --> Reference["Use the C++ reference cards anytime"] - - Start --> NewCPP - Start --> CEmbedded - Start --> CPP -``` +> 📋 For volume content and progress see the [project roadmap](todo/000-project-roadmap.md); for release history see [changelogs/](changelogs/). ## Local Development and Checks @@ -142,11 +101,10 @@ flowchart TD | `pnpm hooks:install` / `scripts/setup_precommit.sh` | Install pre-commit checks | | `pnpm coverage` | Show English translation coverage | | `pnpm coverage:update` | Update the English coverage badge in `README.md` | -| `python3 scripts/validate_frontmatter.py` | Validate article frontmatter | -| `python3 scripts/check_links.py` | Check internal links | -| `python3 scripts/check_quality.py documents/` | Run content quality checks | -| `python3 scripts/build_examples.py --host` | Build host-side CMake examples | -| `python3 scripts/build_examples.py --stm32` | Build STM32 example projects | +| `.venv/bin/python scripts/validate_frontmatter.py` | Validate article frontmatter | +| `.venv/bin/python scripts/check_quality.py documents/` | Run content quality checks | +| `.venv/bin/python scripts/build_examples.py --host` | Build host-side CMake examples | +| `.venv/bin/python scripts/build_examples.py --stm32` | Build STM32 example projects | @@ -155,37 +113,15 @@ flowchart TD **Project Structure** -```text -Tutorial_AwesomeModernCPP/ -├── documents/ # Tutorial Markdown files and bilingual content -│ ├── vol1-fundamentals/ # Vol.1: C++ Fundamentals -│ ├── vol2-modern-features/ # Vol.2: Modern C++ Features -│ ├── vol3-standard-library/ # Vol.3: Standard Library In Depth -│ ├── vol4-advanced/ # Vol.4: Advanced Topics -│ ├── vol5-concurrency/ # Vol.5: Concurrent Programming -│ ├── vol6-performance/ # Vol.6: Performance Optimization -│ ├── vol7-engineering/ # Vol.7: Engineering Practice -│ ├── vol8-domains/ # Vol.8: Domain Applications -│ ├── vol9-open-source-project-learn/ # Vol.9: Open Source Project Study -│ ├── vol10-open-lecture-notes/ # Vol.10: Courses and Talk Notes -│ ├── community/ # Community submissions, initial publications, and reviewed content -│ ├── cpp-reference/ # C++ feature reference cards -│ ├── compilation/ # Compilation & Linking In Depth -│ └── projects/ # Capstone projects -├── code/ # Code examples, STM32F1 projects, and reusable templates -├── site/ # VitePress configuration, theme, and plugins -├── scripts/ # Build, check, coverage, and content tooling -├── todo/ # Content planning and task records -└── package.json # Node.js dependencies and script entry points -``` +- `documents/` — 10 tutorial volumes (bilingual), plus community / cpp-reference / compilation / projects +- `code/` — code examples, STM32F1 projects, and reusable templates +- `site/` — VitePress configuration, theme, and plugins +- `scripts/` — build, check, coverage, and content tooling +- `todo/`, `changelogs/` — content roadmap and release history -**Version History** +> For the full directory and navigation, see the [online docs](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/) sidebar. -| Version | Date | Notes | -|---------|------|-------| -| [v0.3.0](changelogs/v0.3.0.md) | 2026-05-20 | Vol.5 Concurrency full rewrite (47 articles), Vol.10 Lecture Notes launched, contributor system | -| [v0.2.0](changelogs/v0.2.0.md) | 2026-05-04 | Vol.9 Open Source Study initial content, ccache and GCC 14 build | -| [v0.1.0](changelogs/v0.1.0.md) | 2026-04-29 | Initial public release with Vol.1, Vol.2, compilation/linking, embedded tutorials, and related content | +**Version History** See [changelogs/](changelogs/) for full release history. @@ -211,14 +147,6 @@ If you have questions, feel free to open an issue at [GitHub Issues](https://git Thanks to everyone who has contributed to this project! See [CONTRIBUTORS.md](./CONTRIBUTORS.md) for details. - -| Contributor | Contributions | -|-------------|--------------| -| [Charliechen](https://github.com/Charliechen114514) | 📝 Content · 🔍 Review · 💡 Examples | -| [Doll-Attire](https://github.com/Doll-Attire) | 🎨 UI Design · 📝 UX Improvements | -| [YukunJ](https://github.com/YukunJ) | 🐛 Bug Reports · 💡 Content Fixes | - - > Contributions are not limited to code. UI design, illustrations, issue reports, and content suggestions all count. See [CONTRIBUTING.md](./CONTRIBUTING.md). ## Acknowledgements diff --git a/README.md b/README.md index 406c1b4e6..c854e1bcd 100644 --- a/README.md +++ b/README.md @@ -24,22 +24,35 @@ ## 这是什么项目 -`Tutorial_AwesomeModernCPP` 是一个持续更新的现代 C++ 学习项目。它不是零散的语法速查，而是把语言基础、标准库、现代特性、工程实践和领域应用放在同一条学习路径里，并为关键概念配套可编译的 CMake 示例。 +

一套系统化的现代 C++ 教程——从语法到芯片，把现代 C++ 写进桌面、STM32 嵌入式与工业级开源项目。

-适合这些读者： +10 卷、350+ 篇，从 C/C++ 基础一路讲到并发、性能、工程与领域实战；每个关键概念都配可在 CI 中编译验证的 CMake 示例，不是文章里跑不起来的孤立片段。 -- 正在系统学习 C/C++，希望少走碎片化资料弯路。 -- 有 C 或嵌入式经验，想把现代 C++ 用到真实工程里。 -- 已经会写 C++，但希望补齐并发、性能、构建、调试、源码研读等工程能力。 +

+ articles + C++ standard + embedded + examples +

+ +**适合谁？** 正在系统学 C/C++ · 有 C 或嵌入式经验 · 已会 C++ 想补齐工程能力 ## 特色亮点 -- **10 卷体系**：基础、现代特性、标准库、高级主题、并发、性能、工程、领域应用、开源项目、课程笔记逐层展开。 -- **可编译示例**：示例代码以 CMake 工程组织，可在 CI 中构建验证，不只是文章里的孤立片段。 -- **嵌入式方向**：包含 STM32F1 实战工程、资源约束、外设抽象、交叉编译与链接脚本等内容。 -- **工程化文档站**：基于 VitePress，支持搜索、导航、暗色模式、本地预览与 GitHub Pages 自动部署。 -- **双语与参考卡**：中文主线内容已完成英文翻译覆盖，并提供 C++98 到 C++23 特性参考索引。 -- **社区文章入口**：支持社区来稿初刊、审阅收录和后续主线整合，降低文章投稿门槛。 + + + + + + + + + + + + + +

🔧 从语法到芯片

深入 STM32F1 嵌入式——寄存器访问、中断安全、零开销抽象、交叉编译与链接脚本，打通裸机。

⚡ 克隆即跑的真示例

代码以 CMake 工程组织、CI 构建验证，不是文章里跑不起来的伪代码片段。

📚 一条完整路径

10 卷 350+ 篇，基础→现代特性→标准库→高级→并发→性能→工程→领域，层层递进、不碎片。

🚀 紧跟 C++23

讲解并实践 concepts、协程、ranges 等新特性，不停在 C++11。

🔍 读真源码 · 读真会议

卷九研读 Chromium（如 OnceCallback），卷十是 CppCon 等会议演讲的读书笔记。

🌐 工程化 + 双语

VitePress（搜索 / 暗色 / GitHub Pages 自动部署）+ 中文主线 + 英文翻译 + C++98→23 特性参考卡。
## 马上开始 @@ -69,63 +82,13 @@ pnpm preview # 访问 http://localhost:4173/Tutorial_AwesomeModernCPP/ ``` -## 内容地图 - -```mermaid -graph LR - V1["卷一 基础入门"] --> V2["卷二 现代特性"] - V2 --> V3["卷三 标准库"] - V2 --> V4["卷四 高级主题"] - V2 --> V5["卷五 并发编程"] - V2 --> V6["卷六 性能优化"] - V2 --> V7["卷七 工程实践"] - V2 --> V8["卷八 领域应用"] - V8 --> EMB["嵌入式 / 网络 / GUI / 数据 / 算法"] - V2 --> V9["卷九 开源项目学习"] - V2 --> V10["卷十 课程与演讲笔记"] - V2 --> REF["C++ 参考卡 / 编译链接 / 实战项目"] -``` +## 内容导览 -
-各卷内容与进度 - -| 模块 | 内容 | 状态 | -|------|------|------| -| [卷一：C++ 基础入门](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol1-fundamentals/) | C 语言速通、类型、控制流、函数、指针、类、模板初步、内存与异常 | 已完成 | -| [卷二：现代 C++ 特性](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol2-modern-features/) | 移动语义、智能指针、constexpr、Lambda、结构化绑定、错误处理、filesystem | 已完成 | -| [卷三：标准库深入](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol3-standard-library/) | array、span、环形缓冲区、侵入式容器、自定义分配器、类型安全寄存器访问 | 部分内容已有，待重写 | -| [卷四：高级主题](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol4-advanced/) | 模板、CRTP、协程、if constexpr、三路比较、Modules、C++20/23/26 特性 | 部分内容已有，待重写 | -| [卷五：并发编程](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol5-concurrency/) | 线程生命周期、互斥量、条件变量、atomic、无锁结构、线程池、协程 I/O、Actor/Channel | 编写中 | -| [卷六：性能优化](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol6-performance/) | 编译器优化、性能与代码大小评估、AVX/AVX2、汇编阅读与基准测试 | 部分内容已有，待重写 | -| [卷七：软件工程实践](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol7-engineering/) | CMake、交叉编译、编译器选项、链接脚本、文件 I/O、WSL、MSVC 调试 | 部分内容已有，待重写 | -| [卷八：领域应用](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol8-domains/) | 嵌入式、网络编程、GUI 与图形、数据存储、算法与数据结构 | 规划中，嵌入式内容已展开 | -| [卷九：开源项目学习](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol9-open-source-project-learn/) | Chromium OnceCallback 等真实开源项目源码研读 | 编写中 | -| [卷十：课程与演讲笔记](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/vol10-open-lecture-notes/) | CppCon 等课程、会议演讲与学习素材的阅读笔记和二次创作 | 编写中 | -| [C++ 特性参考卡](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/cpp-reference/) | C++98 到 C++23 核心语言、容器、内存、并发、模板特性速查 | 编写中 | -| [编译与链接深入](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/compilation/) | 预处理、汇编、静态库、动态库、符号可见性、运行时加载 | 已完成 | -| [贯穿式实战项目](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/projects/) | 手写 STL、迷你 HTTP 服务器、GUI 框架、嵌入式 OS 等综合项目 | 规划中 | -| [社区文章](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/community/) | 社区来稿初刊、审阅收录文章与后续主线整合入口 | 建设中 | +可视化路线图（十卷内容地图 + 按背景选择学习路径）已整合进在线文档站首页的「项目路线图」区： -
+→ [在线查看可视化路线图](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/#roadmap) -## 学习路径 - -```mermaid -flowchart TD - Start(["你的起点"]) - NewCPP["C/C++ 零基础"] --> V1["卷一：基础入门"] --> V2["卷二：现代特性"] - CEmbedded["有 C 或嵌入式经验"] --> V2 --> Embedded["卷八：嵌入式开发"] - CPP["已有 C++ 经验"] --> Pick["按目标选择专题"] - Pick --> Concurrency["卷五：并发"] - Pick --> Performance["卷六：性能"] - Pick --> Engineering["卷七：工程实践"] - Pick --> Source["卷九：开源项目学习"] - V2 --> Reference["C++ 参考卡随时查"] - - Start --> NewCPP - Start --> CEmbedded - Start --> CPP -``` +> 📋 各卷内容与进度见 [项目总路线图](todo/000-project-roadmap.md)，版本变更见 [changelogs/](changelogs/)。 ## 本地开发与质量检查 @@ -142,11 +105,10 @@ flowchart TD | `pnpm hooks:install` / `scripts/setup_precommit.sh` | 安装 pre-commit 提交前检查 | | `pnpm coverage` | 查看英文翻译覆盖率 | | `pnpm coverage:update` | 更新 `README.md` 中的英文翻译覆盖率徽章 | -| `python3 scripts/validate_frontmatter.py` | 验证文章 frontmatter | -| `python3 scripts/check_links.py` | 检查 Markdown 与组件内部链接有效性 | -| `python3 scripts/check_quality.py documents/` | 内容质量检查 | -| `python3 scripts/build_examples.py --host` | 编译主机侧 CMake 示例 | -| `python3 scripts/build_examples.py --stm32` | 编译 STM32 示例工程 | +| `.venv/bin/python scripts/validate_frontmatter.py` | 验证文章 frontmatter | +| `.venv/bin/python scripts/check_quality.py documents/` | 内容质量检查 | +| `.venv/bin/python scripts/build_examples.py --host` | 编译主机侧 CMake 示例 | +| `.venv/bin/python scripts/build_examples.py --stm32` | 编译 STM32 示例工程 | @@ -155,37 +117,15 @@ flowchart TD **项目结构** -```text -Tutorial_AwesomeModernCPP/ -├── documents/ # 教程 Markdown 文件与中英文内容 -│ ├── vol1-fundamentals/ # 卷一：C++ 基础入门 -│ ├── vol2-modern-features/ # 卷二：现代 C++ 特性 -│ ├── vol3-standard-library/ # 卷三：标准库深入 -│ ├── vol4-advanced/ # 卷四：高级主题 -│ ├── vol5-concurrency/ # 卷五：并发编程 -│ ├── vol6-performance/ # 卷六：性能优化 -│ ├── vol7-engineering/ # 卷七：软件工程实践 -│ ├── vol8-domains/ # 卷八：领域应用 -│ ├── vol9-open-source-project-learn/ # 卷九：开源项目学习 -│ ├── vol10-open-lecture-notes/ # 卷十：课程与演讲笔记 -│ ├── community/ # 社区来稿、初刊文章与已审阅收录内容 -│ ├── cpp-reference/ # C++ 特性参考卡 -│ ├── compilation/ # 编译与链接深入 -│ └── projects/ # 贯穿式实战项目 -├── code/ # 示例代码、STM32F1 工程与可复用模板 -├── site/ # VitePress 站点配置、主题与插件 -├── scripts/ # 构建、检查、覆盖率与内容工具 -├── todo/ # 内容规划与任务记录 -└── package.json # Node.js 依赖与脚本入口 -``` +- `documents/` — 10 卷教程内容（中英双语），含 community / cpp-reference / compilation / projects 等区 +- `code/` — 示例代码、STM32F1 工程与可复用模板 +- `site/` — VitePress 站点配置、主题与插件 +- `scripts/` — 构建、检查、覆盖率与内容工具 +- `todo/`、`changelogs/` — 内容路线图与版本变更记录 -**版本历史** +> 完整目录与站点导航见[在线文档站](https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/)侧边栏。 -| 版本 | 日期 | 说明 | -|------|------|------| -| [v0.3.0](changelogs/v0.3.0.md) | 2026-05-20 | 卷五并发编程全面重写（47 篇）、卷十课程笔记上线、贡献者体系建立 | -| [v0.2.0](changelogs/v0.2.0.md) | 2026-05-04 | 卷九开源项目学习初始内容、ccache 与 GCC 14 构建 | -| [v0.1.0](changelogs/v0.1.0.md) | 2026-04-29 | 首个公开版本，包含卷一、卷二、编译与链接、嵌入式教程等内容 | +**版本历史** 完整变更记录见 [changelogs/](changelogs/)。 @@ -211,14 +151,6 @@ Tutorial_AwesomeModernCPP/ 感谢所有为本项目做出贡献的人！详见 [CONTRIBUTORS.md](./CONTRIBUTORS.md)。 - -| 贡献者 | 贡献类型 | -|--------|---------| -| [Charliechen](https://github.com/Charliechen114514) | 📝 内容 · 🔍 审阅 · 💡 示例 | -| [Doll-Attire](https://github.com/Doll-Attire) | 🎨 界面设计 · 📝 体验改进 | -| [YukunJ](https://github.com/YukunJ) | 🐛 问题反馈 · 💡 内容修复 | - - > 贡献方式不限于代码，包括界面设计、插画、问题反馈、内容建议等。详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 致谢 diff --git a/documents/community/dev/index.md b/documents/community/dev/index.md index dd78637b6..b31990605 100644 --- a/documents/community/dev/index.md +++ b/documents/community/dev/index.md @@ -14,6 +14,13 @@ description: "社区协作下的项目维护节奏、开发日志、发布治理 - `CONTRIBUTING.md` 记录投稿、审阅和质量规则。 - `community/dev/` 记录维护者如何推进网站和内容迭代。 +## 路线图与版本 + +想了解项目下一步做什么、已经发布了什么？以下是两个权威来源（托管在 GitHub 仓库根目录）： + +- 📋 **[项目总路线图](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/blob/main/todo/000-project-roadmap.md)** — 总体优先级（P0–P3）、各卷资产/缺口判断与近期重点；卷级细节见同目录 `todo/010–020`。 +- 📦 **[版本变更记录](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/tree/main/changelogs)** — 每个已发布版本的新增内容与重要改动。 + ## 开发记录 diff --git a/documents/en/community/dev/index.md b/documents/en/community/dev/index.md index 5d9f36800..75a9ef327 100644 --- a/documents/en/community/dev/index.md +++ b/documents/en/community/dev/index.md @@ -14,6 +14,13 @@ It does not replace `todo/`, `changelogs/`, or `CONTRIBUTING.md`: - `CONTRIBUTING.md` defines contribution, review, and quality rules. - `community/dev/` explains how maintainers move the site and content forward. +## Roadmap & Releases + +Wondering what's next or what has already shipped? These are the two authoritative sources (hosted at the repository root on GitHub): + +- 📋 **[Project Roadmap](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/blob/main/todo/000-project-roadmap.md)** — overall priorities (P0–P3), per-volume asset/gap assessment, and near-term focus; volume-level detail lives in `todo/010–020` alongside it. +- 📦 **[Release History](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/tree/main/changelogs)** — what each released version added or changed. + ## Development Notes diff --git a/documents/en/index.md b/documents/en/index.md index f0052d400..b3b1138a5 100644 --- a/documents/en/index.md +++ b/documents/en/index.md @@ -6,7 +6,7 @@ description: "A systematic modern C++ tutorial — from fundamentals to domain p hero: name: "Modern C++ Tutorial" text: "现代 C++ 教程" - tagline: "A comprehensive, systematic modern C++ development tutorial and knowledge base, from fundamentals to industrial practice" + tagline: "More than a syntax cheat-sheet — a complete path from fundamentals to engineering practice." actions: - theme: brand text: Start Learning @@ -14,6 +14,9 @@ hero: - theme: alt text: C++ Reference link: /en/cpp-reference/ + - theme: alt + text: View Roadmap + link: /en/community/dev/ - theme: alt text: GitHub link: https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP diff --git a/documents/en/vol5-concurrency/exercises/02-atomic-spsc.md b/documents/en/vol5-concurrency/exercises/02-atomic-spsc.md index d82e5d84f..4ad9782f1 100644 --- a/documents/en/vol5-concurrency/exercises/02-atomic-spsc.md +++ b/documents/en/vol5-concurrency/exercises/02-atomic-spsc.md @@ -422,11 +422,15 @@ Many people assume that "lock-free" is always faster, but the reality is not tha ### Implementation Guide -Follow the requirements from the "Concurrent Performance Measurement Methodology" chapter in `.claude/chapter-projects-outline.md`: - -1. Warm-up phase—run 5 rounds first without recording data -2. Formal collection—at least 10 rounds, take the median -3. Report format—test environment, parameters, results, conclusions, and boundaries +Follow this unified benchmark methodology (shared by all later Labs): + +1. **Measurement goal** — decide whether you measure throughput (ops/s), latency, or scalability; test one at a time. +2. **Warm-up** — run 5 rounds without recording, so caches and branch predictors reach steady state. +3. **Multi-round collection** — at least 10 formal rounds; take the **median** (never a single run or a plain average). +4. **Pin CPU affinity** — use `taskset` or `pthread_setaffinity_np` to bind threads to fixed cores, avoiding OS migration noise; distinguish physical cores from hyper-threaded logical cores. +5. **Two data scales** — one dataset fits in L3, one exceeds L3, to expose cache effects. +6. **Don't let the result be optimized away** — use `benchmark::DoNotOptimize` or write to `volatile` so the computation isn't elided; preallocate memory to avoid allocator-lock interference. +7. **Report format** — test environment, parameters, results, conclusions, and boundaries (differences under ~5% are usually not significant; focus on order-of-magnitude differences). Pseudocode: diff --git a/documents/en/vol5-concurrency/exercises/06-capstone-mini-runtime.md b/documents/en/vol5-concurrency/exercises/06-capstone-mini-runtime.md index 30a7b24ba..b33c0ba5e 100644 --- a/documents/en/vol5-concurrency/exercises/06-capstone-mini-runtime.md +++ b/documents/en/vol5-concurrency/exercises/06-capstone-mini-runtime.md @@ -251,7 +251,7 @@ Insert metrics collection points at key paths in the runtime: - When a new connection is established: `max_connections_.update(current_connections)` - Periodic sampling of queue length (optional) -Write an end-to-end benchmark: start the runtime, submit N tasks, wait for all futures to complete, and report the total time and throughput. Refer to the benchmark methodology in `.claude/chapter-projects-outline.md`. +Write an end-to-end benchmark: start the runtime, submit N tasks, wait for all futures to complete, and report the total time and throughput. Reuse Lab 2's benchmark methodology — warm up, take the median over multiple rounds, pin CPU affinity, and report the environment and boundaries; don't trust a single run or swings under ~5%. Finally, run the complete test suite with TSan to confirm there are no data races. diff --git a/documents/index.md b/documents/index.md index c0dd2c5cf..f60364db7 100644 --- a/documents/index.md +++ b/documents/index.md @@ -6,11 +6,14 @@ description: "系统化的现代 C++ 教程 — 从基础入门到领域实战" hero: name: "现代 C++ 教程" text: "Modern C++ Tutorial" - tagline: "一套完整的、系统化的现代 C++ 开发教程与知识库，从基础入门到工业级实战" + tagline: "不止于语法速查 —— 从基础到工程实战的一条完整现代 C++ 路径" actions: - theme: brand text: 开始学习 link: /vol1-fundamentals/ + - theme: alt + text: 查看路线图 + link: /roadmap/ - theme: alt text: C++ 速查 link: /cpp-reference/ diff --git a/documents/roadmap/index.md b/documents/roadmap/index.md new file mode 100644 index 000000000..8081ab60e --- /dev/null +++ b/documents/roadmap/index.md @@ -0,0 +1,190 @@ +--- +title: "学习路线图" +description: "从零基础到工程实战的现代 C++ 学习路径——按背景选起点、十卷递进详解、学习节奏与配套资源" +--- + +# 学习路线图 + +这份路线图告诉你：**这套教程该怎么学、从哪里开始、每一卷教什么**。 + +它面向「想系统掌握现代 C++」的人——无论你是零基础、有 C/嵌入式背景，还是已经会写 C++ 想补齐工程能力。下面先按背景选起点，再逐卷展开。 + +> 这里是**学习路线图**（读者怎么学）。项目本身的开发进展与规划是另一回事，见文末[内容成熟度与项目路线图](#内容成熟度与项目路线图)。 + +## 这份路线图怎么用 + +整套教程按一条递进主线组织： + +``` +基础 → 现代特性 → 标准库 → 高级 → 并发 → 性能 → 工程 → 领域实战 +``` + +- **不是语法速查**：每个关键概念都配可编译的 CMake 示例，能跑、能改、能验证。 +- **卷与卷之间有依赖**：后面的卷默认你掌握了前面的核心（尤其卷一→卷二是关键分水岭）。 +- **可以跳读**：有相关背景的读者不必从卷一第一页读起，按下面的「三条路径」选起点即可。 +- **配套资源随时查**：[C++ 特性参考卡](/cpp-reference/)（C++98→C++23 速查）、[实战项目](/projects/)、[课程笔记](/vol10-open-lecture-notes/)。 + +## 三条学习路径（按背景选起点） + +```mermaid +flowchart TD + Start(["你的背景？"]) + A["零基础 / 仅会 C"] --> V1["卷一 基础入门
(含 C 速通)"] + B["有 C 或嵌入式经验"] --> V2a["卷二 现代特性
(补现代写法)"] + C["已会 C++"] --> Goal["按目标选专题"] + + V1 --> V2["卷二 现代特性"] + V2 --> V3["卷三 标准库"] + V3 --> V4["卷四 高级"] + V2 --> V5["卷五 并发"] + V5 --> V6["卷六 性能"] + V6 --> V7["卷七 工程"] + V7 --> V8["卷八 领域/嵌入式"] + V2a --> V8 + V8 --> V9["卷九 开源研读"] + V8 --> V10["卷十 课程笔记"] + + Goal --> Conc["卷五 并发"] + Goal --> Perf["卷六 性能"] + Goal --> Eng["卷七 工程"] + Goal --> Src["卷九 开源研读"] + Goal --> Adv["卷四 高级前沿"] + + Start --> A + Start --> B + Start --> C +``` + +- **路径 A · 零基础 / 仅会 C**：从 [卷一](/vol1-fundamentals/) 开始（含 C 语言速通），沿主线一卷卷走。最稳，也最长。 +- **路径 B · 有 C 或嵌入式经验**：你的语法底子够，直接进 [卷二](/vol2-modern-features/) 补「现代 C++ 写法」，然后扎进 [卷八 嵌入式](/vol8-domains/) 实战，按需补并发（五）/性能（六）/工程（七）。 +- **路径 C · 已会 C++**：按目标直取专题——要并发读 [卷五](/vol5-concurrency/)，要性能读 [卷六](/vol6-performance/)，要工程化读 [卷七](/vol7-engineering/)，想读大型源码读 [卷九](/vol9-open-source-project-learn/)，追前沿读 [卷四](/vol4-advanced/)。 + +## 卷级详解 + +### 卷一 · 基础入门 + +- **定位**：从零建立 C++ 完整知识体系，含一份完整的 C 语言速通教程。 +- **关键主题**：环境搭建 · 类型系统与值类别 · 控制流与函数 · 指针与引用 · 数组与字符串（`std::array`/`std::string`） · 类与面向对象 · 继承与多态 · 模板初步与异常。 +- **规模**：约 102 篇（全仓最厚）。 +- **亮点**：C 语言速通复习 · 值类别深度剖析 · 智能指针预览 · STL 初见。 +- **难度 / 前置**：入门 → 中级 / 无前置。 +- **建议节奏**：零基础全读；有基础可跳过 C 速通，重点看值类别、OOP、模板初步。 + +### 卷二 · 现代特性 + +- **定位**：系统掌握 C++11/14/17 核心特性，是「会写 C++」与「会写现代 C++」的关键分水岭。 +- **关键主题**：移动语义与右值引用 · 智能指针与 RAII · `constexpr` 编译期计算 · Lambda 与函数式 · 类型安全（`enum class`/`variant`/`optional`） · 结构化绑定 · `auto`/`decltype`/`string_view`/`filesystem`。 +- **规模**：约 56 篇。 +- **亮点**：移动语义实践 · RAII 深度剖析 · Lambda 捕获详解 · `string_view` 性能与陷阱。 +- **难度 / 前置**：中级 / 卷一。 +- **建议节奏**：核心转折卷，务必精读；这一卷决定你后续所有卷的顺畅度。 + +### 卷三 · 标准库深入 + +- **定位**：STL 容器与字符串的实现细节、性能与内存底层机制。 +- **关键主题**：`vector` 动态扩容与迭代器失效 · `string` 内存模型与小字符串优化 · `char8_t` 与 UTF-8 · `span` · 自定义分配器 · 对象大小与平凡类型。 +- **规模**：约 8 篇（篇幅小但深）。 +- **亮点**：`vector` 实现与性能分析 · `string` 内存模型深度剖析 · 自定义分配器。 +- **难度 / 前置**：中级 / 卷一、卷二。 +- **建议节奏**：按需精读；做性能敏感或嵌入式开发时回头看。 + +### 卷四 · 高级主题 + +- **定位**：C++20/23/26 前沿特性与元编程技术，写库、写高性能泛型代码的人必经。 +- **关键主题**：模板体系（C++11→23） · 协程与调度器 · Ranges 与管道式编程 · 三路比较 `<=>` · 空基类优化 · Modules。 +- **规模**：约 12 篇（部分章节重写中）。 +- **亮点**：协程调度器实现 · Ranges 管道实践 · 三路比较运算符 · C++ Modules（MSVC）。 +- **难度 / 前置**：高级 / 卷二、卷三。 +- **建议节奏**：先读协程、Ranges、三路比较三块；其余随用随补。 + +### 卷五 · 并发编程 + +- **定位**：从线程原语到协程异步，建立完整并发判断力（先正确再性能、先锁再无锁、先同步再任务）。 +- **关键主题**：线程生命周期与 RAII · 互斥与同步原语 · `atomic` 与六种内存序 · 无锁数据结构（SPSC/MPMC） · `future` 与线程池 · 协程与事件循环 · Actor/Channel。 +- **规模**：约 44 篇 + 9 个练习项目（Lab 0–5 + Capstone）。 +- **亮点**：内存序详解 · 无锁队列 · 协程 Echo 服务器 · Mini Concurrent Runtime（Capstone）。 +- **难度 / 前置**：中高 / 卷一 ~ 卷四。 +- **建议节奏**：规模最大、配套 Lab 最多，强烈建议动手做 Lab，不要只读。 + +### 卷六 · 性能优化 + +- **定位**：CPU 缓存、SIMD、汇编阅读、优化模式等 C++ 性能核心技术。 +- **关键主题**：内联与编译器优化 · 性能与代码大小评估 · AVX/AVX2。 +- **规模**：3 篇（重写扩充中）。 +- **亮点**：内联与编译器优化 · AVX/AVX2 深入。 +- **难度 / 前置**：中高 / 卷五。 +- **建议节奏**：内容正在扩充；先建立缓存层级与 SIMD 直觉，后续按专题深入。 + +### 卷七 · 工程实践 + +- **定位**：C++ 软件工程落地——构建、交叉编译、链接、调试、平台开发。 +- **关键主题**：CMake 与交叉编译 · 编译器选项 · 链接器与链接脚本 · WSL 开发 · MSVC 调试 · 文件 I/O 实践。 +- **规模**：约 8 篇。 +- **亮点**：交叉编译与 CMake · 链接器与链接脚本 · 文件拷贝器（完整 I/O 项目） · MSVC 调试原理。 +- **难度 / 前置**：中级 / 建议先读「编译与链接深入」。 +- **建议节奏**：配合 [编译与链接](/compilation/) 一起学；按当前工程栈挑读。 + +### 编译与链接深入 + +- **定位**：C/C++ 编译、链接、静态/动态库、符号可见性的底层机制，是工程实践的基础。 +- **关键主题**：编译链接概述 · 静态库 · 动态库设计与原则 · 符号可见性 · 运行时加载 · 库搜索逻辑。 +- **规模**：约 10 篇。 +- **亮点**：动态库设计 · 符号可见性（ABI 层控制） · 动态库作为可执行文件。 +- **难度 / 前置**：中级 / C++ 基础。 +- **建议节奏**：作为卷七的前置；做嵌入式/交叉编译前必读。 + +### 卷八 · 领域应用 + +- **定位**：现代 C++ 在各垂直领域的实战，**主线是嵌入式**（STM32F1/F4）。 +- **关键主题**：STM32 环境搭建 · LED/按键/UART 全流程（从 C 重构到 C++23） · 零开销抽象 · 寄存器访问 · 中断安全 ·（网络/GUI/数据存储 规划中）。 +- **规模**：约 75 篇（其中嵌入式 62 篇）。 +- **亮点**：LED 点灯 13 篇系列 · UART 串口 13 篇系列（含协程/`expected`/concepts） · 中断安全的代码 · 嵌入式零开销抽象。 +- **难度 / 前置**：中级 / 卷一 ~ 卷七。 +- **建议节奏**：嵌入式是当前最完整的领域主线，按外设循序渐进；有 STM32 板子可同步实操。 + +### 卷九 · 开源项目学习 + +- **定位**：分析工业级开源项目源码，学真实世界的 C++ 设计与实现。 +- **关键主题**：Chromium `OnceCallback` 回调设计机制 ·（更多项目规划中）。 +- **规模**：约 20 篇。 +- **亮点**：OnceCallback——从 Chromium 学到的回调设计（完整系列）。 +- **难度 / 前置**：中高 / 卷一 ~ 卷七（尤其卷四、卷五、卷七）。 +- **建议节奏**：读源码导向；建议先掌握卷四高级特性，再来读工业级实现。 + +### 卷十 · 课程与演讲笔记 + +- **定位**：CppCon 等技术会议演讲与开源课程的阅读笔记和二次创作。 +- **关键主题**：CppCon 2025——概念泛型编程 · Ranges · 移动语义 · 底层汇编阅读。 +- **规模**：约 24 篇。 +- **亮点**：Concept-based Generic Programming · Back to Basics: Ranges · Back to Basics: Move Semantics。 +- **难度 / 前置**：中级 / 卷一 ~ 卷五。 +- **建议节奏**：用作「深化」——学完对应卷后看相关演讲笔记加固理解。 + +## 学习节奏与建议 + +- **时间预期**：零基础走完整条主线是长期工程（数百篇 + 实战），别指望速成；按卷设里程碑，每卷配示例动手敲。 +- **推荐顺序**：严格按 一→二→三→四→五→六→七→八 的依赖走最稳；有背景则按「三条路径」切入。 +- **跳读策略**：卷一可跳 C 速通；卷三/卷六/卷九篇幅小或扩充中，按需读；卷十可穿插在对应卷之后当复习。 +- **用实战串联**：每学完一块，去 [实战项目](/projects/) 找对应项目练手（协程服务器、并发运行时、嵌入式等），把零散知识捏成完整能力。 + +## 配套资源 + +- [C++ 特性参考卡](/cpp-reference/)：C++98→C++23 共约 46 篇速查，按标准版本与功能类别双视图。 +- [贯穿式实战项目](/projects/)：把各卷知识串成可交付项目。 +- [社区文章](/community/)：社区来稿与审阅收录，也欢迎你投稿。 +- [卷十 课程笔记](/vol10-open-lecture-notes/)：CppCon 等顶级演讲的二次创作，深化用。 + +## 内容成熟度与项目路线图 + +各卷的当前状态（供你判断哪部分内容最扎实）： + +- ✓ **成熟稳定**：卷一 基础、卷二 现代特性、编译与链接深入。 +- ✦ **推进中**：卷三 标准库、卷四 高级、卷五 并发、卷七 工程、卷八 嵌入式、卷十 课程笔记。 +- ◇ **扩充/规划中**：卷六 性能、卷九 开源研读、卷八的 网络/GUI/数据 子领域。 + +想看**项目本身的开发规划**（要做什么、发布节奏、TODO 优先级），那是另一份文档： + +- 📋 [项目开发路线图（`community/dev/`）](/community/dev/) — 维护节奏、发布治理、站点演进。 +- 📦 [版本变更记录（`changelogs/`）](https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/tree/main/changelogs) — 每个已发布版本改了什么。 + +> 简言之：**学习路线图**（本页）回答「我该怎么学」；**项目路线图**回答「这个项目在做什么」。 diff --git a/documents/vol5-concurrency/exercises/02-atomic-spsc.md b/documents/vol5-concurrency/exercises/02-atomic-spsc.md index 463c4e9cb..a6b3f8c17 100644 --- a/documents/vol5-concurrency/exercises/02-atomic-spsc.md +++ b/documents/vol5-concurrency/exercises/02-atomic-spsc.md @@ -414,11 +414,15 @@ TEST_CASE("Milestone 4: benchmark padded vs unpadded", ### 实现指引 -参考 `.claude/chapter-projects-outline.md` 中"并发性能测量方法论"章节的要求： - -1. 热身阶段——先跑 5 轮，不记录数据 -2. 正式采集——至少 10 轮，取中位数 -3. 报告格式——测试环境、参数、结果、结论和边界 +按统一的 benchmark 方法论来测（后续 Lab 共用这套准则）： + +1. **测量目标**——明确测的是吞吐量（ops/s）、延迟还是扩展性，一次只测一个。 +2. **热身**——先跑 5 轮不计入，让缓存与分支预测进入稳态。 +3. **多轮采集**——正式至少 10 轮，取**中位数**（不要只取平均或单次）。 +4. **固定 CPU 亲和性**——用 `taskset` 或 `pthread_setaffinity_np` 把线程钉在固定核心，避免 OS 迁移核心引入噪声；区分物理核与超线程逻辑核。 +5. **两组数据规模**——一组数据量在 L3 缓存内、一组超出 L3，观察缓存效应。 +6. **防止结果被优化掉**——用 `benchmark::DoNotOptimize` 或写入 `volatile`，确保计算不被编译器消除；预分配内存，避免分配器锁干扰。 +7. **报告格式**——测试环境、参数、结果、结论与边界（5% 以内的差异通常不显著，关注量级差异）。 伪代码： diff --git a/documents/vol5-concurrency/exercises/06-capstone-mini-runtime.md b/documents/vol5-concurrency/exercises/06-capstone-mini-runtime.md index a7f09ae2f..efda03a91 100644 --- a/documents/vol5-concurrency/exercises/06-capstone-mini-runtime.md +++ b/documents/vol5-concurrency/exercises/06-capstone-mini-runtime.md @@ -244,7 +244,7 @@ TEST_CASE("Milestone 3: channel close propagates through pipeline", - 新连接建立时 `max_connections_.update(current_connections)` - 队列长度定期采样（可选） -写一个端到端 benchmark：启动 runtime，提交 N 个任务，等待所有 future 完成，报告总耗时和吞吐量。参考 `.claude/chapter-projects-outline.md` 中的 benchmark 方法论。 +写一个端到端 benchmark：启动 runtime，提交 N 个任务，等待所有 future 完成，报告总耗时和吞吐量。沿用 Lab 2 的 benchmark 方法论——热身后多轮取中位数、固定 CPU 亲和性、报告测试环境与边界，别只看单次或 5% 以内的波动。 最后，用 TSan 运行完整的测试套件，确认没有 data race。 diff --git a/scripts/build.ts b/scripts/build.ts index d7a51b68e..69ecf2c87 100644 --- a/scripts/build.ts +++ b/scripts/build.ts @@ -37,6 +37,7 @@ const VOLUMES: Volume[] = [ { name: 'cpp-reference', srcDir: 'cpp-reference', urlPrefix: '/cpp-reference' }, { name: 'projects', srcDir: 'projects', urlPrefix: '/projects' }, { name: 'community', srcDir: 'community', urlPrefix: '/community' }, + { name: 'roadmap', srcDir: 'roadmap', urlPrefix: '/roadmap' }, { name: 'appendix', srcDir: 'appendix', urlPrefix: '/appendix' }, { name: 'team', srcDir: 'team', urlPrefix: '/team' }, ] @@ -207,7 +208,7 @@ function generateRootConfig(absSiteDir: string, absSrcDir: string): string { return `import { defineConfig } from 'vitepress' import withDrawio from '@dhlx/vitepress-plugin-drawio' import { sharedBase, sharedThemeConfig, sharedEnThemeConfig } from '${relShared}' -import { navZh, navEn } from '${relNav}' +import { navEn } from '${relNav}' import { buildSidebar } from '${relSidebar}' export default withDrawio(defineConfig({ @@ -224,10 +225,8 @@ export default withDrawio(defineConfig({ themeConfig: { nav: navEn, editLink: { pattern: 'https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/edit/main/documents/en/:path', text: 'Edit this page on GitHub' } } }, }, themeConfig: { - nav: navZh, sidebar: buildSidebar(), search: { provider: 'local' }, - editLink: { pattern: 'https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/edit/main/documents/:path', text: '在 GitHub 上编辑此页' }, - footer: { message: '基于 VitePress 构建', copyright: 'Copyright 2025-2026 Charliechen' }, - socialLinks: [{ icon: 'github', link: 'https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP' }], + ...sharedThemeConfig(), + sidebar: buildSidebar(), }, }), { width: '100%', diff --git a/site/.vitepress/config/build-info.ts b/site/.vitepress/config/build-info.ts new file mode 100644 index 000000000..343a0116b --- /dev/null +++ b/site/.vitepress/config/build-info.ts @@ -0,0 +1,29 @@ +import { execFileSync } from 'node:child_process' + +// VitePress config 在 Node 运行,CI 已 fetch-depth: 0,可零依赖拿到 git 信号。 +// 版本展示的唯一真相源是 git tag(package.json version 是停滞占位值,不可用)。 + +function git(args: string[]): string { + try { + return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() + } catch { + return '' // 非 git 仓库 / 无 tag → 回退 + } +} + +export interface BuildInfo { + /** git describe 结果,如 v0.5.3 或 v0.5.3-3-gabc1234(-dirty 表示有未提交改动) */ + version: string + /** 7 位短 SHA */ + sha: string + /** 构建日期 YYYY-MM-DD */ + date: string +} + +export function getBuildInfo(): BuildInfo { + return { + version: git(['describe', '--tags', '--always', '--dirty']) || 'dev', + sha: git(['rev-parse', '--short=7', 'HEAD']), + date: new Date().toISOString().substring(0, 10), + } +} diff --git a/site/.vitepress/config/index.ts b/site/.vitepress/config/index.ts index a6f096325..b3c9e4833 100644 --- a/site/.vitepress/config/index.ts +++ b/site/.vitepress/config/index.ts @@ -1,7 +1,8 @@ import { defineConfig } from 'vitepress' import withDrawio from '@dhlx/vitepress-plugin-drawio' -import { navZh, navEn } from './nav' +import { navEn } from './nav' import { buildSidebar } from './sidebar' +import { sharedThemeConfig } from './shared' import { kbdPlugin } from '../plugins/kbd-plugin' import { cppTemplateEscapePlugin } from '../plugins/escape-cpp-templates' import { mermaidPlugin } from '../plugins/mermaid-plugin' @@ -101,26 +102,8 @@ export default withDrawio(defineConfig({ }, themeConfig: { - nav: navZh, + ...sharedThemeConfig(), sidebar: buildSidebar(), - - search: { - provider: 'local', - }, - - editLink: { - pattern: 'https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP/edit/main/documents/:path', - text: '在 GitHub 上编辑此页', - }, - - footer: { - message: '基于 VitePress 构建', - copyright: 'Copyright 2025-2026 Charliechen', - }, - - socialLinks: [ - { icon: 'github', link: 'https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeModernCPP' }, - ], }, }), { width: '100%', diff --git a/site/.vitepress/config/nav.ts b/site/.vitepress/config/nav.ts index 34375d28f..d677830c4 100644 --- a/site/.vitepress/config/nav.ts +++ b/site/.vitepress/config/nav.ts @@ -37,6 +37,7 @@ export const navZh: DefaultTheme.NavItem[] = [ { text: '参考', link: '/cpp-reference/' }, { text: '附录', link: '/appendix/' }, { text: '社区', link: '/community/' }, + { text: '路线图', link: '/roadmap/' }, { text: '贡献者', link: '/team/' }, ] @@ -76,5 +77,7 @@ export const navEn: DefaultTheme.NavItem[] = [ }, { text: 'Reference', link: '/en/cpp-reference/' }, { text: 'Appendix', link: '/en/appendix/' }, + { text: 'Community', link: '/en/community/' }, + { text: 'Roadmap', link: '/en/community/dev/' }, { text: 'Team', link: '/en/team/' }, ] diff --git a/site/.vitepress/config/shared.ts b/site/.vitepress/config/shared.ts index 02e6732d4..a6c72e6b0 100644 --- a/site/.vitepress/config/shared.ts +++ b/site/.vitepress/config/shared.ts @@ -3,6 +3,10 @@ import { navZh, navEn } from './nav' import { kbdPlugin } from '../plugins/kbd-plugin' import { cppTemplateEscapePlugin } from '../plugins/escape-cpp-templates' import { mermaidPlugin } from '../plugins/mermaid-plugin' +import { getBuildInfo } from './build-info' + +// 模块加载时算一次,两个 themeConfig 函数共用;同一构建进程内一致。 +const buildInfo = getBuildInfo() export const sharedBase = { base: '/Tutorial_AwesomeModernCPP/', @@ -54,7 +58,7 @@ export function sharedThemeConfig(): DefaultTheme.Config { text: '在 GitHub 上编辑此页', }, footer: { - message: '基于 VitePress 构建', + message: `${buildInfo.version} · ${buildInfo.sha} · ${buildInfo.date}`, copyright: 'Copyright 2025-2026 Charliechen', }, socialLinks: [ @@ -74,7 +78,7 @@ export function sharedEnThemeConfig(): DefaultTheme.Config { text: 'Edit this page on GitHub', }, footer: { - message: 'Built with VitePress', + message: `${buildInfo.version} · ${buildInfo.sha} · ${buildInfo.date}`, copyright: 'Copyright 2025-2026 Charliechen', }, socialLinks: [ diff --git a/site/.vitepress/theme/components/HomeHeroVisual.vue b/site/.vitepress/theme/components/HomeHeroVisual.vue new file mode 100644 index 000000000..921788587 --- /dev/null +++ b/site/.vitepress/theme/components/HomeHeroVisual.vue @@ -0,0 +1,260 @@ + + + + + diff --git a/site/.vitepress/theme/components/HomeRoadmap.vue b/site/.vitepress/theme/components/HomeRoadmap.vue new file mode 100644 index 000000000..6040c1b65 --- /dev/null +++ b/site/.vitepress/theme/components/HomeRoadmap.vue @@ -0,0 +1,245 @@ + + + + + diff --git a/site/.vitepress/theme/components/ProofStrip.vue b/site/.vitepress/theme/components/ProofStrip.vue new file mode 100644 index 000000000..b07096583 --- /dev/null +++ b/site/.vitepress/theme/components/ProofStrip.vue @@ -0,0 +1,90 @@ + + + + + diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css index ad6ecd914..ed96ffaae 100644 --- a/site/.vitepress/theme/custom.css +++ b/site/.vitepress/theme/custom.css @@ -463,6 +463,51 @@ color: var(--vp-c-text-2) !important; } +/* ── Hero Image Slot: content card (HomeHeroVisual terminal) ── + VitePress sizes .image-container as a fixed 320/392px square and gives .image + large negative margins — both meant for a small decorative image with a + blurred background blob. A real content card needs normal document flow, so + neutralize those; otherwise the card overflows up into the hero text (and the + nav on narrow screens) and the -48px bottom margin pulls the next section + (ProofStrip) up into an overlap. */ + +.VPHero .image-bg { + display: none !important; +} + +.VPHero .image { + margin: 24px auto 0 !important; +} + +.VPHero .image-container { + width: auto !important; + height: auto !important; +} + +@media (min-width: 640px) { + .VPHero .image { + margin: 32px auto 0 !important; + } +} + +@media (min-width: 960px) { + /* Desktop two-column hero: image column fills remaining width, card centered. */ + .VPHero .image { + flex-grow: 1; + margin: 0 !important; + min-height: 100%; + } + + .VPHero .image-container { + display: flex; + justify-content: center; + align-items: center; + width: 100% !important; + height: 100% !important; + transform: none !important; + } +} + /* ── Feature Card Entrance Animation ────────────────────────── */ @keyframes feature-fade-up { diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts index 786bc9b59..fff0996b0 100644 --- a/site/.vitepress/theme/index.ts +++ b/site/.vitepress/theme/index.ts @@ -9,6 +9,9 @@ import RefLink from './components/RefLink.vue' import ReferenceCard from './components/ReferenceCard.vue' import ReferenceItem from './components/ReferenceItem.vue' import OnlineCompilerDemo from './components/OnlineCompilerDemo.vue' +import HomeHeroVisual from './components/HomeHeroVisual.vue' +import ProofStrip from './components/ProofStrip.vue' +import HomeRoadmap from './components/HomeRoadmap.vue' import { setupMermaid } from './mermaid-client' import './custom.css' @@ -16,7 +19,10 @@ export default { extends: DefaultTheme, Layout() { return h(DefaultTheme.Layout, null, { - 'home-features-before': () => h(HomeTipBanner) + 'home-hero-image': () => h(HomeHeroVisual), + 'home-hero-after': () => h(ProofStrip), + 'home-features-before': () => h(HomeTipBanner), + 'home-features-after': () => h(HomeRoadmap), }) }, setup() { diff --git a/todo/README.md b/todo/README.md index ed45fa501..9e9ced04d 100644 --- a/todo/README.md +++ b/todo/README.md @@ -49,9 +49,7 @@ estimated_effort: medium | `017-vol8-domains.md` | 卷八领域应用，嵌入式优先 | | `018-vol9-open-source-study.md` | 卷九开源项目研读路线 | | `019-vol10-lecture-notes.md` | 卷十课程笔记治理 | -| `020-compilation-and-reference.md` | 编译链接与参考卡维护 | | `020-projects.md` | 贯穿式项目路线 | -| `030-community.md` | 社区协作入口 | | `031-qa-knowledge-base.md` | QA 和知识库 | ## 旧 TODO 合并映射