add context for continuing chat in a different session

analogy to a stochastic snapshot!

cplusplus/learning/commands.md

@@ -0,0 +1,93 @@
+Perfect! Let’s extend the `README.md` with a **“Quick Commands” section** so that you have a ready reference for all the main tasks. I’ll integrate it cleanly at the end of the existing README.
+
+## 7. Quick Commands
+These commands are handy for **building, formatting, analyzing, and running tutorials**.
+
+### Build Project
+
+```bash
+# Configure and generate build system
+cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+
+# Build all tutorials
+cmake --build build
+
+# Build a specific tutorial (e.g., tut1)
+cmake --build build --target tut1
+````
+
+### Run Executables
+
+```bash
+# Run tut1 manually
+./build/tut1/tut1 arg1 arg2
+
+# Run tut2 manually
+./build/tut2/tut2
+```
+
+> Or use **VS Code debug/run panel** (CMake Tools can auto-generate temporary launch configs).
+
+### Format Code
+```bash
+# Format a single file
+clang-format -i tut1/main.cpp
+
+# Format all cpp/h files in the project
+find . -name "*.cpp" -o -name "*.h" | xargs clang-format -i
+```
+
+### Static Analysis with clang-tidy
+```bash
+# Analyze a single file
+clang-tidy tut1/main.cpp -p build -header-filter='^/home/ys/family-repo/code/cplusplus/learning/.*' -quiet
+
+# Example: test warning by introducing a short variable name
+# double x; // triggers readability-identifier-length
+```
+
+### Debugging in VS Code
+
+1. Use **CMake Tools panel → Debug target**
+
+   * Automatically sets up GDB for the executable
+   * Supports breakpoints, stepping, and inspecting variables
+
+2. Optional: Create `.vscode/launch.json` for:
+
+   * Custom arguments
+   * Environment variables
+   * Stop-at-entry behavior
+
+```json
+"args": ["arg1", "arg2"],
+"stopAtEntry": false,
+"environment": [{"name": "MY_FLAG", "value": "1"}]
+```
+
+### Shared Libraries
+```bash
+# Build shared library and tutorials
+cmake --build build
+
+# Ensure runtime can find .so files
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/family-repo/code/cplusplus/learning/build/libcommon
+```
+
+* Tutorials link against `libcommon` or other shared libraries.
+* Step into shared library code in VS Code debugger.
+
+
+### Notes
+
+* Always run `cmake -B build` if you add new tutorials or change CMake files.
+* Run `clang-format` regularly to maintain consistent code style.
+* Run `clang-tidy` to catch bugs or style issues early.
+* Debugging works even without `launch.json` due to CMake Tools auto-config.
+
+```
+
+
+✅ With this section, your **README.md** now becomes a **single-page guide** for building, formatting, analyzing, debugging, and managing multiple tutorials with shared libraries.  
+
+It will serve as a **perfect context** for continuing the session later.