Proper Linux compiler support/documentation

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -42,7 +42,7 @@ body:
     validations: { required: true }
     attributes:
       label: CMake Version
-      description: Output of `cmake --version` (must be ≥ 3.20).
+      description: Output of `cmake --version` (must be ≥ 3.25).
       placeholder: "3.28.1"
   - type: dropdown
     id: consumption

.github/actions/setup-sdk-deps/action.yml

@@ -43,25 +43,37 @@ runs:
         fi
         sudo apt-get update
         sudo apt-get install -y \
-          build-essential cmake ninja-build pkg-config \
-          llvm-dev libclang-dev clang \
+          build-essential cmake ninja-build pkg-config git git-lfs curl \
           libva-dev libdrm-dev libgbm-dev libx11-dev libgl1-mesa-dev \
           libxext-dev libxcomposite-dev libxdamage-dev libxfixes-dev \
           libxrandr-dev libxi-dev libxkbcommon-dev \
           libasound2-dev libpulse-dev \
-          libssl-dev \
-          libprotobuf-dev protobuf-compiler \
-          libabsl-dev \
-          libcurl4-openssl-dev \
+          libglib2.0-dev libssl-dev libcurl4-openssl-dev \
           libwayland-dev libdecor-0-dev \
+          wget ca-certificates gnupg lsb-release \
           "${extra_packages[@]}"
 
-    # libwebrtc ships hermetic libc++ headers that require a newer clang than
-    # Ubuntu provides. The submodule script exports CC/CXX for later steps.
-    - name: Install clang for libwebrtc
+    - name: Install Clang 21
       if: runner.os == 'Linux'
       shell: bash
-      run: client-sdk-rust/.github/scripts/install-clang.sh
+      run: |
+        set -eux
+        sudo install -m 0755 -d /etc/apt/keyrings
+        wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key \
+          | sudo tee /etc/apt/keyrings/llvm.asc >/dev/null
+        sudo chmod a+r /etc/apt/keyrings/llvm.asc
+        codename=$(lsb_release -cs)
+        echo "deb [signed-by=/etc/apt/keyrings/llvm.asc] http://apt.llvm.org/${codename}/ llvm-toolchain-${codename}-21 main" \
+          | sudo tee /etc/apt/sources.list.d/llvm-21.list >/dev/null
+        sudo apt-get update
+        sudo apt-get install -y clang-21
+
+        source scripts/setup-linux-toolchain.sh
+        {
+          echo "CC=$CC"
+          echo "CXX=$CXX"
+          echo "LIBCLANG_PATH=$LIBCLANG_PATH"
+        } >> "$GITHUB_ENV"
 
     - name: Install base deps (macOS)
       if: runner.os == 'macOS'

.github/workflows/builds.yml

@@ -157,9 +157,6 @@ jobs:
         run: |
           echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
           echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
-          LLVM_ROOT="$(dirname "${CXX}")/.."
-          test -f "${LLVM_ROOT}/lib/libclang.so"
-          echo "LIBCLANG_PATH=${LLVM_ROOT}/lib" >> "$GITHUB_ENV"
 
       # ---------- Build ----------
       - name: Build standard SDK

.github/workflows/ci.yml

@@ -46,6 +46,7 @@ jobs:
               - CMakePresets.json
               - build*
               - .build*
+              - scripts/setup-linux-toolchain.sh
               - vcpkg.json
               - .github/workflows/ci.yml
               - .github/workflows/builds.yml
