11 — Tools Setup: The Day-1 Fortress

Target end state (2 hours from a clean macOS Apple Silicon machine): a working modern C++20/23 development environment with Homebrew LLVM 21+, CMake 3.28+, Ninja, Conan 2, VSCode or CLion, and a first Hello, C++23 program that builds and runs from a cmake --build build command.

1. Why this directory exists

Tooling is where most self-taught C++ learners lose 2–4 weeks. The friction is real and it’s mostly one-time. This directory front-loads all of it into one focused day (Day 1 of Phase 0) so you never have to fight your environment again for the rest of the 13 months.

Everything here is verified for macOS Sequoia / macOS 16 on Apple Silicon (M1/M2/M3/M4) as of July 2026. If you are on Intel Mac, most commands still work but some Homebrew paths differ (/usr/local vs /opt/homebrew) — flags noted inline where relevant.

2. What you’ll end up with

  • Compiler: Homebrew LLVM 21+ (clang++ + libc++) exposed on PATH so brew LLVM wins over Apple’s /usr/bin/clang++ (which lags ~2 major versions behind on C++ standards support and lacks recent libc++ features).

  • Build system: CMake 3.28+ (module support), Ninja backend.

  • Package manager: Conan 2 (default in industry), plus vcpkg on standby for a Phase 4 comparison.

  • Editor: VSCode with clangd + CodeLLDB + CMake Tools + Error Lens as primary. CLion as secondary — now free for non-commercial use since May 7, 2025 (per JetBrains).

  • Containers: OrbStack (paid, ~$8/mo but the best Docker-Desktop alternative on Apple Silicon in 2026) OR Colima (free, OSS, slightly less polished) OR native Docker Desktop. Apple added native container support at WWDC 2025 for very light workloads.

  • Cloud GPU: For CUDA work in Phase 5, a cheap on-demand plan on Thunder Compute ($1.09/hr A100) or Vast.ai spot pricing.

  • Git: GitHub CLI (gh) configured; SSH key set; two-factor on.

3. File map

#

File

What it covers

Phase relevance

0

README.md (this file)

Overview and setup principles

Day 1

1

01_day1_macos_setup.md

The full copy-pasteable Day-1 command sequence

Phase 0, Day 1

2

02_vscode_config.md

VSCode + clangd + CMake production config with dotfiles

Phase 0, Day 2

3

03_clion_alternative.md

CLion path (free non-commercial) — when it wins

Phase 0 or 4

4

04_docker_and_devcontainers.md

Reproducible Linux dev env matching CI

Phase 4 onward

5

05_cloud_and_gpu_access.md

Cloud GPUs for CUDA (no NVIDIA on Mac)

Phase 5 mandatory

4. Setup principles

4.1. Homebrew LLVM, not Apple Clang

Apple ships clang++ in Xcode Command Line Tools. It works. It also lags C++ standard support by roughly two major LLVM versions. On macOS Sequoia (default Xcode 16.x in July 2026), the system clang++ is ~LLVM 19-based whereas Homebrew’s llvm@21.1.8 (verified live on formulae.brew.sh/formula/llvm July 2026) already has near-complete C++23 support and partial C++26.

You will spend more time in the next 13 months on the standard library edge (<expected>, <print>, <mdspan>, <flat_map>, ranges, coroutines, modules) than on anything else. Brew LLVM gets you there. Apple Clang doesn’t.

4.2. CMake — even if you dislike it

You will write CMake. Everyone in the C++ industry writes CMake. There is no serious escape route in 2026. Bazel exists at Google-scale, Meson exists in niches, but 90%+ of C++ jobs in India (Zoho, Freshworks, Zerodha, Optiver, Bloomberg Bangalore, NVIDIA Bangalore) list CMake in the JD.

Craig Scott’s Professional CMake — 22nd Edition (2025), covering CMake 4.2, is the single best resource. $30 lifetime updates. Buy it Phase 0.

4.3. Conan 2 as primary, vcpkg as backup

Both are legitimate. Conan 2 has broader industry adoption in telemetry-heavy shops, vcpkg is stronger in the Microsoft ecosystem. Learn Conan first (Phase 4). Set up vcpkg once for comparison.

4.4. Two editor path (deliberate)

For daily driving, VSCode + clangd is faster, uses less RAM, and boots in ~1 second on M1/M2. For large refactoring and debugger UX, CLion is better. Set up both. Use whichever fits the task. This is not indecision; it’s tooling maturity.

4.5. Copilot policy — hard rule

Copilot and Cursor OFF for Phase 0, Phase 1, Phase 2 per the M1 no-AI-for-fundamentals rule in the master command directive (00_command/README.md). Turn back on only after you can hand-write a unique_ptr-with-custom-deleter and a future/promise example from memory. Then use AI as a spellchecker, not a co-author.

