Building

This document covers everything you need to build the LiveKit C++ SDK from source: prerequisites, cloning the repository, the build scripts, advanced CMake/vcpkg flows, and Docker.

Prerequisites

Common to all platforms

CMake ≥ 3.20
Rust / Cargo — latest stable toolchain (for building the Rust FFI layer). Install via rustup.
Git LFS — required for examples that pull test media assets.
Protobuf ≥ 5.29
Abseil — always required (used by Protobuf 5.x+)

Platform-specific toolchains

Platform	Compiler	Package manager
Windows	Visual Studio 2019+ (MSBuild or Ninja)	vcpkg (see below)
Linux	GCC 9+ or Clang 10+	`apt` / `dnf` (or vcpkg)
macOS	Xcode 12+ (macOS 12.3+ for ScreenCaptureKit)	Homebrew (or vcpkg)

Clone the repository

The SDK depends on the client-sdk-rust submodule (recursive), so always clone with submodules:

# Option 1: clone with submodules in one step
git clone --recurse-submodules https://github.com/livekit/client-sdk-cpp.git

# Option 2: clone first, then initialize submodules
git clone https://github.com/livekit/client-sdk-cpp.git
cd client-sdk-cpp
git submodule update --init --recursive

# Pull Git LFS assets if you want to run the integration tests:
git lfs pull

Recommended setup

These are the exact packages our CI uses. They will also work for examples.

macOS

brew install cmake ninja protobuf abseil rust

Ubuntu / Debian

sudo apt update && sudo apt install -y \
  build-essential cmake ninja-build pkg-config \
  llvm-dev libclang-dev clang \
  libprotobuf-dev protobuf-compiler libabsl-dev \
  libssl-dev

# Install Rust if you don't already have it
curl https://sh.rustup.rs -sSf | sh

If you plan to build the example collection (SDL-based renderer + camera/mic capture), also install:

sudo apt install -y \
  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 \
  libwayland-dev libdecor-0-dev

Windows

# Set VCPKG_ROOT once and bootstrap vcpkg
git clone https://github.com/microsoft/vcpkg.git
.\vcpkg\bootstrap-vcpkg.bat
$env:VCPKG_ROOT = "$PWD\vcpkg"

CMake's vcpkg manifest mode (below) reads vcpkg.json and installs the rest automatically the first time you configure.

Build scripts (recommended)

The repo ships with build.sh (Linux/macOS) and build.cmd (Windows) that wrap the right CMake preset for your platform and pick sensible defaults.

Linux/macOS:

./build.sh release            # Build Release
./build.sh debug              # Build Debug
./build.sh release-examples   # Release + examples
./build.sh debug-examples     # Debug + examples
./build.sh release-tests      # Release + tests
./build.sh debug-tests        # Debug + tests
./build.sh release-all        # Release + tests + examples
./build.sh debug-all          # Debug + tests + examples
./build.sh clean              # Clean CMake build artifacts + local-install
./build.sh clean-all          # Deep clean (C++ + Rust + local-install + generated files)

Windows:

.\build.cmd release
.\build.cmd debug
.\build.cmd release-examples
# ... same suffixes as build.sh

The build scripts pass an explicit job count to cmake --build --parallel. Set CMAKE_BUILD_PARALLEL_LEVEL to override the auto-detected logical CPU count.

Advanced: CMake presets

For more control, drive CMake directly via the presets in CMakePresets.json:

# Linux
cmake --preset linux-release
cmake --build --preset linux-release

# macOS
cmake --preset macos-release
cmake --build --preset macos-release

# Windows
cmake --preset windows-release
cmake --build --preset windows-release

Windows requires VCPKG_ROOT to be set:

$env:VCPKG_ROOT = "C:\path\to\vcpkg"

Advanced: vcpkg manifest mode

vcpkg will automatically install all dependencies listed in vcpkg.json the first time you configure with its toolchain file.