@@ -68,6 +69,7 @@ jobs:
               - cmake/**
               - scripts/set-test-tokens.sh
               - scripts/run-with-backtrace.sh
+              - scripts/setup-linux-toolchain.sh
               - CMakeLists.txt
               - CMakePresets.json
               - build*

.github/workflows/make-release.yml

@@ -165,9 +165,6 @@ jobs:
         run: |
           echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
           echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
-          LLVM_ROOT="$(dirname "${CXX}")/.."
-          test -f "${LLVM_ROOT}/lib/libclang.so"
-          echo "LIBCLANG_PATH=${LLVM_ROOT}/lib" >> "$GITHUB_ENV"
 
       # ---------- Build both variants in the same CMake tree ----------
       - name: Build standard SDK

.github/workflows/tests.yml

@@ -295,9 +295,6 @@ jobs:
         run: |
           echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
           echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
-          LLVM_ROOT="$(dirname "${CXX}")/.."
-          test -f "${LLVM_ROOT}/lib/libclang.so"
-          echo "LIBCLANG_PATH=${LLVM_ROOT}/lib" >> "$GITHUB_ENV"
 
       - name: Configure Unix crash diagnostics
         if: runner.os != 'Windows'
@@ -585,11 +582,9 @@ jobs:
       # ---------- Build environment setup ----------
       - name: Set build environment
         run: |
-          LLVM_ROOT="$(dirname "${CXX}")/.."
-          test -f "${LLVM_ROOT}/lib/libclang.so"
-          LLVM_COV="${LLVM_ROOT}/bin/llvm-cov"
+          test -d "${LIBCLANG_PATH}"
+          LLVM_COV="$(dirname "$(readlink -f "${CXX}")")/llvm-cov"
           test -x "${LLVM_COV}"
-          echo "LIBCLANG_PATH=${LLVM_ROOT}/lib" >> "$GITHUB_ENV"
           echo "GCOV_EXECUTABLE=${LLVM_COV} gcov" >> "$GITHUB_ENV"
 
       # ---------- Configure with upstream preset + coverage flag overrides ----------

AGENTS.md

@@ -145,7 +145,16 @@ the source tree. Track capture Rust sources and shaders in build dependencies.
 The build scripts pass an explicit job count to `cmake --build --parallel`. Set
 `CMAKE_BUILD_PARALLEL_LEVEL` to override the default detected logical CPU count.
 
-**Requirements:** CMake 3.20+, C++17, Rust toolchain (cargo), protoc. On macOS: `brew install cmake ninja protobuf abseil`. On Linux: see the CI workflow for apt packages. spdlog is vendored automatically via FetchContent (or vcpkg on Windows) to avoid system conflicts.
+**Requirements:** CMake 3.25+, C++17, Rust toolchain (cargo), protoc. Linux
+source builds require clang/clang++ 21+ and a matching libclang runtime;
+`build.sh` sources `scripts/setup-linux-toolchain.sh` to discover versioned
+installations and validate the toolchain. Source that script before direct
+Linux CMake usage. The build script rejects stale build directories configured
+with another compiler. macOS builds use Xcode Apple Clang selected through
+`xcrun`. On macOS:
+`brew install cmake ninja protobuf abseil`. On Linux: see `docs/building.md`
+and the CI workflow for apt packages. spdlog is vendored automatically via
+FetchContent (or vcpkg on Windows) to avoid system conflicts.
 
 ### SDK Packaging
 
@@ -357,6 +366,8 @@ malformed table, missing `@param` on a documented function, …) fails the build
 | GStreamer | Capture builds / runtime | System libraries and plugins; accessed through Rust; not redistributed in SDK bundles |
 | Google Test | Test only | FetchContent in `src/tests/CMakeLists.txt` |
 
+When a dependency is added, removed, upgraded, or used differently, update the
+Dependencies table in `docs/building.md` in the same change.
 When adding a new private/vendored dependency to this table, also add a
 forbidden symbol pattern for it to
 `.github/scripts/check_no_private_symbols.py` so the "Symbol leak check"

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.20)
+cmake_minimum_required(VERSION 3.25)
 
 if(NOT DEFINED LIVEKIT_VERSION OR LIVEKIT_VERSION STREQUAL "")
   set(LIVEKIT_VERSION "0.0.0")

CMakePresets.json

@@ -2,7 +2,7 @@
   "version": 6,
   "cmakeMinimumRequired": {
     "major": 3,
-    "minor": 20,
+    "minor": 25,
     "patch": 0
   },
   "configurePresets": [

README.md

@@ -35,7 +35,7 @@ Use this SDK to add realtime video, audio and data features to your C++ app. By
 
 ## Using the SDK
 
-[CMake](https://cmake.org/) (≥ 3.20) is used for building the SDK itself and for consuming it as a library. The
+[CMake](https://cmake.org/) (≥ 3.25) is used for building the SDK itself and for consuming it as a library. The
 [**cpp-example-collection**](https://github.com/livekit-examples/cpp-example-collection) contains a reference [LiveKitSDK.cmake](https://github.com/livekit-examples/cpp-example-collection/blob/main/cmake/LiveKitSDK.cmake)
 which downloads the latest stable release at CMake configure time. See [docs/building.md](docs/building.md) for additional documentation on integrating LiveKit into your project.
 

benchmarks/data_track_throughput/CMakeLists.txt

@@ -4,7 +4,7 @@
 # All paths are relative to CMAKE_CURRENT_SOURCE_DIR so this directory
 # can be moved or renamed freely.
 
-cmake_minimum_required(VERSION 3.20)
+cmake_minimum_required(VERSION 3.25)
 project(DataTrackThroughput LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 17)

benchmarks/data_track_throughput/README.md

@@ -125,7 +125,7 @@ One row per received frame. Raw observation data only:
 
 ## Prerequisites
 
-- CMake 3.20+
+- CMake 3.25+
 - C++17 compiler
 - The LiveKit C++ SDK, built and installed (see below)
 

build.sh

@@ -27,6 +27,28 @@ detect_os() {
 
 OS_TYPE="$(detect_os)"
 
+configure_macos_toolchain() {
+  if ! command -v xcrun >/dev/null 2>&1; then
+    echo "ERROR: xcrun is unavailable. Install Xcode Command Line Tools." >&2
+    exit 1
+  fi
+
+  CC="$(xcrun --find clang)"
+  CXX="$(xcrun --find clang++)"
+  export CC CXX
+
+  echo "==> macOS compiler: $("${CXX}" --version | awk 'NR == 1 { print; exit }')"
+  echo "==> CC=${CC}"
+  echo "==> CXX=${CXX}"
+}
+
+configure_build_toolchain() {
+  case "${OS_TYPE}" in
+    linux) source "${PROJECT_ROOT}/scripts/setup-linux-toolchain.sh" ;;
+    macos) configure_macos_toolchain ;;
+  esac
+}
+
 usage() {
   cat <<EOF
 Usage:
@@ -94,6 +116,22 @@ validate_capture_value() {
   done
 }
 
+canonicalize_path() {
+  local path="$1"
+  local resolved directory
+
+  if resolved="$(readlink -f "${path}" 2>/dev/null)" && [[ -n "${resolved}" ]]; then
+    printf '%s\n' "${resolved}"
+    return
+  fi
+
+  if directory="$(cd "$(dirname "${path}")" 2>/dev/null && pwd -P)"; then
+    printf '%s/%s\n' "${directory}" "$(basename "${path}")"
+  else
+    printf '%s\n' "${path}"
+  fi
+}
+
 parse_opts() {
   shift || true
   while [[ $# -gt 0 ]]; do
@@ -174,6 +212,26 @@ parse_opts() {
 }
 
 configure() {
+  if [[ -f "${BUILD_DIR}/CMakeCache.txt" ]]; then
+    local cached_cc cached_cxx selected_cc selected_cxx
+    cached_cc="$(awk -F= '$1 == "CMAKE_C_COMPILER:FILEPATH" { print $2; exit }' \
+      "${BUILD_DIR}/CMakeCache.txt")"
+    cached_cxx="$(awk -F= '$1 == "CMAKE_CXX_COMPILER:FILEPATH" { print $2; exit }' \
+      "${BUILD_DIR}/CMakeCache.txt")"
+    selected_cc="$(canonicalize_path "${CC}")"
+    selected_cxx="$(canonicalize_path "${CXX}")"
+    if [[ -n "${cached_cc}" && "$(canonicalize_path "${cached_cc}")" != "${selected_cc}" ]] \
+      || [[ -n "${cached_cxx}" && "$(canonicalize_path "${cached_cxx}")" != "${selected_cxx}" ]]; then
+      echo "ERROR: ${BUILD_DIR} was configured with a different compiler:" >&2
+      echo "  cached CC=${cached_cc}" >&2
+      echo "  cached CXX=${cached_cxx}" >&2
+      echo "  selected CC=${CC}" >&2
+      echo "  selected CXX=${CXX}" >&2
+      echo "Run './build.sh clean' and retry." >&2
+      exit 1
+    fi
+  fi
+
   echo "==> Configuring CMake (${BUILD_TYPE}) using preset ${PRESET}..."
   local -a extra_args=("-DLIVEKIT_CAPTURE=${CAPTURE_OVERRIDE}")
   if [[ -n "${LIVEKIT_VERSION}" ]]; then
@@ -351,6 +409,8 @@ clean() {
     else
       echo "      (skipping) Unknown build system or not configured"
     fi
+    rm -f "${debug_dir}/CMakeCache.txt"
+    rm -rf "${debug_dir}/CMakeFiles"
   else
     echo "   (skipping) build-debug does not exist."
   fi
@@ -365,6 +425,8 @@ clean() {
     else
       echo "      (skipping) Unknown build system or not configured"
     fi
+    rm -f "${release_dir}/CMakeCache.txt"
+    rm -rf "${release_dir}/CMakeFiles"
   else
     echo "   (skipping) build-release does not exist."
   fi
@@ -400,6 +462,11 @@ fi
 
 cmd="$1"
 parse_opts "$@"
+case "${cmd}" in
+  debug|debug-examples|debug-tests|debug-all|release|release-examples|release-tests|release-all|build-all)
+    configure_build_toolchain
+    ;;
+esac
 case "${cmd}" in
   debug)
     BUILD_TYPE="Debug"