Lesson 0 — Setup VS Code + toolchain (Mac & Windows)

First lesson. After this lesson you'll be able to build & run the starter app on both OSes. Focus: VS Code — the main IDE for every later lesson.

1. Goals

After this lesson you have:

• VS Code installed + 2 core extensions (C/C++, CMake Tools)
• C++20 compiler (Apple Clang on Mac / MSVC on Windows)
• CMake ≥ 3.20 + Git
• Can open lcpp.code-workspace and see 4 multi-root folders
• Can build & run an app in VS Code (F7 build, F5 debug)
• cmake.cmakePath configured correctly for each folder

2. File tree

After setup + clone, the repo layout:

lcpp/
├── apps/
│   ├── todo/                       ← todo demo app (Weeks 1-6)
│   ├── sudoku/                     ← Sudoku 9x9 UI (Phase 1-3)
│   └── sudoku_solver/              ← CLI test bench (Phase 3+)
├── libs/
│   └── solver/                     ← static lib (algorithms)
│       ├── CMakeLists.txt
│       ├── include/solver/
│       ├── src/
│       └── .vscode/settings.json   ← lib-specific config
├── docs/
│   ├── book/                       ← this book
│   └── LESSON_TEMPLATE.md
├── .vscode/settings.json           ← root workspace config
├── lcpp.code-workspace             ← multi-root workspace file
├── CLAUDE.md                       ← AI assistant instructions
└── .gitignore

Each folder under apps/ and libs/ has its own CMakeLists.txt + its own .vscode/ → isolated, builds independently.

3. What to learn

1. VS Code multi-root workspace (.code-workspace file)
2. Extension marketplace, install + configure
3. CMake Tools status bar (project picker, kit selector, build/debug)
4. CMake configure vs build vs install lifecycle
5. cmake.cmakePath, cmake.generator, compileCommands settings
6. F-key shortcuts: F5 (debug), F7 (build), Shift+F5 (run no debug)
7. Platform differences: Apple Clang vs MSVC, single-config vs multi-config generator

4. How to do it

Step 1 — Install VS Code (Mac & Windows)

Mac:

1. Download from code.visualstudio.com → .zip file
2. Unzip → drag Visual Studio Code.app into /Applications
3. Open the terminal, type code --version to verify. If it errors with "command not found":
   • Open VS Code → Cmd+Shift+P → type "Shell Command: Install 'code' command in PATH" → Enter

Windows:

1. Download the .exe installer from code.visualstudio.com
2. Run the installer → important to tick these options:
   • Add to PATH ✓
   • Register Code as an editor for supported file types ✓
   • Add 'Open with Code' action (right-click context menu) ✓
3. Open a fresh PowerShell → code --version to verify

Step 2 — Install extensions in VS Code

Open VS Code → Cmd+Shift+X (Mac) / Ctrl+Shift+X (Win) to open the Extensions panel. Install 2 required extensions:

| Extension | Publisher | ID | Role | |---|---|---|---| | C/C++ | Microsoft | ms-vscode.cpptools | IntelliSense, debugger, syntax | | CMake Tools | Microsoft | ms-vscode.cmake-tools | Project picker, configure, build, kit |

Optional (recommended):

| Extension | ID | Role | |---|---|---| | CodeLLDB | vadimcn.vscode-lldb | LLDB debugger (Mac alternative) | | Clang-Format | xaver.clang-format | Auto-format per .clang-format | | GitLens | eamodio.gitlens | Git blame, inline history | | Error Lens | usernamehw.errorlens | Show errors inline instead of on hover |

After installing, reload the VS Code window (Cmd+Shift+P → "Developer: Reload Window").

Step 3 — Install the compiler

Mac (Apple Clang):

xcode-select --install

Confirm the popup → wait for the download (~10 minutes). Verify:

clang++ --version
# Apple clang version 17.0.0 (clang-1700.x.x.x)

