Skip to content

Commit b87dc87

Browse files
UniFFI C++ Bindgen Initial Integration (#249)
This PR introduces the initial steps for uniffi integration. For this initial integration, a private header/adapter translation unit is added to test the UniFFI build version signature offered by the current livekit-ffi. This approach was taken to: * Not expose this signature in the public header * Not change building or linking behavior to expose the bindings directly to the unit test (better tests the build/link this way anyway) * Allows these internal files to be deleted later once actual critical-path SDK features are moved over to UniFFI
1 parent a31bd0d commit b87dc87

13 files changed

Lines changed: 302 additions & 29 deletions

File tree

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
data/welcome.wav filter=lfs diff=lfs merge=lfs -text
2+
build.cmd whitespace=cr-at-eol

‎.github/scripts/check_no_private_symbols.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
# limitations under the License.
1515
#
1616
"""
17-
Verify that liblivekit's exported ABI does not leak private dependency symbols.
17+
Verify that liblivekit's exported ABI does not leak private implementation symbols.
1818
1919
The LiveKit SDK statically links several private dependencies (spdlog, fmt,
2020
google::protobuf, absl, nlohmann/json). When those symbols escape the dynamic symbol table
@@ -23,6 +23,10 @@
2323
rcl_logging_spdlog ABI-clashing with our vendored spdlog and crashing inside
2424
spdlog::pattern_formatter).
2525
26+
The generated UniFFI C++ bindings are also private implementation details.
27+
Their generated API and runtime symbols must remain hidden behind the SDK's
28+
public ABI.
29+
2630
This script lists exported defined symbols from the supplied shared library
2731
using the platform-appropriate tool and fails (exit code 1) if any of them
2832
match a forbidden pattern.
@@ -53,6 +57,10 @@
5357
"google::protobuf",
5458
"absl::",
5559
"nlohmann::",
60+
# Generated UniFFI C++ binding API and runtime implementation.
61+
"livekit_ffi::",
62+
"uniffi::",
63+
"uniffi_",
5664
]
5765

5866
MAX_REPORTED_LEAKS = 20
@@ -237,7 +245,7 @@ def main(argv: list[str]) -> int:
237245
"(set LIVEKIT_SYMBOL_CHECK_VERBOSE=1 to see all)")
238246

239247
print(
240-
"\nliblivekit must not re-export private dependency symbols.\n"
248+
"\nliblivekit must not re-export private dependency or UniFFI implementation symbols.\n"
241249
"If you intentionally added a public symbol that triggered this, mark\n"
242250
"it with LIVEKIT_API in include/livekit/visibility.h and rebuild.\n"
243251
)

‎.github/workflows/cpp-tools.yml‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -73,23 +73,26 @@ jobs:
7373
sudo apt-get install -y \
7474
build-essential cmake ninja-build pkg-config \
7575
llvm-dev libclang-dev clang \
76-
libssl-dev libcurl4-openssl-dev wget ca-certificates gnupg
76+
libglib2.0-dev libssl-dev libcurl4-openssl-dev \
77+
wget ca-certificates gnupg
7778
78-
- name: Install clang-tidy 19 (for ExcludeHeaderFilterRegex support)
79+
- name: Install clang-tidy 19 and clang 21
7980
run: |
8081
set -eux
8182
# Ubuntu 24.04 apt ships clang-tidy 18, which doesn't understand
8283
# ExcludeHeaderFilterRegex (added in 19). Pull clang-tidy 19 from
83-
# the upstream LLVM apt repository and pin the unversioned names.
84+
# the upstream LLVM apt repository. libwebrtc requires clang 21+.
8485
sudo install -m 0755 -d /etc/apt/keyrings
8586
wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key \
8687
| sudo tee /etc/apt/keyrings/llvm.asc >/dev/null
8788
sudo chmod a+r /etc/apt/keyrings/llvm.asc
8889
codename=$(lsb_release -cs)
8990
echo "deb [signed-by=/etc/apt/keyrings/llvm.asc] http://apt.llvm.org/${codename}/ llvm-toolchain-${codename}-19 main" \
9091
| sudo tee /etc/apt/sources.list.d/llvm-19.list >/dev/null
92+
echo "deb [signed-by=/etc/apt/keyrings/llvm.asc] http://apt.llvm.org/${codename}/ llvm-toolchain-${codename}-21 main" \
93+
| sudo tee /etc/apt/sources.list.d/llvm-21.list >/dev/null
9194
sudo apt-get update
92-
sudo apt-get install -y clang-tidy-19 clang-tools-19
95+
sudo apt-get install -y clang-tidy-19 clang-tools-19 clang-21 libclang-21-dev
9396
sudo ln -sf /usr/bin/clang-tidy-19 /usr/local/bin/clang-tidy
9497
sudo ln -sf /usr/bin/run-clang-tidy-19 /usr/local/bin/run-clang-tidy
9598
clang-tidy --version
@@ -104,15 +107,19 @@ jobs:
104107
run: |
105108
echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
106109
echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
107-
LLVM_VERSION=$(llvm-config --version | cut -d. -f1)
108-
echo "LIBCLANG_PATH=/usr/lib/llvm-${LLVM_VERSION}/lib" >> "$GITHUB_ENV"
110+
echo "CC=/usr/bin/clang-21" >> "$GITHUB_ENV"
111+
echo "CXX=/usr/bin/clang++-21" >> "$GITHUB_ENV"
112+
echo "LIBCLANG_PATH=/usr/lib/llvm-21/lib" >> "$GITHUB_ENV"
109113
110114
- name: Configure compilation database
111115
run: cmake --preset linux-release
112116

113117
- name: Generate protobuf headers
114118
run: cmake --build build-release --target livekit_proto
115119

120+
- name: Generate UniFFI C++ bindings
121+
run: cmake --build build-release --target generate_livekit_ffi_uniffi_cpp
122+
116123
- name: Run clang-tidy
117124
env:
118125
TIDY_BLOB_SHA: ${{ github.event.pull_request.head.sha || github.sha }}

‎AGENTS.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -234,8 +234,9 @@ The exported ABI is enforced by `.github/scripts/check_no_private_symbols.py`,
234234
run from the `make-release.yml` "Symbol leak check" CI step so a leak blocks
235235
the release build itself (it does not run on regular pushes/PRs). The script
236236
fails if `nm`/`dumpbin` reports any exported symbol matching a forbidden
237-
substring (currently `spdlog::`, `fmt::v`, `google::protobuf`, `absl::`). To
238-
run it locally, point it at the built shared library:
237+
substring (including private dependency namespaces and generated UniFFI
238+
symbols such as `livekit_ffi::`, `uniffi::`, and `uniffi_`). To run it locally,
239+
point it at the built shared library:
239240
240241
```bash
241242
python3 .github/scripts/check_no_private_symbols.py \

‎CMakeLists.txt‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ set(FFI_PROTO_FILES
7979
${FFI_PROTO_DIR}/track.proto
8080
${FFI_PROTO_DIR}/video_frame.proto
8181
${FFI_PROTO_DIR}/audio_frame.proto
82+
${FFI_PROTO_DIR}/capture.proto
8283
${FFI_PROTO_DIR}/e2ee.proto
8384
${FFI_PROTO_DIR}/stats.proto
8485
${FFI_PROTO_DIR}/data_stream.proto
@@ -269,6 +270,10 @@ endif()
269270
message(STATUS \"[run_cargo.cmake] CFG=\${CFG} CARGO=\${CARGO} PROTOC=\${PROTOC_PATH}\")
270271
set(ENV{PROTOC} \"\${PROTOC_PATH}\")
271272
273+
if(DEFINED CARGO_TARGET_DIR AND NOT CARGO_TARGET_DIR STREQUAL \"\")
274+
set(ENV{CARGO_TARGET_DIR} \"\${CARGO_TARGET_DIR}\")
275+
endif()
276+
272277
if(DEFINED GCC_LIB_DIR AND NOT GCC_LIB_DIR STREQUAL \"\")
273278
set(ENV{RUSTFLAGS} \"-L \${GCC_LIB_DIR} \$ENV{RUSTFLAGS}\")
274279
set(ENV{LD_LIBRARY_PATH} \"\${GCC_LIB_DIR}:\$ENV{LD_LIBRARY_PATH}\")
@@ -343,13 +348,29 @@ else()
343348
)
344349
endif()
345350

346-
file(GLOB_RECURSE RUST_SOURCES
351+
file(GLOB_RECURSE RUST_SOURCES CONFIGURE_DEPENDS
347352
"${RUST_ROOT}/livekit-ffi/src/*.rs"
353+
"${RUST_ROOT}/livekit-ffi/protocol/*.proto"
354+
"${RUST_ROOT}/livekit-ffi/build.rs"
348355
"${RUST_ROOT}/livekit-ffi/Cargo.toml"
349356
)
357+
list(APPEND RUST_SOURCES
358+
"${RUST_ROOT}/Cargo.toml"
359+
"${RUST_ROOT}/Cargo.lock"
360+
"${RUST_ROOT}/rust-toolchain.toml"
361+
)
362+
363+
set(RUST_BUILD_OUTPUTS
364+
"$<IF:$<CONFIG:Debug>,${RUST_LIB_DEBUG},${RUST_LIB_RELEASE}>"
365+
)
366+
if(WIN32)
367+
list(APPEND RUST_BUILD_OUTPUTS
368+
"$<IF:$<CONFIG:Debug>,${RUST_DLL_DEBUG},${RUST_DLL_RELEASE}>"
369+
)
370+
endif()
350371

351372
add_custom_command(
352-
OUTPUT "${RUST_LIB_DEBUG}" "${RUST_LIB_RELEASE}"
373+
OUTPUT ${RUST_BUILD_OUTPUTS}
353374
COMMAND "${CMAKE_COMMAND}"
354375
-DCFG=$<CONFIG>
355376
-DRUST_ROOT=${RUST_ROOT}
@@ -365,9 +386,11 @@ add_custom_command(
365386
)
366387

367388
add_custom_target(build_rust_ffi
368-
DEPENDS "${RUST_LIB_DEBUG}" "${RUST_LIB_RELEASE}"
389+
DEPENDS ${RUST_BUILD_OUTPUTS}
369390
)
370391

392+
include(uniffi_cpp)
393+
371394
# Note: protozero_plugin.o removal is no longer needed since we use dynamic libraries on Unix
372395

373396
add_library(livekit SHARED
@@ -401,6 +424,7 @@ add_library(livekit SHARED
401424
src/token_source_json.cpp
402425
src/token_source_jwt.cpp
403426
src/token_source_internal.h
427+
src/uniffi_bindgen_adapter.cpp
404428
src/local_participant.cpp
405429
src/remote_participant.cpp
406430
src/stats.cpp
@@ -445,7 +469,14 @@ if(UNIX AND NOT APPLE)
445469
endif()
446470

447471

448-
target_sources(livekit PRIVATE $<TARGET_OBJECTS:livekit_proto>)
472+
target_sources(livekit PRIVATE
473+
$<TARGET_OBJECTS:livekit_proto>
474+
$<TARGET_OBJECTS:livekit_uniffi_cpp>
475+
)
476+
set_source_files_properties(
477+
${LIVEKIT_ROOT_DIR}/src/uniffi_bindgen_adapter.cpp
478+
PROPERTIES OBJECT_DEPENDS ${LIVEKIT_UNIFFI_CPP_HEADER}
479+
)
449480

450481
target_include_directories(livekit
451482
PUBLIC
@@ -454,6 +485,7 @@ target_include_directories(livekit
454485
PRIVATE
455486
${LIVEKIT_ROOT_DIR}/src
456487
${LIVEKIT_ROOT_DIR}/src/trace
488+
${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}
457489
${LIVEKIT_PROTOBUF_DEP_INCLUDE_DIRS}
458490
)
459491

‎build.cmd‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -336,14 +336,9 @@ if exist "%LOCAL_INSTALL_DIR%" (
336336
rmdir /s /q "%LOCAL_INSTALL_DIR%" 2>nul
337337
)
338338

339-
echo Removing Rust debug artifacts...
340-
if exist "%PROJECT_ROOT%\client-sdk-rust\target\debug" (
341-
rmdir /s /q "%PROJECT_ROOT%\client-sdk-rust\target\debug" 2>nul
342-
)
343-
344-
echo Removing Rust release artifacts...
345-
if exist "%PROJECT_ROOT%\client-sdk-rust\target\release" (
346-
rmdir /s /q "%PROJECT_ROOT%\client-sdk-rust\target\release" 2>nul
339+
echo Removing Rust target directory...
340+
if exist "%PROJECT_ROOT%\client-sdk-rust\target" (
341+
rmdir /s /q "%PROJECT_ROOT%\client-sdk-rust\target" 2>nul
347342
)
348343

349344
echo ==^> Clean-all complete.

‎build.sh‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -347,11 +347,8 @@ clean_all() {
347347
echo "Removing local-install directory..."
348348
rm -rf "${LOCAL_INSTALL_DIR}" || true
349349

350-
echo "Removing Rust debug artifacts..."
351-
rm -rf "${PROJECT_ROOT}/client-sdk-rust/target/debug" || true
352-
353-
echo "Removing Rust release artifacts..."
354-
rm -rf "${PROJECT_ROOT}/client-sdk-rust/target/release" || true
350+
echo "Removing Rust target directory..."
351+
rm -rf "${PROJECT_ROOT}/client-sdk-rust/target" || true
355352

356353
echo "==> Clean-all complete."
357354
}

‎client-sdk-rust‎

‎cmake/uniffi_cpp.cmake‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Copyright 2026 LiveKit, Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
set(LIVEKIT_UNIFFI_CPP_GENERATED_DIR "${LIVEKIT_BINARY_DIR}/generated/uniffi")
16+
set(LIVEKIT_UNIFFI_CPP_SOURCE
17+
"${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}/livekit_ffi.cpp")
18+
set(LIVEKIT_UNIFFI_CPP_HEADER
19+
"${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}/livekit_ffi.hpp")
20+
set(LIVEKIT_UNIFFI_CPP_SCAFFOLDING_HEADER
21+
"${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}/livekit_ffi_scaffolding.hpp")
22+
23+
# Release Linux builds strip the UniFFI metadata symbols, so generate from a
24+
# separate unstripped Debug library there. PE and Mach-O retain the metadata,
25+
# allowing Windows and macOS to reuse the livekit-ffi library already built for
26+
# the selected CMake configuration.
27+
if(UNIX AND NOT APPLE)
28+
set(LIVEKIT_UNIFFI_METADATA_TARGET_DIR
29+
"${RUST_ROOT}/target/uniffi-cpp-metadata")
30+
set(LIVEKIT_UNIFFI_METADATA_LIBRARY
31+
"${LIVEKIT_UNIFFI_METADATA_TARGET_DIR}/debug/liblivekit_ffi.so")
32+
endif()
33+
34+
file(GLOB_RECURSE LIVEKIT_UNIFFI_RUST_SOURCES CONFIGURE_DEPENDS
35+
"${RUST_ROOT}/livekit-ffi/src/*.rs"
36+
"${RUST_ROOT}/livekit-ffi/protocol/*.proto"
37+
"${RUST_ROOT}/livekit-ffi/build.rs"
38+
"${RUST_ROOT}/livekit-ffi/Cargo.toml"
39+
)
40+
list(APPEND LIVEKIT_UNIFFI_RUST_SOURCES
41+
"${RUST_ROOT}/Cargo.toml"
42+
"${RUST_ROOT}/Cargo.lock"
43+
"${RUST_ROOT}/rust-toolchain.toml"
44+
)
45+
46+
file(GLOB_RECURSE LIVEKIT_UNIFFI_BINDGEN_SOURCES CONFIGURE_DEPENDS
47+
"${RUST_ROOT}/tools/bindgens/src/*.rs"
48+
"${RUST_ROOT}/tools/bindgens/Cargo.toml"
49+
)
50+
51+
if(UNIX AND NOT APPLE)
52+
add_custom_command(
53+
OUTPUT "${LIVEKIT_UNIFFI_METADATA_LIBRARY}"
54+
COMMAND "${CMAKE_COMMAND}"
55+
-DCFG=Debug
56+
-DRUST_ROOT=${RUST_ROOT}
57+
-DCARGO=${CARGO_EXECUTABLE}
58+
-DPROTOC_PATH=${Protobuf_PROTOC_EXECUTABLE}
59+
-DGCC_LIB_DIR=${GCC_LIB_DIR}
60+
-DCARGO_TARGET_DIR=${LIVEKIT_UNIFFI_METADATA_TARGET_DIR}
61+
-P "${RUN_CARGO_SCRIPT}"
62+
WORKING_DIRECTORY "${RUST_ROOT}"
63+
DEPENDS ${LIVEKIT_UNIFFI_RUST_SOURCES}
64+
COMMENT "Building unstripped livekit-ffi metadata library"
65+
VERBATIM
66+
)
67+
add_custom_target(build_livekit_ffi_metadata
68+
DEPENDS "${LIVEKIT_UNIFFI_METADATA_LIBRARY}")
69+
else()
70+
set(LIVEKIT_UNIFFI_METADATA_LIBRARY "$<TARGET_FILE:livekit_ffi>")
71+
add_custom_target(build_livekit_ffi_metadata)
72+
endif()
73+
74+
# Keep Cargo invocations serialized on fresh runners, and ensure the selected
75+
# livekit-ffi library exists before it is inspected on Windows and macOS.
76+
add_dependencies(build_livekit_ffi_metadata build_rust_ffi)
77+
78+
add_custom_command(
79+
OUTPUT
80+
"${LIVEKIT_UNIFFI_CPP_SOURCE}"
81+
"${LIVEKIT_UNIFFI_CPP_HEADER}"
82+
"${LIVEKIT_UNIFFI_CPP_SCAFFOLDING_HEADER}"
83+
COMMAND "${CMAKE_COMMAND}" -E make_directory
84+
"${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}"
85+
COMMAND "${CMAKE_COMMAND}" -E env
86+
"CARGO_TARGET_DIR=${RUST_ROOT}/target/bindgens"
87+
"CARGO_ENCODED_RUSTFLAGS="
88+
"RUSTFLAGS="
89+
"${CARGO_EXECUTABLE}" run --locked
90+
--package bindgens
91+
--bin uniffi-bindgen-cpp
92+
--
93+
--library "${LIVEKIT_UNIFFI_METADATA_LIBRARY}"
94+
--out-dir "${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}"
95+
WORKING_DIRECTORY "${RUST_ROOT}"
96+
DEPENDS
97+
build_livekit_ffi_metadata
98+
${LIVEKIT_UNIFFI_RUST_SOURCES}
99+
${LIVEKIT_UNIFFI_BINDGEN_SOURCES}
100+
COMMENT "Generating UniFFI C++ bindings"
101+
VERBATIM
102+
)
103+
add_custom_target(generate_livekit_ffi_uniffi_cpp
104+
DEPENDS
105+
"${LIVEKIT_UNIFFI_CPP_SOURCE}"
106+
"${LIVEKIT_UNIFFI_CPP_HEADER}"
107+
"${LIVEKIT_UNIFFI_CPP_SCAFFOLDING_HEADER}"
108+
)
109+
110+
set_source_files_properties(
111+
"${LIVEKIT_UNIFFI_CPP_SOURCE}"
112+
"${LIVEKIT_UNIFFI_CPP_HEADER}"
113+
"${LIVEKIT_UNIFFI_CPP_SCAFFOLDING_HEADER}"
114+
PROPERTIES GENERATED TRUE
115+
)
116+
117+
add_library(livekit_uniffi_cpp OBJECT
118+
"${LIVEKIT_UNIFFI_CPP_SOURCE}"
119+
)
120+
set_target_properties(livekit_uniffi_cpp PROPERTIES
121+
CXX_VISIBILITY_PRESET hidden
122+
C_VISIBILITY_PRESET hidden
123+
VISIBILITY_INLINES_HIDDEN ON
124+
)
125+
add_dependencies(livekit_uniffi_cpp generate_livekit_ffi_uniffi_cpp)
126+
target_include_directories(livekit_uniffi_cpp
127+
PUBLIC "${LIVEKIT_UNIFFI_CPP_GENERATED_DIR}"
128+
)
129+
target_link_libraries(livekit_uniffi_cpp PRIVATE livekit_ffi)

‎include/livekit/e2ee.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ class LIVEKIT_API E2EEManager {
121121
/// Use this for key rotation during the lifetime of a single room or for
122122
/// per-participant keys (e.g., when implementing the MEGOLM or MLS protocol)
123123
/// via shared-key or participant-keyed APIs paired with the frame cryptor.
124-
/// See https://docs.livekit.io/home/client/encryption/#custom-key-provider
124+
/// See https://docs.livekit.io/transport/encryption/start/#custom-key-provider
125125
/// for details.
126126
class LIVEKIT_API KeyProvider {
127127
public:

0 commit comments

Comments
 (0)