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:

# 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:

BasedOnStyle: Google
IndentWidth: 4
ColumnLimit: 100

Usage

• Format a single file:

clang-format -i tut1/main.cpp

• Format all source files:

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

• VS Code integration:

"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

sudo apt install clang-tidy

.clang-tidy example:

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

Usage

1. Generate compile commands with CMake:

cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

2. Run clang-tidy on a file:

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

Testing example:

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

{
  "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:

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

---

4. CMake Multi-Executable Setup

Root CMakeLists.txt

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)

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

Shared Library Example (libcommon)

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

Linking in tutorial:

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