Apple Clang is a fork of LLVM Clang + libc++ STL. Full C++20 support.

Windows (MSVC):

2 options:

1. Visual Studio Community 2022 (full IDE, ~5GB):

   • Download from visualstudio.microsoft.com
   • In the installer pick the "Desktop development with C++" workload
   • Components: MSVC v143 toolset, Windows 11 SDK, C++ CMake tools

2. Build Tools standalone (~3GB, no IDE):

   • Download Build Tools for Visual Studio 2022
   • Same C++ workload

Verify: open "Developer PowerShell for VS 2022" from the Start menu:

cl /?
# Microsoft (R) C/C++ Optimizing Compiler Version 19.xx.xxxxx.x for x64

cl.exe is only available in Developer PowerShell, not regular PowerShell. When VS Code opens a project that has CMake Tools, it will source the environment automatically.

Step 4 — Install CMake + Git

Mac (via Homebrew):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install CMake + Git
brew install cmake git

Verify:

cmake --version    # >= 3.20
git --version
which cmake        # /opt/homebrew/bin/cmake (Apple Silicon) or /usr/local/bin/cmake (Intel)

Windows:

CMake: included in the Build Tools workload. If missing:

• Download the .msi installer from cmake.org/download
• Tick "Add CMake to system PATH for current user" during install

Git:

• Download git-scm.com/download/win
• Default setup is OK

Verify in PowerShell:

cmake --version
git --version
where.exe cmake    # e.g. C:\Program Files\CMake\bin\cmake.exe

Step 5 — Clone the project

# Mac/Windows (same command)
git clone <repo-url> lcpp
cd lcpp

Or via VS Code: Cmd+Shift+P → "Git: Clone" → paste the URL.

Step 6 — Open the multi-root workspace

Important: do NOT open the lcpp/ folder via code .. Open the workspace file:

code lcpp.code-workspace

Difference:

| How you open it | Behavior | |---|---| | code lcpp/ (open folder) | 1 root folder, CMake Tools manages everything together | | code lcpp.code-workspace (multi-root) | 4-5 separate folders in Explorer, each one its own CMake project |

After opening, the Explorer sidebar shows:

• lcpp (root)
• todo → apps/todo
• sudoku → apps/sudoku
• sudoku_solver → apps/sudoku_solver
• libs/solver → libs/solver

Step 7 — Configure cmake.cmakePath (if needed)

By default CMake Tools auto-finds cmake on PATH. If it reports Bad CMake executable: '', you need to specify the path:

Mac (Apple Silicon): in each folder's .vscode/settings.json:

{
  "cmake.cmakePath": "/opt/homebrew/bin/cmake"
}

Mac (Intel):

{
  "cmake.cmakePath": "/usr/local/bin/cmake"
}

Windows:

{
  "cmake.cmakePath": "C:/Program Files/CMake/bin/cmake.exe"
}

Or if CMake came from Build Tools:

{
  "cmake.cmakePath": "C:/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe"
}

The project ships with Mac settings already. Windows users need to edit them or add an override in user settings.

Step 8 — First CMake Configure

1. Click the sudoku folder tab in Explorer
2. Cmd+Shift+P → CMake: Configure
3. CMake Tools asks for a kit (compiler):
   • Mac: Clang 17.0.0 arm64-apple-darwin24 (or similar)
   • Windows: Visual Studio Community 2022 Release - amd64
4. CMake starts downloading GLFW + ImGui via FetchContent (the first time takes 2-5 minutes, needs internet)
5. Final output:

   -- Configuring done (XX.Xs)
   -- Generating done (X.Xs)
   -- Build files have been written to: .../apps/sudoku/build
   

Step 9 — Build

3 ways:

| Method | Shortcut / Action | |---|---| | Status bar | Click the Build button on the bottom status bar | | Keyboard | F7 (default) | | Command Palette | Cmd+Shift+P → CMake: Build |

The first build takes ~1-2 minutes (compiling GLFW + ImGui). After that, incremental builds — only ~5s.

