cpp-course/README.md

# Modern C++ Course (Basics → C++26)

A hands-on C++ course with **56 Google Test exercises** organized into **14 modules**, from your first functions to modern standard-library features.

## Requirements

- **CMake** 3.20+
- **GCC 16+** with C++26 and contracts support
- **CLion** (recommended) or any CMake-aware IDE
- Internet access on first configure (Google Test is fetched automatically)

Install GCC 16 on macOS (Homebrew):

```bash
brew install gcc@16
```

## Quick Start (CLion)

1. Open this folder in CLion.
2. **Settings → Build, Execution, Deployment → CMake**
3. Enable profile **`default`** (display name **GCC 16 + C++26** from `CMakePresets.json`).
4. Disable old profiles that use Apple Clang (e.g. custom profiles without the preset toolchain).
5. Click **Reload CMake Project**.

If configure fails with *"This project requires GCC 16+"*, CLion is still using Apple Clang. Enable the **`default`** preset or set the toolchain C++ compiler to `g++-16`.

If configure fails with *"generator does not match"*, delete the build folder (`cmake-build-debug-gcc-16-cpp26`) and reload CMake.

6. Pick an exercise target (e.g. `02_control_flow_loops`) and run tests.

## Quick Start (Terminal)

```bash
cmake --preset default
cmake --build cmake-build-debug-gcc-16-cpp26
ctest --test-dir cmake-build-debug-gcc-16-cpp26 --output-on-failure
```

Run a single exercise:

```bash
cmake --build cmake-build-debug-gcc-16-cpp26 --target 02_control_flow_loops
./cmake-build-debug-gcc-16-cpp26/modules/02_control_flow/02_control_flow_loops
```

Manual configure (without presets):

```bash
cmake -S . -B cmake-build-debug-gcc-16-cpp26 \
  -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/gcc-16.cmake \
  -DCOURSE_ENABLE_CONTRACTS=ON
cmake --build cmake-build-debug-gcc-16-cpp26
```

## Project Structure

```
cppc/
├── CMakeLists.txt              # Root project + Google Test
├── CMakePresets.json           # GCC 16 + C++26 preset
├── cmake/
│   ├── CourseExercise.cmake    # add_course_exercise() helper
│   ├── CourseOptions.cmake     # Warnings, standards, contracts
│   └── toolchains/gcc-16.cmake # GCC 16 toolchain file
├── support/                    # Contract violation handler
└── modules/
    ├── 01_fundamentals/
    ├── 02_control_flow/
    └── ...                     # 14 modules total
```

Each module contains:

- `README.md` — learning goals and exercise list
- `include/` — function and class declarations
- `src/` — **your implementation** (start here)
- `test/` — Google Test files (do not edit unless extending)

## How to Study

1. Read the module `README.md`.
2. Open the exercise header to understand the required API.
3. Implement TODOs in the corresponding `src/` file.
4. Run that exercise’s test target in CLion or via CTest.
5. Move to the next exercise only when tests pass.

## Course Map

| Module | Topic | Exercises | Build standard |
|--------|-------|-----------|----------------|
| 01 | Fundamentals | 4 | C++26 |
| 02 | Control flow | 4 | C++26 |
| 03 | Functions | 4 | C++26 |
| 04 | Arrays & strings | 4 | C++26 |
| 05 | Pointers & references | 4 | C++26 |
| 06 | OOP basics | 4 | C++26 |
| 07 | STL containers | 4 | C++26 |
| 08 | STL algorithms | 4 | C++26 |
| 09 | C++11 features | 4 | C++26 |
| 10 | C++14 features | 4 | C++26 |
| 11 | C++17 features | 4 | C++26 |
| 12 | C++20 features | 4 | C++26 |
| 13 | C++23 features | 4 | C++26 |
| 14 | C++26 frontier | 4 | C++26 |

## CMake Options

| Option | Default | Description |
|--------|---------|-------------|
| `COURSE_BUILD_TESTS` | ON | Build Google Test exercise targets |
| `COURSE_WARNINGS_AS_ERRORS` | OFF | Treat warnings as errors |
| `COURSE_ENABLE_CONTRACTS` | ON | Enable `-fcontracts` on GCC 16+ |

Example:

```bash
cmake --preset default -DCOURSE_WARNINGS_AS_ERRORS=ON
```

## C++26 Contracts

On GCC 16+, the build enables:

- `-fcontracts`
- `-fcontract-evaluation-semantic=enforce`
- A shared `handle_contract_violation` handler in `support/contract_handler.cpp`

Example:

```cpp
#include <contracts>

[[nodiscard]] auto factorial(const int n) -> long long pre(n >= 0);
```

```cpp
auto factorial(const int n) -> long long
    pre(n >= 0)
{
    // ...
}
```

## CLion Tips

- Use the **GCC 16** toolchain, not Apple Clang.
- Disable **Clangd** and **Clang-Tidy** inspections — they use the Clang frontend and do not support GCC C++26 contracts.
- **Cppcheck plugin:** disable inline analysis for this project (see [Cppcheck](#cppcheck) below).
- Use **Run | Run…** and filter by module prefix (e.g. `02_control_flow`).
- Enable **Google Test** integration to see individual tests in the tree view.

## Cppcheck

Cppcheck **does not understand GCC C++26 contracts** (`pre(...)`) or GCC 16 libstdc++ when the CLion plugin analyzes headers in isolation. That produces false IDE errors such as:

- `Include file: <contracts> not found`
- `failed to evaluate #elif condition` in libstdc++ headers
- parse errors on `pre(...)`

### Recommended: disable the plugin, use the CMake target

1. **Settings → Editor → Inspections → C/C++ → Cppcheck** → **disable**
2. Configure and build once:
   ```bash
   cmake --preset default
   cmake --build build
   ```
3. Run Cppcheck from CLion or terminal:
   ```bash
   cmake --build build --target cppcheck_modules
   ```

This uses `compile_commands.json` from your **GCC 16** build and suppresses known false positives (`cppcheck/suppressions.txt`).

### If you keep the plugin anyway

**Settings → Cppcheck configuration → Options:**

```
--language=c++ --std=c++26 --max-configs=1 --suppress=missingIncludeSystem --suppress=syntaxError
```

Expect remaining false positives on contract syntax. The plugin is not a good fit for this codebase.

## Notes on C++26

All exercises build with **C++26**. Module READMEs describe the language feature each exercise teaches (C++11, C++17, etc.), but the toolchain baseline is C++26 throughout.

Happy learning!