Setup

Two toolchains, kept apart: LLVM 17 for book exercises and a current-main checkout for contribution work.

These commands are starting recipes to verify on your own machine, not recorded results. Check current requirements in R4 and R5 before configuring.

Version discipline

Use LLVM 17 and matching archived documentation for book exercises. Use a separate current llvm-project main checkout for contributions. Record its commit SHA and check current build requirements; the book’s minimum compiler versions are historical.

Keep separate builds and explicit executable paths. Do not mix headers, libraries or plugins across versions. Reproduce proposed upstream bugs on current main.

Toolchain	Days	Use it for
Host C++ compiler	3–6	Building the toy expression frontend
LLVM 17	1, 2, 7–12	Book exercises, IR experiments, the toy frontend’s IR generation (bound to the LLVM 17 CMake package)
Current main (`build/bin/clang++`)	2, 7, 12–30	Clang source work, AST dumps, lit tests and anything you report or submit upstream

Build setup for the contribution track

The recipe assumes a Unix-like shell and installed Git, CMake, Ninja, Python and a host C++ compiler satisfying the current LLVM requirements in R4. Start in your development directory. On Ubuntu, install the required development packages through your package manager; on macOS, use a working Xcode Command Line Tools installation and the needed build tools. Verify current minimum versions before configuring. Do not overwrite the system compiler.

Current-main Clang build

git clone https://github.com/llvm/llvm-project.git llvm-main
cd llvm-main
git rev-parse HEAD
cmake -S llvm -B build -G Ninja \
  -DLLVM_ENABLE_PROJECTS=clang \
  -DLLVM_TARGETS_TO_BUILD=Native \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  -DLLVM_PARALLEL_LINK_JOBS=1
cmake --build build --target clang --parallel 2
build/bin/clang++ --version
cmake --build build --target check-clang --parallel 2

Native limits target backends to the host architecture; cross-target tests may be unsupported. Start with two build jobs and one link job, then adjust to available RAM. Release with assertions is a practical first build. For day 19, use a separate RelWithDebInfo build with assertions, or another locally appropriate debug configuration; expect higher disk and memory use.

As a planning allowance, reserve tens of gigabytes and preferably around 60–100 GB free for source and multiple builds; actual usage varies substantially. A 16 GB machine can require conservative parallelism; more memory is helpful. These are planning estimates, not official minimums.

Maintain a reproducibility note

Record the checkout SHA, CMake command, host compiler, generated compiler version, target, relevant environment settings and exact test commands. The contribution compiler is build/bin/clang++, not whichever clang++ happens to be first on PATH. Keep your exercises outside the upstream checkout.

For a book source build, use a separate LLVM 17 checkout pinned to the release or patch version you actually use, plus a separate build directory. Do not reuse main’s CMake cache. Match LLVM_DIR in your toy project to that LLVM 17 installation’s lib/cmake/llvm directory. Begin with packaged LLVM 17 tools for book work if a second source build is too costly.

Commands for compiler exploration

Set CXX to an explicit compiler path: your LLVM 17 clang++ for book experiments, or the current-main build for upstream work. Use these on a small sample.cpp you wrote yourself.

Compiler pipeline (day 1 and later)

CXX=/absolute/path/to/clang++
"$CXX" --version
"$CXX" -std=c++17 -E sample.cpp -o sample.ii
"$CXX" -std=c++17 -S -emit-llvm sample.cpp -o sample.ll
"$CXX" -std=c++17 -S sample.cpp -o sample.s
"$CXX" -std=c++17 -c sample.cpp -o sample.o
"$CXX" -std=c++17 -Xclang -ast-dump \
  -fsyntax-only sample.cpp

For LLVM 17 IR exercises, choose the bin directory containing matching llvm-as and opt. Verification and optimization are separate operations; emitted IR may contain optnone when generated without optimization. Prefer handwritten IR for the first optimization experiment, or deliberately select an appropriate compiler optimization setting.

LLVM 17 IR tools

LLVM17_BIN=/absolute/path/to/llvm17/bin
"$LLVM17_BIN/llvm-as" example.ll -o example.bc
"$LLVM17_BIN/opt" -passes=verify \
  -disable-output example.bc
"$LLVM17_BIN/opt" -S -passes='default<O1>' \
  example.ll -o optimized.ll

Troubleshooting

Configuration rejects the host compiler: Use a recent supported host compiler (see R4) instead of overwriting the system compiler.
The machine runs out of memory during the build: Lower parallelism (--parallel and LLVM_PARALLEL_LINK_JOBS) before adding projects or targets. Reuse Ninja’s incremental build rather than starting over.
A long first build is not finished: Let it continue in the background; a successful configure is enough for day 2. On day 7, finish it or record the first build blocker and a specific recovery step.
Link errors or odd behavior in the toy project: Suspect a version mix. Confirm llvm-config --version and that LLVM_DIR points at the LLVM 17 installation, not main.
Some lit tests report unsupported: With Native targets, cross-target tests may be unsupported. Record them separately; do not treat an unsupported test as passing coverage.
Debug symbols or memory block debugging on day 19: Trace the same path manually, record the limitation and schedule a narrow debug build.
Disk space runs low: Plan for tens of gigabytes, preferably 60–100 GB free, across source and multiple build directories.