Code/cplusplus/learning/README.md

Absolutely! I can create a **comprehensive `README.md`** summarizing our session so far. This file can serve as both **documentation and a reference** if you continue later.

Here’s a fully structured version:

```markdown
# C++ Learning Project Setup with VS Code, CMake, clang-format, clang-tidy, and vcpkg

This repository demonstrates a fully featured C++ learning setup using:

- **VS Code** as the IDE
- **CMake** as the build system
- **vcpkg** as the package manager
- **clang-format** for code formatting
- **clang-tidy** for static analysis
- **Run/Debug configurations** for interactive debugging

The project structure is designed to host multiple tutorials (`tut1`, `tut2`, ...) as **separate executables**, and optionally share code via **shared libraries**.

---

## Project Structure

```

learning/
│
├─ tut1/
│   ├─ main.cpp
│   └─ CMakeLists.txt
├─ tut2/
│   ├─ main.cpp
│   └─ CMakeLists.txt
├─ libcommon/
│   ├─ common.cpp
│   ├─ common.h
│   └─ CMakeLists.txt
├─ CMakeLists.txt      # Root CMake file
├─ .clang-format       # Code formatting rules
├─ .clang-tidy         # Static analysis configuration
└─ .vscode/
└─ launch.json     # Optional debug/run configurations

````

---

## 1. clang-format

**Purpose:** Enforces consistent code style.

### Setup

```bash
sudo apt install clang-format
````

**.clang-format example:**

```yaml
BasedOnStyle: Google
IndentWidth: 4
ColumnLimit: 100
```

### Usage

* Format a single file:

```bash
clang-format -i tut1/main.cpp
```

* Format all source files:

```bash
find . -name "*.cpp" -o -name "*.h" | xargs clang-format -i
```

* VS Code integration:

```json
"C_Cpp.clang_format_style": "file",
"editor.formatOnSave": true
```

**Clarifications:**

* All tutorials share the same style using a project-wide `.clang-format`.
* Optional: create a CMake target to auto-format all files.

---

## 2. clang-tidy

**Purpose:** Static analysis, bug detection, and enforcing modern C++ practices.

### Setup

```bash
sudo apt install clang-tidy
```

**.clang-tidy example:**

```yaml
Checks: >
  bugprone-*,
  performance-*,
  readability-*,
  modernize-*,
  clang-analyzer-*
WarningsAsErrors: ""
HeaderFilterRegex: '.*'
```

### Usage

1. Generate compile commands with CMake:

```bash
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
```

2. Run clang-tidy on a file:

```bash
clang-tidy tut1/main.cpp -p build -header-filter='^/home/ys/family-repo/code/cplusplus/learning/.*' -quiet
```

**Testing example:**

```cpp
double x; // triggers readability-identifier-length warning
```

**Clarifications:**

* Thousands of warnings initially are normal; non-user headers are suppressed.
* Use `-header-filter` and `-quiet` to see **only your tutorial code**.
* Specific checks can be run using `-checks=`.

---

## 3. VS Code Run/Debug Configurations

**Purpose:** Run and debug executables built with CMake, with arguments and environment variables.

### Example `launch.json`

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run tut1",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/tut1/tut1",
      "args": ["arg1"],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "MIMode": "gdb",
      "setupCommands": [
        {
          "description": "Enable pretty-printing",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ]
    }
  ]
}
```

### Notes

* CMake Tools extension can **auto-generate temporary launch configurations**, which is why you can debug without `launch.json`.
* Use `launch.json` for:

  * Custom arguments
  * Environment variables
  * Named configurations
  * Stop-at-entry or other debugger options
* Compiler options are controlled via CMake:

```cmake
target_compile_options(tut1 PRIVATE -Wall -Wextra $<$<CONFIG:DEBUG>:-g>)
```

---

## 4. CMake Multi-Executable Setup

### Root CMakeLists.txt

```cmake
cmake_minimum_required(VERSION 3.25)
project(LearningCPP LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# vcpkg integration
if(DEFINED ENV{VCPKG_ROOT})
    set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" CACHE STRING "")
endif()

# Add tutorial subdirectories automatically
file(GLOB SUBDIRS RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/tut*)
foreach(subdir ${SUBDIRS})
    if(IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${subdir})
        add_subdirectory(${subdir})
    endif()
endforeach()
```

### Per-Tutorial CMakeLists.txt (e.g., `tut1`)

```cmake
add_executable(tut1 main.cpp)
# Link libraries if needed
# target_link_libraries(tut1 PRIVATE common)
```

### Shared Library Example (`libcommon`)

```cmake
add_library(common SHARED common.cpp)
target_include_directories(common PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
```

**Linking in tutorial:**

```cmake
target_link_libraries(tut1 PRIVATE common)
```

---

## 5. Key Takeaways

* **clang-format:** automatic code style enforcement
* **clang-tidy:** static analysis, bug detection, and modern C++ checks
* **CMake:** builds multiple tutorials and shared libraries
* **vcpkg:** manages dependencies
* **VS Code launch configurations:** optional but useful for debugging with arguments/env

---

## 6. Next Steps

* Run tutorials with debugger stepping into shared library code
* Add CMake targets for **format** and **tidy**
* Explore modernize checks in clang-tidy
* Manage multiple tutorials efficiently with shared utilities