Windows:

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake
cmake --build build --config Release

# With examples:
cmake -B build -S . `
  -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake `
  -DLIVEKIT_BUILD_EXAMPLES=ON -DVCPKG_MANIFEST_FEATURES=examples
cmake --build build --config Release

Linux/macOS:

cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build

# With examples:
cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DLIVEKIT_BUILD_EXAMPLES=ON -DVCPKG_MANIFEST_FEATURES=examples
cmake --build build

Building with Docker

The Docker setup is split into a reusable base image (toolchain + system deps) and an SDK image layered on top. Tested on Linux only.

docker build -t livekit-cpp-sdk-base . -f docker/Dockerfile.base
docker build --build-arg BASE_IMAGE=livekit-cpp-sdk-base \
  -t livekit-cpp-sdk . -f docker/Dockerfile.sdk
docker run -it --network host livekit-cpp-sdk:latest bash

If you're authoring your own Dockerfile, mirror the ENV block in docker/Dockerfile.base:

export CC=$HOME/gcc-14/bin/gcc
export CXX=$HOME/gcc-14/bin/g++
export LD_LIBRARY_PATH=$HOME/gcc-14/lib64:$LD_LIBRARY_PATH
export PATH=$HOME/.cargo/bin:$PATH
export PATH=$HOME/cmake-3.31/bin:$PATH

CMake options

Option	Default	Description
`LIVEKIT_BUILD_EXAMPLES`	OFF	Build example applications
`LIVEKIT_USE_SYSTEM_PROTOBUF`	OFF	Use system Protobuf instead of vcpkg's
`LIVEKIT_LOG_LEVEL`	`TRACE`	Compile-time log threshold (see logging.md)
`LIVEKIT_VERSION`	repo-derived	SDK version string baked into the binary

Build output

After a successful build:

build-release/
├── lib/
│   ├── liblivekit.{a,lib}          # Main SDK static library
│   ├── liblivekit_ffi.{so,dylib}   # Rust FFI dynamic library
│   └── livekit_ffi.dll, *.lib      # (Windows) FFI DLL + import lib
├── include/                        # Public headers (auto-synced)
│   └── livekit/
└── bin/                            # Example/test executables
    └── liblivekit_ffi.{so,dylib}   # (Linux/macOS: copied for runtime)

Integrating into your project

Using CMake

# Method 1: as a subdirectory
add_subdirectory(path/to/client-sdk-cpp)
target_link_libraries(your_target PRIVATE livekit)

# Method 2: find_package (after install)
find_package(livekit REQUIRED)
target_link_libraries(your_target PRIVATE livekit)

Using prebuilt releases

The easiest way to consume the SDK without building from source is via the cpp-example-collection helper, which downloads a release tarball at CMake configure time:

include(LiveKitSDK.cmake)  # pins or auto-resolves a release

See the example collection's LiveKitSDK.cmake for the full pattern.

Manual linking

Add include path: build-release/include
Link the static SDK library:
- Windows: build-release/lib/livekit.lib
- Linux: build-release/lib/liblivekit.a
- macOS: build-release/lib/liblivekit.a
Link/deploy the Rust FFI dynamic library:
- Windows: link livekit_ffi.dll.lib, deploy livekit_ffi.dll next to your .exe
- Linux: deploy liblivekit_ffi.so next to your executable
- macOS: deploy liblivekit_ffi.dylib next to your executable
Link platform system libraries (see below).

Important: On Linux/macOS the FFI shared library must live next to the executable. RPATH is set to $ORIGIN (Linux) / @loader_path (macOS).

Windows system libraries:

ntdll userenv winmm iphlpapi msdmo dmoguids wmcodecdspuuid
ws2_32 secur32 bcrypt crypt32

macOS frameworks:

CoreAudio AudioToolbox CoreFoundation Security CoreGraphics
CoreMedia VideoToolbox AVFoundation CoreVideo Foundation
AppKit QuartzCore OpenGL IOSurface Metal MetalKit ScreenCaptureKit

Linux libraries:

OpenSSL::SSL OpenSSL::Crypto

Runtime dependencies of prebuilt artifacts

Whether protobuf / abseil / openssl need to be installed on the target machine depends on how the SDK binary was built:

Windows release artifacts use vcpkg triplet x64-windows-static-md — protobuf and abseil are statically linked into the DLLs; no runtime install needed.
macOS release artifacts (from our CI) do not dynamically depend on protobuf / abseil / openssl. You can verify with otool -L liblivekit.dylib.
Linux depends on packaging. Check with ldd liblivekit_ffi.so; if any of those are listed, install the corresponding -dev (build) or runtime package (libprotobuf32 / libabsl / libssl3) as appropriate.

Troubleshooting

Missing proto files or `client-sdk-rust` directory

Initialize submodules:

git submodule update --init --recursive

Deprecated-declaration errors on Linux

Newer GCC versions (12+) are stricter with the WebRTC legacy code in the Rust submodule. If ./build.sh release errors with -Werror=deprecated-declarations, relax it for the build:

export CXXFLAGS="-Wno-deprecated-declarations"
export CFLAGS="-Wno-deprecated-declarations"

Rust bindgen fails with "unable to find libclang"

Install libclang-dev (Ubuntu) or llvm (macOS Homebrew). bindgen normally 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).

Rust code recompiles after C++ edits

This was a historical issue; Rust only recompiles now when Rust source files change or the Rust library is missing.

Cannot find Protobuf or other dependencies

Make sure you're passing the vcpkg toolchain file:

-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

`clang-tidy` on Windows

Not currently supported via our scripts — the Visual Studio (MSBuild) CMake generator doesn't produce compile_commands.json. The Ninja generator does; see tools.md.

How do I deep-clean?

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

Or via CMake targets:

cmake --build build --target clean              # CMake artifacts
cmake --build build --target cargo_clean        # Rust artifacts
cmake --build build --target clean_generated    # Generated protobuf headers
cmake --build build --target clean_all          # Full clean

Support

GitHub Issues: https://github.com/livekit/client-sdk-cpp/issues
LiveKit Docs: https://docs.livekit.io/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Building

Prerequisites

Common to all platforms

Platform-specific toolchains

Clone the repository

Recommended setup

macOS

Ubuntu / Debian

Windows

Build scripts (recommended)

Advanced: CMake presets

Advanced: vcpkg manifest mode

Building with Docker

CMake options

Build output

Integrating into your project

Using CMake

Using prebuilt releases

Manual linking

Runtime dependencies of prebuilt artifacts

Troubleshooting

Missing proto files or `client-sdk-rust` directory

Deprecated-declaration errors on Linux

Rust bindgen fails with "unable to find libclang"

Rust code recompiles after C++ edits

Cannot find Protobuf or other dependencies

`clang-tidy` on Windows

How do I deep-clean?

Support

FilesExpand file tree

building.md

Latest commit

History

building.md

File metadata and controls

Building

Prerequisites

Common to all platforms

Platform-specific toolchains

Clone the repository

Recommended setup

macOS

Ubuntu / Debian

Windows

Build scripts (recommended)

Advanced: CMake presets

Advanced: vcpkg manifest mode

Building with Docker

CMake options

Build output

Integrating into your project

Using CMake

Using prebuilt releases

Manual linking

Runtime dependencies of prebuilt artifacts

Troubleshooting

Missing proto files or client-sdk-rust directory

Deprecated-declaration errors on Linux

Rust bindgen fails with "unable to find libclang"

Rust code recompiles after C++ edits

Cannot find Protobuf or other dependencies

clang-tidy on Windows

How do I deep-clean?

Support

Missing proto files or `client-sdk-rust` directory

`clang-tidy` on Windows