4.6. Zero magical GUIs

Do not install GUIs that hide the CMake generator, the compiler command, or the linker line. If you cannot copy the exact clang++ command from your build and paste it into a terminal, you are behind. VSCode + CMake Tools shows you the command in the output pane. CLion shows it under “Build” tool window. Look at it. Read it. This is a career-long habit.

5. Day-1 timeline (2 hours)

Time

Task

0:00–0:15

Xcode CLT + Homebrew install (01_day1_macos_setup.md §1)

0:15–0:35

brew install bundle: llvm cmake ninja git gh conan (§2)

0:35–0:45

PATH setup in ~/.zshrc; verify clang++ --version shows 21.x (§3)

0:45–1:00

Git + GitHub CLI configuration; SSH key; 2FA (§4)

1:00–1:30

VSCode + extensions + dotfiles: .clangd, .clang-format, .clang-tidy (see 02_vscode_config.md)

1:30–1:50

First Hello, C++23 template clone; cmake -B build; cmake --build build; ./build/hello

1:50–2:00

Commit to a dotfiles repo on GitHub. First green build.

If you finish under 2 hours you did it right. If over, most likely the ~/.zshrc PATH order is wrong — see troubleshooting section in 01_day1_macos_setup.md.

6. What NOT to install on Day 1

  • Homebrew gcc. You’ll rarely need it on macOS. Wait until Phase 3 when you want to compare libc++ vs libstdc++ behavior.

  • Xcode.app. Command Line Tools alone are enough. The full Xcode application is a 15 GB installer and you don’t need Interface Builder or the Swift toolchain for C++.

  • Anaconda / Miniconda. You will use uv or pyenv for Python later (Phase 5). Conda pollutes PATH.

  • Multiple Node versions, Ruby, etc. Not your problem this year.

  • Boost via Homebrew. Install per-project via Conan. Homebrew’s Boost is a 500 MB monolith you don’t need globally.

  • Homebrew Python. You will brew install uv and use uv-managed Pythons instead. Homebrew’s Python can be an ugly PATH fight.

7. India-specific notes

  • Download sizes. The Day-1 bundle pulls ~4 GB. On a typical Indian home fiber (100 Mbps Airtel/Jio) that’s ~7 minutes. On hotel wifi in Bangalore, it can be 45 minutes. Do this from a stable connection.

  • Homebrew mirror. No India-based Homebrew mirror is officially endorsed in 2026. The default github.com + ghcr.io route is fine. If you are corp-VPN’d in Zoho, verify brew reaches GitHub before starting.

  • Cloud GPU billing. All cloud GPU providers bill in USD. Use a virtual USD-capable card (Niyo, Jupiter, or your Zoho corp card if allowed). Do NOT use your primary Indian debit card for automated hourly-metered services; International-transaction limits will trip. See 05_cloud_and_gpu_access.md §5 for the tested billing path.

  • IST timing for brew upgrades. GitHub’s CDN is fastest for you between IST 07:00 and IST 11:00. Avoid IST 20:00–00:00 (US East wake-up overlaps with slow global CDN nodes).

8. Failure modes and how to spot them early

Symptom

Root cause

Fix location

clang++ --version shows Apple clang after brew install

PATH order wrong in ~/.zshrc

01_day1_macos_setup.md §3

#include <expected> — file not found

Using Apple libc++; use -stdlib=libc++ with brew LLVM’s -L/-I flags

01_day1_macos_setup.md §7 (troubleshooting)

Linker error _main referenced from _start

SDK path mismatch after macOS update

01_day1_macos_setup.md §7

cmake --build build succeeds but ./hello crashes with dyld error

Wrong runtime libc++; RPATH not set

01_day1_macos_setup.md §7

Rosetta-related x86 binary warning

You installed the wrong Homebrew arch

01_day1_macos_setup.md §7

VSCode clangd shows red squigglies everywhere

.clangd config missing or wrong compilation database path

02_vscode_config.md §4

Every one of these has bitten India-based C++ learners on Apple Silicon in the last three years. All are one-line fixes when you know where to look.

9. Maintenance rhythm

  • Weekly: brew update && brew upgrade on a Saturday. Takes 5 min.

  • Monthly: brew cleanup to reclaim disk. Takes 1 min.

  • Quarterly: Re-verify clang++ --version is still ≥ the version specified in your project’s CMakeLists.txt cmake_minimum_required and target_compile_features lines.

  • Yearly: After a macOS major update, run xcode-select --install again to refresh CLT.

10. Next step

Start with 01_day1_macos_setup.md. Do the full sequence in one sitting. Do not context-switch. Do not do it in parallel with a real project — a clean run of the Day-1 sequence is a small, contained deliverable that gives you a working environment as a single unit.