Final output:

[100%] Built target sudoku

Step 10 — Run + Debug

Run (no debug):

• Shift+F5
• Or Cmd+Shift+P → CMake: Run Without Debugging
• Or in the terminal:

  # Mac
  ./apps/sudoku/build/sudoku
  # Windows
  apps\sudoku\build\Debug\sudoku.exe
  

Debug (with breakpoint):

• Set a breakpoint: click to the left of the line number → a red dot
• F5 to launch the debugger
• Variables panel, Call stack panel appear in the sidebar

5. Key learning — first lesson

This is lesson 0 — there is no "previous lesson" to compare against. The anchoring concepts:

• VS Code is not an IDE in the traditional sense (like IntelliJ, Visual Studio). It is an editor + extension framework. All C++ functionality comes from the C/C++ + CMake Tools extensions.
• CMake Tools manages the lifecycle Configure → Build → Run/Debug. You no longer invoke cmake by hand (unless you want to).
• Multi-root workspace lets several projects stay isolated within the same window. Each project has its own settings.
• Single-config vs multi-config generator: affects the layout of the build output; you will see the difference when switching between Mac ↔ Windows.

6. How to verify it works

Verify toolchain (terminal)

Mac:

clang++ --version    # Apple clang 17.0.0+
cmake --version      # 3.20+
git --version        # any version
code --version       # 1.85+

Windows (Developer PowerShell):

cl /?                # MSVC 19.30+
cmake --version
git --version
code --version

Verify VS Code extensions

Cmd+Shift+X → "Installed" tab:

• [ ] C/C++ (Microsoft) — present, enabled
• [ ] CMake Tools (Microsoft) — present, enabled

Verify the workspace opens correctly

After code lcpp.code-workspace, Explorer shows ≥ 4 folders (lcpp, todo, sudoku, sudoku_solver, libs/solver).

Verify the build passes

Select the sudoku folder → F7. In the Output panel (Ctrl+/Cmd+):

[100%] Built target sudoku

Verify run

Shift+F5 → a "Sudoku" window appears with a 9x9 grid containing a sample puzzle (only if you've completed Phase 1+; if you just cloned the starter repo 728db39, you'll see the ImGui demo window).

7. Common errors / pitfalls

| Symptom | Cause | Fix | |---|---|---| | VS Code: Bad CMake executable: '' | CMake not on PATH or no path configured | Add "cmake.cmakePath": "/opt/homebrew/bin/cmake" (Mac) / "C:/Program Files/CMake/bin/cmake.exe" (Win) to .vscode/settings.json | | Mac: xcode-select: command not found | macOS too old, no CLT | Update macOS to ≥ 11 | | Windows: cl.exe not recognized in PowerShell | Not Developer PowerShell | Open "Developer PowerShell for VS 2022" from the Start menu, or install the extension and it auto-sources the env | | fatal error: 'GLFW/glfw3.h' file not found | CMake configure not yet finished | Wait for configure to finish (first time is slow), reload the window | | FetchContent download timeout | Slow network/proxy | Set the https_proxy env var, or use a repo proxy CDN | | MSVC: cannot open compiler intermediate file | Antivirus scanning the build dir | Exclude build/ in Windows Defender Settings → Add exclusion | | Mac: window does not appear after Run | OpenGL context fails (macOS too old) | Update macOS to ≥ 11 | | IntelliSense detected errors red but build OK | clangd loaded a stale compile_commands.json | Reload the VS Code window. Verify cmake.copyCompileCommands is ON | | CMake Tools does not show the kit picker | CMake Tools has not scanned kits | Cmd+Shift+P → "CMake: Scan for Kits" | | Build status bar has no "Build" button | Configure has not completed | Configure first (Step 8) | | Opened code . instead of the workspace file | Explorer shows only 1 folder | Cmd+Shift+P → "File: Open Workspace from File" → choose lcpp.code-workspace |

