Tools & Toolchain
This curriculum is C++-only (Track B — LLVM Core). All labs target macOS (Apple Silicon verified) and are portable to Linux with trivial flag changes (noted per-lab).
The full setup, version verification, and why each tool exists is taught in
cp-01-environment-setup/. Do that lab first — even if you already have the tools installed — because it teaches concepts (target triples, sysroots, ELF vs Mach-O, Apple Clang vs upstream LLVM) that you'll need for every subsequent phase.
Required Tools
| Tool | Minimum Version | Where It's Used | Install |
|---|---|---|---|
| Xcode Command Line Tools | (any current) | C++ compiler, linker, system headers (phases 1–4) | xcode-select --install |
| CMake | 3.20+ | Build system for every lab | brew install cmake |
| Ninja | 1.10+ | Fast parallel builder (used in phases 5+) | brew install ninja |
| Homebrew LLVM | 18+ | Full LLVM with headers, libraries, mlir-opt, llc, lli (phases 5+) | brew install llvm |
| lldb | (bundled with Xcode CLT and Homebrew LLVM) | Debugger | already installed |
| git | 2.30+ | Version control | already installed on macOS |
Optional Tools
| Tool | Purpose | Install |
|---|---|---|
| Docker Desktop | Run a Linux container to validate ELF/glibc behavior (Phase 8 FFI optional cross-check) | https://www.docker.com/products/docker-desktop |
| graphviz | Render CFG / dominator-tree dumps as PNGs (Phase 4) | brew install graphviz |
| rr (Linux only) | Time-travel debugger — useful inside Docker for Phase 8 GC debugging | apt in Linux container |
| clang-format | Auto-format C++ (configured per lab) | bundled with both Clang installations |
| gdb | Some people prefer GDB; LLDB ships natively on macOS so we use LLDB | brew install gdb (with caveats on macOS) |
Tool Sets By Phase
| Phase | Need |
|---|---|
| 1–4 | Apple Clang + CMake |
| 5 | + Homebrew LLVM (brew install llvm) + Ninja |
| 6 | same as Phase 5 |
| 7 | same as Phase 5; also requires mlir-opt, mlir-translate (ship with Homebrew LLVM) |
| 8 | same as Phase 5; optional Docker for Linux validation |
| 9 | same as Phase 5 |
Apple Clang vs Homebrew LLVM — Why We Have Both
| Apple Clang | Homebrew LLVM | |
|---|---|---|
| Path | /usr/bin/clang++ | /opt/homebrew/opt/llvm/bin/clang++ |
| Provides | Compiler, linker integration | Compiler + libLLVM.dylib + headers + tools |
| Tools included | clang, clang++, lldb | clang++, llc, opt, llvm-config, mlir-opt, lli, llvm-link |
| Used for | Phases 1–4 (plain C++) | Phases 5–18 (LLVM/MLIR work) |
Why Apple ships its own Clang: Apple uses LLVM internally for the macOS toolchain. Their Clang is patched, tracks Xcode releases, links against the system frameworks, and produces signed binaries. But it does not ship the LLVM C++ libraries or the MLIR tools — those are reserved for the development tools install. We install upstream LLVM via Homebrew to get the missing pieces.
Target Triple (macOS Apple Silicon)
Your default triple is arm64-apple-macosx<version>. This is recorded in every Mach-O binary as the load command LC_BUILD_VERSION. Inspect with:
otool -l <binary> | grep -A5 LC_BUILD_VERSION
This matters in:
- Phase 5: when you ask LLVM to emit object files, you pass this triple.
- Phase 11 and beyond: when you write FFI or assembly intrinsics.
Verification
The full step-by-step verification script lives in cp-01-environment-setup/docs/verification.md. Run it once, before any other lab.