Pinned dependencies

Every version the course depends on is pinned in one place per ecosystem:

Pin	Where	Current value	How it is enforced
CMake minimum	PEBBLE_PIN_CMAKE_MINIMUM in cmake/PebbleDependencies.cmake	3.25	cmake_minimum_required in the top-level CMakeLists.txt
C++ standard	PEBBLE_PIN_CXX_STANDARD	23	CMAKE_CXX_STANDARD, cxx_std_23 on every target
LLVM major	PEBBLE_PIN_LLVM_MAJOR	23	Hard error if the LLVM that was found isn't 23.x
LLVM verified version	PEBBLE_PIN_LLVM_VERSION	23.1.2	Warning if the LLVM found is older
Clang on macOS	PEBBLE_PIN_CLANG_MIN_MAJOR	23	Hard error for Apple clang, or for Homebrew clang older than this
GoogleTest	PEBBLE_PIN_GTEST_VERSION / _GIT_TAG	1.17.0 / v1.17.0	Fetched with FetchContent if no compatible install is found
GoogleTest minimum installed	PEBBLE_PIN_GTEST_MIN_VERSION	1.14 (Ubuntu 24.04's)	FIND_PACKAGE_ARGS
Python minimum	PEBBLE_PIN_PYTHON_MIN	3.11	find_package(Python3 3.11 REQUIRED)
lit	pyproject.toml (+ uv.lock)	lit==23.1.2	Checked at configure time; warning with the uv sync command to fix it
PyYAML	pyproject.toml (+ uv.lock)	PyYAML==6.0.2	Same; a different patch release in the same series (6.0.x) is accepted
Website tools	pyproject.toml group site (+ uv.lock)	mkdocs 1.6.x, mkdocs-material 9.x, pymdown-extensions	Exact versions locked in uv.lock; ./course doctor checks .venv matches the lock
Every other Python package	uv.lock	exact versions + hashes	uv sync installs exactly the lock; CI runs uv sync --locked
Devcontainer / CI LLVM	.devcontainer/devcontainer.json (LLVM_MAJOR), .github/workflows/ci.yml (LLVM_MAJOR)	23	CI fails if llvm-config --version isn't 23.x

What the build does with the pins

• LLVM: the build first runs find_package(LLVM 23.1 CONFIG), then checks LLVM_VERSION_MAJOR. It asks for 23.1 rather than 23 because LLVMConfigVersion.cmake only accepts requests whose major.minor match. Asking for 23 would reject 23.1.x, and LLVM releases are always numbered X.1.y.
• GoogleTest: FetchContent_Declare(GTest ... FIND_PACKAGE_ARGS 1.14 CONFIG). An installed GoogleTest (Homebrew googletest, apt libgtest-dev) is used when one exists. Otherwise the pinned tag is downloaded. Configure with -DPEBBLE_FETCH_GTEST=OFF to forbid downloads, for example on offline machines.
• Python: managed by uv. pyproject.toml declares the dependencies (lit, PyYAML; dependency groups site for the website and dev, both installed by default) and uv.lock pins every package exactly, with hashes. uv sync creates .venv/ at the repository root; CMake prefers it, and looks for lit in .venv/bin, then next to the Python interpreter, then on PATH. cmake --build build/<preset> --target setup-venv runs uv sync. ./course re-executes itself through uv run --project <repo> unless it already runs in .venv (or COURSE_NO_UV=1 is set, for environments you manage yourself).
• Install uv: macOS brew install uv; Linux curl -LsSf https://astral.sh/uv/install.sh | sh (or pipx install uv). ./course doctor checks that uv is present, that uv.lock matches pyproject.toml, and that .venv matches uv.lock.
• Record: each configure run writes build/<preset>/pebble-env.txt. It's a key=value file with the resolved compiler, LLVM version and paths, the tool paths (opt, FileCheck, …), the lit, PyYAML and GoogleTest versions, the pinned versions, and the selected solutions. ./course doctor reads it.

Bumping a pin

1. Edit the value in cmake/PebbleDependencies.cmake. For Python packages, edit pyproject.toml, run uv lock (or uv lock --upgrade-package <name> to move one locked package), then uv sync, and commit both pyproject.toml and uv.lock.
2. For a new LLVM major, also update:
3. LLVM_MAJOR in .github/workflows/ci.yml and .devcontainer/devcontainer.json, plus the ARG default in .devcontainer/Dockerfile
4. the paths in docs/setup/*.md (/usr/lib/llvm-NN)
5. docs/PROPOSAL.md §4
6. lit==NN.x in pyproject.toml (then uv lock)

Then rebuild everything with PEBBLE_USE_SOLUTION=all and fix API breakage. The plugin API in llvm/Plugins/PassPlugin.h and the pass-manager signatures are the usual suspects. 3. For GoogleTest, update both PEBBLE_PIN_GTEST_VERSION and PEBBLE_PIN_GTEST_GIT_TAG. 4. Delete the build directories: CMake caches tool paths such as PEBBLE_FILECHECK and PEBBLE_LIT. Then run CI. The macOS job is the release gate.