Skip to content

Setting up on Linux

These steps are tested on Ubuntu 24.04 with LLVM 23 from apt.llvm.org. Other distributions work if you can provide LLVM 23 with its CMake config, clang 23, GoogleTest ≥ 1.14, Ninja, CMake ≥ 3.25 and Python ≥ 3.11.

If you'd rather not install anything, use the dev container.

1. Install LLVM 23 and the tools

wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh
sudo ./llvm.sh 23                        # adds the apt.llvm.org repository + clang-23
sudo apt install clang-23 lld-23 llvm-23-dev llvm-23-tools   # headers, CMake config, FileCheck, not
# Do NOT use `llvm.sh 23 all`: it installs libc++abi-23-dev, whose cxxabi.h sits in the
# LLVM include dir and breaks libstdc++ builds ("conflicting types for __cxa_init_primary_exception").
sudo apt install ninja-build cmake libgtest-dev libgmock-dev \
                 libzstd-dev zlib1g-dev libxml2-dev libedit-dev libcurl4-openssl-dev
sudo apt install libpolly-23-dev         # only if CMake complains about Polly (see troubleshooting)
curl -LsSf https://astral.sh/uv/install.sh | sh    # uv, the Python environment manager (or: pipx install uv)

Check:

/usr/lib/llvm-23/bin/llvm-config --version     # 23.x.y
ls /usr/lib/llvm-23/bin/FileCheck              # comes from the llvm-23-tools package

2. Configure, build, test

uv sync                        # .venv with the pinned lit, PyYAML and website tools (uv.lock)
cmake --preset linux
cmake --build --preset linux
ctest --preset linux

The linux preset uses cmake/toolchains/linux-llvm.cmake. It looks for LLVM and clang in this order:

  • LLVM: -DLLVM_DIR=..., then $LLVM_DIR, then /usr/lib/llvm-23/lib/cmake/llvm.
  • Compiler: $CC/$CXX or -DCMAKE_CXX_COMPILER=... if you set them. Otherwise the clang++-23/clang++ next to that LLVM, then clang++-23 on PATH.

If LLVM is installed somewhere else:

cmake --preset linux -DLLVM_DIR=/opt/llvm-23/lib/cmake/llvm \
                     -DPEBBLE_FILECHECK=/opt/llvm-23/libexec/llvm/FileCheck

GCC 14 can compile the course, but it isn't supported. Use clang 23 so that plugins and LLVM are built by the same compiler.

3. Verify

ctest --preset linux -L infra

infra.lit and infra.TodoTest.* must pass. infra.InfraDemoTest.* fails with TODO(infra) until you build with -DPEBBLE_USE_SOLUTION=infra-demo (or =all). The macOS guide explains this in more detail. The everyday commands are the same as on macOS; replace macos with linux.

Then run ./course doctor.