8. Space for self-study

After setup is done, try the following directions (you do not have to do them all — pick whichever interests you):

1. Keybinding personalization: File → Preferences → Keyboard Shortcuts. Move build from F7 to a key your hand prefers.
2. Theme + font: try "Material Theme", "One Dark Pro", "Dracula". Ligature fonts: "Fira Code", "JetBrains Mono", "Cascadia Code".
3. launch.json debug config: open apps/sudoku/.vscode/launch.json, study the structure. Try adding a command-line argument to the app.
4. CMake variants: Cmd+Shift+P → "CMake: Select Variant" → switch Debug ↔ Release. Compare the binary sizes.
5. Compile commands JSON: open apps/sudoku/build/compile_commands.json. Read one entry → understand where clangd/IntelliSense gets its info from.
6. WSL2 (Windows): try installing WSL2 + Ubuntu, open the project via the "Remote - WSL" extension, build inside the Linux environment.

9. End-of-lesson exercises

Exercise 1 — Verify cross-platform path

Open lcpp.code-workspace, find the cmake.cmakePath setting. If you are on Windows, add an override:

Create apps/sudoku/.vscode/settings.json (or edit if it exists) and add a Windows-friendly path key. Then reload, reconfigure sudoku → verify that CMake Tools finds cmake.

Exercise 2 — Custom keybinding

Change the Build shortcut from F7 to Cmd+B (Mac) / Ctrl+B (Win). Hint: in the Keyboard Shortcuts panel, search "CMake: Build" and edit the shortcut. Verify that pressing Cmd+B/Ctrl+B triggers a build.

Exercise 3 — Build all 3 apps sequentially

In the terminal (repo root), write a bash or PowerShell script that builds apps/todo, apps/sudoku, apps/sudoku_solver in order. Verify the output contains "Built target" three times.

Exercise 4 — Modify the window title

Open apps/sudoku/src/app.cpp, find the line glfwCreateWindow(720, 800, "Sudoku", ...). Change the title to your name. Build + run, verify the window shows the new name.

Exercise 5 (challenge) — Cross-compile awareness

Look up the commands cmake -DCMAKE_OSX_ARCHITECTURES=x86_64 (Mac) or -A x64 (Windows MSVC). Reconfigure sudoku with an explicit architecture. Inspect compile_commands.json to see whether there is a -arch x86_64 flag or equivalent.

10. Exercise answers

{
  "cmake.cmakePath": "C:/Program Files/CMake/bin/cmake.exe",
  "cmake.generator": "Visual Studio 17 2022",
  "C_Cpp.default.cppStandard": "c++20",
  "C_Cpp.default.compileCommands": "${workspaceFolder}/build/compile_commands.json",
  "C_Cpp.default.compilerPath": "cl.exe"
}

[
  {
    "key": "cmd+b",
    "command": "cmake.build",
    "when": "cmake:enabledFullFeatureSet"
  }
]

#!/usr/bin/env bash
set -e

for app in todo sudoku sudoku_solver; do
    echo ">>> Building $app"
    cd "apps/$app"
    cmake -S . -B build
    cmake --build build
    cd ../..
done
echo "All built OK"

chmod +x build_all.sh && ./build_all.sh

$ErrorActionPreference = "Stop"
foreach ($app in @("todo", "sudoku", "sudoku_solver")) {
    Write-Host ">>> Building $app"
    Push-Location "apps\$app"
    cmake -S . -B build
    cmake --build build
    Pop-Location
}
Write-Host "All built OK"

window_ = glfwCreateWindow(720, 800, "Sudoku — Long's Practice", nullptr, nullptr);

cd apps/sudoku
rm -rf build
cmake -S . -B build -DCMAKE_OSX_ARCHITECTURES=x86_64
cat build/compile_commands.json | head -20

cmake -S . -B build -A Win32

→ Next: 01-phase1-grid-ui.md — Phase 1: Grid type + ImGui Table UI