Academy
Learn how to read the repository, how the teaching modules map to code, and what counts as acceptable evidence.
Skip to content
For a broader operational path, continue with the Quick Start guide.
C++20 whitepaper route
Learn performancewith evidence first
A learning-first homepage for readers who want a serious C++ guide with runnable examples, validation routes, and explicit proof standards.
Use this page as the front door to the whitepaper: understand who it is for, follow the recommended study path, then take the first-run route before diving into deeper reference material.
- Teaching modules
- 5
- Whitepaper sections
- 6
- Validation ladder
- debug→ubsan
Who should read this guide?
This guide is for readers who want more than isolated tips:
- engineers revisiting modern C++ performance work and wanting a structured re-entry point
- reviewers or interviewers who need to inspect claims against runnable code and verification surfaces
- maintainers who must understand how examples, tests, presets, and whitepaper narrative fit together
The repository treats performance advice as something to compile, test, benchmark, and falsify. An expert reader should be able to move from a claim on this page to the corresponding source file, preset, benchmark, or test target without guesswork.
Recommended study path
Start with orientation before specialization:
- Read the Academy overview to learn the repository's teaching model.
- Use Module Atlas to map each module to concrete code surfaces.
- Read Validation Doctrine before trusting any optimization claim.
- Continue into Architecture once you want repository topology and methodology.
- Keep Playbook and Reference nearby for operational detail.
First-run route
Use the preset-driven path first. It is the shortest route that still preserves architectural intent.
Run the baseline before browsing advanced optimization pages. That keeps the learning sequence anchored to a known-good build and test loop.
cmake --preset=debug && cmake --build build/debug && ctest --preset=debugValidation claims
| Claim type | Minimum evidence in this repository | Primary route |
|---|---|---|
| "the code still works" | debug configure, build, and ctest --preset=debug | Validation Doctrine |
| "the optimization is representative" | release or relwithdebinfo build plus benchmark or profiler output | Performance Methodology |
| "the concurrent path is safe" | unit or property tests plus tsan when synchronization changed | Validation & Sanitizers |
| "the docs are current" | links, navigation, and built Pages output stay aligned with the live repository | Playbook |
Whitepaper map
Architecture
Inspect repository topology, preset-driven validation, and the methodology behind every performance claim.
Algorithms
High-performance algorithm implementations with complexity analysis, cache-aware trade-offs, and reproducible benchmarks.
Playbook
Run the repository without hunting for commands. The playbook regroups setup, learning, profiling, and hardening routes.
Reference
Use the reference hub for API entry points, troubleshooting, and exact command surfaces when you need precision more than narrative.
Research
See the external literature, public repositories, and evolution notes that frame this project as an archive-ready engineering artifact.
Module map
| Module | Primary code surface | Typical evidence | Best entry page |
|---|---|---|---|
| 01. Modern CMake | examples/01-cmake-modern/, CMakeLists.txt, cmake/ | configure and target-level builds | Quick Start |
| 02. Memory & cache | examples/02-memory-cache/, tests/unit/memory/, tests/property/memory_properties.cpp | cache-sensitive benchmarks, perf stat | Module Atlas |
| 03. Modern C++ | examples/03-modern-cpp/, tests/unit/modern_cpp/ | benchmark comparisons and unit tests | Learning Path |
| 04. SIMD vectorization | examples/04-simd-vectorization/, tests/unit/simd/, tests/property/simd_properties.cpp | vectorization checks and simd_bench | Optimization Decision Tree |
| 05. Concurrency | examples/05-concurrency/, tests/unit/concurrency/, tests/property/concurrency_properties.cpp | tsan, queue tests, scaling benchmarks | Validation Doctrine |
Use the preset-driven path first. It is the shortest route that still preserves architectural intent.
cmake --preset=debug && cmake --build build/debug && ctest --preset=debugExpert reader callouts
- Interviewer or reviewer: start with Architecture and Research. Those pages expose the validation model and external context fastest.
- Future maintainer: read Module Atlas, Repository Topology, and the repository-level guidance in
AGENTS.mdandCLAUDE.mdon GitHub. - Practicing engineer: use the Playbook for commands, then move to profiling and sanitizer routes only after a baseline run succeeds.
Operational routes
Learning path
Keep the original study sequence visible, but treat it as a guided reading program rather than the whole documentation strategy.
SIMD & concurrency
Reach the performance-heavy modules directly when you already know the fundamentals and want to inspect ISA or threading trade-offs.
Validation & analysis
Use the operational guides to reproduce, profile, benchmark, and harden changes with the same vocabulary used throughout the whitepaper.
Technical specifications
| Surface | Detail |
|---|---|
| C++ standard | C++17 minimum, C++20 where beneficial |
| Build system | CMake 3.20+ with presets |
| Platforms | Linux primary; macOS and Windows via cross-platform headers |
| Compilers | GCC 11+, Clang 14+, MSVC 2022+ |
| Testing | GoogleTest + RapidCheck (property-based) |
| Benchmarks | Google Benchmark, perf integration |
| Sanitizers | ASan, TSan, UBSan via CMake presets |
| Documentation | VitePress, bilingual (en/zh), GitHub Pages |
Secondary routes
- Contributing workflow remains available for repository contributors, but it is not part of the main expert-reading arc.
- Exercises remain intentionally secondary. They are practice surfaces, not the primary architectural narrative.