Proper Linux compiler support/documentation by alan-george-lk · Pull Request #303 · livekit/client-sdk-cpp

alan-george-lk · 2026-10-28T20:05:34Z

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

Co-authored-by: Cursor <cursoragent@cursor.com>

alan-george-lk · 2026-10-30T18:14:20Z

+    - name: Install Clang 21
      if: runner.os == 'Linux'
      shell: bash
-      run: client-sdk-rust/.github/scripts/install-clang.sh


Context: this one upstream downloads a ton more than we need, this was taking a few minutes in CI. The below list is the subset of things we need. I may advocate for moving the upstream script to do this eventually

alan-george-lk · 2026-10-30T18:15:03Z


 ## Prerequisites

-### Common to all platforms


I spent a lot of time by hand reorganizing and adding things here, this diff is rough, probably easiest to just render the markdown and read through the new flow

alan-george-lk · 2026-10-30T18:15:52Z

-discovers libclang from the system paths once `libclang-dev` is installed; if
-not, point `LIBCLANG_PATH` at your LLVM's `lib` directory (e.g.
-`/usr/lib/llvm-18/lib` on Ubuntu 24.04).
+On Linux, install `clang-21` as shown above. Rust bindgen uses libclang to


This was an AI change, feels a bit chatty, open to adjusting

alan-george-lk · 2026-10-30T18:17:00Z

 `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


Should we just point AGENTS.md at building.md (or more generally point it at our repo docs) to save duplication/diverging risk here?

devin-ai-integration

Devin Review found 4 potential issues.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

devin-ai-integration · 2026-10-30T18:20:24Z

configure

+  CC="$(xcrun --find clang)"
+  CXX="$(xcrun --find clang++)"
+  export CC CXX


🔴 Existing macOS builds retain Homebrew Clang

With a macOS build tree configured using Homebrew Clang, configure_macos_toolchain reports Apple Clang but builds with Homebrew Clang. CMake retains cached compiler paths, and the new cache guard covers Linux only.

Learn more

CMake fixes compiler selection when it first configures a build tree. Exporting CC and CXX later does not change the cached CMAKE_C_COMPILER and CMAKE_CXX_COMPILER. The new macOS selection therefore applies only to fresh trees, although existing trees remain supported by the build script.

Example: Configure build-release with Homebrew clang++, then run ./build.sh release. The script prints Xcode clang++, but CMake reuses Homebrew clang++.

Recommended fix: Apply the cached-compiler comparison in configure on macOS as well as Linux, or explicitly recreate a mismatched CMake build tree before configuring.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-30T18:20:25Z

Set build environment

+        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


🔴 Coverage setup lacks llvm-cov

On Linux coverage runs, LLVM_COV resolves beside clang-21, but setup-sdk-deps installs only clang-21. llvm-cov requires its separate LLVM package, so the coverage job stops before configuring.

Learn more

The coverage workflow locates llvm-cov beside the resolved C++ compiler and asserts that it is executable in Set build environment. The new setup action installs clang-21 but not the matching LLVM tool package containing llvm-cov; the removed installer previously supplied a full toolchain. This prevents coverage builds from starting even though ordinary builds have a compiler.

Example: On a fresh Ubuntu runner with clang-21 installed, coverage resolves CXX to /usr/bin/clang++-21 and checks /usr/lib/llvm-21/bin/llvm-cov, which is absent without llvm-21.

Recommended fix: Install the package providing llvm-cov-21 in the shared Linux setup action (or specifically in coverage), and resolve the versioned tool explicitly.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-30T18:20:27Z

setup-sdk-deps

+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  echo "ERROR: This script must be sourced so it can export the compiler environment:" >&2
+  echo "  source scripts/setup-linux-toolchain.sh" >&2
+  exit 1


🟡 Toolchain changes skip build and test CI

A PR changing only setup-linux-toolchain.sh skips build and test jobs because neither ci.yml filter includes it. Both jobs source this script, leaving compiler selection changes untested.

Learn more

The reusable build and test jobs both consume this script through setup-sdk-deps, and build.sh sources it for local builds. CI only starts those expensive jobs when the corresponding path filters match changed files. Neither filter includes this new build script.

Example: A follow-up PR changes the compiler discovery loop but no other files; the builds and tests workflows are skipped.

Recommended fix: Add scripts/setup-linux-toolchain.sh to both builds and tests filters in ci.yml, following the repository's rule for new build scripts.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-10-30T18:20:28Z

+  llvm_root="$(cd "$(dirname "${resolved_cxx}")/.." && pwd -P)"
+  libclang_dir="$(livekit_find_libclang_dir "${llvm_root}" "${cxx_major}")" || return 1


🟡 Symlinked Clang installations fail discovery

When CXX is a symlink to Clang under a custom LLVM prefix, livekit_select_linux_clang_pair searches beside the symlink. It misses the matching libclang beside the real compiler and rejects a valid toolchain.

Learn more

The script accepts user-supplied CC/CXX, including executables found through PATH. For a custom compiler exposed through a symlink, the resolved executable path still names the symlink rather than its destination. Computing llvm_root from that path points at the symlink's parent, not the compiler installation, so libclang discovery fails despite a complete LLVM install.

Example: /usr/local/bin/clang++ links to /opt/llvm-21/bin/clang++, with libclang in /opt/llvm-21/lib. With CC and CXX set to the /usr/local/bin links, the script searches /usr/local/lib and /usr/lib/llvm-21/lib and rejects the pair.

Recommended fix: Canonicalize the executable paths before deriving llvm_root, while retaining the selected compiler identity for CMake cache comparison.

Was this helpful? React with 👍 or 👎 to provide feedback.

xianshijing-lk

lgtm, some nits

xianshijing-lk · 2026-10-30T20:38:28Z

-# Pull Git LFS assets if you want to run the integration tests:
-git lfs pull
-```
+<a id="additional-capture-dependencies"></a>


