Appendix C — Appendix C: Toolchain Setup

Appendix C: Toolchain Setup

How to get your machine ready to do the work in this book. One-time setup per platform.

C.1 macOS

# Xcode command-line tools (gives you clang++ as g++)
xcode-select --install

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

# Real g++ (Apple's "g++" is actually clang)
brew install gcc

# Static analysis and formatting
brew install llvm
brew install clang-format

# Memory checker
# Note: valgrind has poor macOS support on Apple Silicon.
# Use AddressSanitizer (built into clang/g++) instead.

Verify:

g++ --version          # 13.x or higher
clang-tidy --version
clang-format --version

C.2 Linux (Debian/Ubuntu)

sudo apt update
sudo apt install build-essential g++ clang clang-tidy clang-format valgrind git make

Verify:

g++ --version
clang --version
valgrind --version

C.4 VS Code setup

Recommended extensions:

  • C/C++ (Microsoft) — IntelliSense, debugging.
  • clangd — better autocomplete than the default; install if you want first-class clang integration.
  • CodeLLDB — debugger for Mac/Linux.
  • GitLens — git superpowers.
  • Markdown All in One — for editing the book.
  • vscode-quarto — Quarto preview if you are contributing.

A minimal .vscode/c_cpp_properties.json:

{
  "configurations": [
    {
      "name": "Mac",
      "includePath": ["${workspaceFolder}/**"],
      "compilerPath": "/usr/bin/g++",
      "cStandard": "c17",
      "cppStandard": "c++17",
      "intelliSenseMode": "macos-clang-x64"
    }
  ],
  "version": 4
}

C.5 A starter .clang-format

BasedOnStyle: Google
IndentWidth: 2
TabWidth: 2
UseTab: Never
ColumnLimit: 100
DerivePointerAlignment: false
PointerAlignment: Left
AllowShortFunctionsOnASingleLine: Inline
SortIncludes: true
IncludeBlocks: Preserve

I prefer Google style as a starting point with 2-space indents and 100-column lines. Adjust to taste.

Format a file in place: clang-format -i main.cpp.

C.6 A starter .clang-tidy

Checks: >
  -*,
  bugprone-*,
  cert-*,
  clang-analyzer-*,
  cppcoreguidelines-*,
  modernize-*,
  performance-*,
  readability-*,
  -modernize-use-trailing-return-type,
  -readability-magic-numbers,
  -cppcoreguidelines-avoid-magic-numbers
WarningsAsErrors: ''
HeaderFilterRegex: '.*'

Run: clang-tidy main.cpp -- -std=c++17.

C.7 The starter Makefile

CXX = g++
CXXFLAGS = -Wall -Wextra -Werror -std=c++17 -g
SAN = -fsanitize=address,undefined -fno-omit-frame-pointer

SRCS = $(wildcard *.cpp)
OBJS = $(SRCS:.cpp=.o)
TARGET = main

all: $(TARGET)

$(TARGET): $(OBJS)
    $(CXX) $(CXXFLAGS) $(SAN) $(OBJS) -o $(TARGET)

%.o: %.cpp
    $(CXX) $(CXXFLAGS) $(SAN) -c $< -o $@

format:
    clang-format -i $(SRCS) *.h

tidy:
    clang-tidy $(SRCS) -- -std=c++17

memcheck: $(TARGET)
    ASAN_OPTIONS=detect_leaks=1 ./$(TARGET)

clean:
    rm -f $(OBJS) $(TARGET)

.PHONY: all clean format tidy memcheck

make, make format, make tidy, make memcheck, make clean. Memorize.

C.8 Git basics

# Configure once
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

# Daily workflow
git clone <url>
git status
git add file.cpp
git commit -m "useful message"
git push

# Pull others' changes
git pull

# See history
git log --oneline -10

# Make a feature branch
git checkout -b feature-x
git push -u origin feature-x

C.9 Quarto (for contributing to this book)

# macOS
brew install quarto

# Linux
# Download .deb from https://quarto.org/docs/download/

Then in the book/ directory:

quarto preview          # live-reload HTML preview
quarto render           # build static HTML in _book/
quarto render --to pdf  # produce a PDF (needs LaTeX)

If you do not have LaTeX, install it via TinyTeX:

quarto install tinytex