Proper Linux compiler support/documentation (#303)

The C++ SDK silently moved compiler requirements from GCC to Clang 21+ as of release v1.10.1, and this was never announced, properly documented, and scripts were not updated accordingly. As such, a fresh clone of this SDK on Linux did not build out of the box. This PR addresses this alongside documentation, script support, etc.

Notable change overview:

Compiler: gcc -> clang-21
build.sh now properly supports this. After users install the deps, this script now just works
CMake minimum version: 3.20 -> 3.25
Note this was already required before this PR due to the schema version 6 usage in CMakePresets.json, just a documentation gap. All supported platforms in CI were already past this version
Updates docs/building.md with relevant changes and proper dependency table

Author: alan-george-lk

.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.