should this be part of the ### GStreamer Installation (LiveKit Capture) or under it ?

xianshijing-lk · 2026-10-30T20:40:58Z

 generator doesn't produce `compile_commands.json`. The Ninja generator does;
 see [tools.md](tools.md).

-### How do I deep-clean?


should we keep this ?
together with

./build.sh clean-all # C++ + Rust + local-install + generated files

xianshijing-lk · 2026-10-30T20:42:39Z


 OS_TYPE="$(detect_os)"

+configure_macos_toolchain() {


just want to make sure, is this needed for this linux clang thing?

or some other improvement ?

and it seems configure_macos_toolchain() unconditionally overwrites CC/CXX with the xcrun paths, whereas the Linux path honors pre-set CC/CXX (setup-linux-toolchain.sh:70-79).

xianshijing-lk · 2026-10-30T20:51:09Z

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


can you check check .github/workflows/cpp-tools.yml to see if we need to make any change there ? as we are using clang 21 on linux now

alan-george-lk and others added 3 commits October 28, 2026 12:58

Initial linux compiler fix

c6b24e6

Additional script cleanup and documentation updates

078ed9c

Co-authored-by: Cursor <cursoragent@cursor.com>

Fix Linux CI libclang path handling

9f41d97

Co-authored-by: Cursor <cursoragent@cursor.com>

alan-george-lk mentioned this pull request Oct 29, 2026

livekit_capture integration livekit/ros-portal#74

Merged

alan-george-lk added 2 commits October 30, 2026 10:47

Update cmake version

14b2ef1

Add dependency table

a9b98b0

alan-george-lk commented Oct 30, 2026

View reviewed changes

alan-george-lk marked this pull request as ready for review October 30, 2026 18:19

alan-george-lk requested review from a team and xianshijing-lk as code owners October 30, 2026 18:19

Fix docs

6cb4a4a

devin-ai-integration Bot reviewed Oct 30, 2026

View reviewed changes

xianshijing-lk approved these changes Oct 30, 2026

View reviewed changes

		llvm_root="$(cd "$(dirname "${resolved_cxx}")/.." && pwd -P)"
		libclang_dir="$(livekit_find_libclang_dir "${llvm_root}" "${cxx_major}")" \|\| return 1

Conversation

alan-george-lk commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

xianshijing-lk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alan-george-lk commented Oct 28, 2026 •

edited

Loading