diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md deleted file mode 100644 index eb223af9..00000000 --- a/DEPENDENCIES.md +++ /dev/null @@ -1,259 +0,0 @@ -# LiveKit C++ SDK - System Dependencies - -This file lists all system-level dependencies required to link against the LiveKit C++ SDK libraries. - -## Overview - -The LiveKit SDK consists of two libraries: -- `livekit.lib` / `liblivekit.a` - Main SDK static library -- `livekit_ffi.dll` / `liblivekit_ffi.so` / `liblivekit_ffi.dylib` - Rust FFI dynamic library - -## Distribution Model - -The SDK uses different distribution strategies per platform: - -### Windows (Complete Package) -✅ **Ready to use** - All dependencies included: -- `livekit.lib` - Main SDK static library -- `livekit_ffi.dll` + `livekit_ffi.dll.lib` - Rust FFI dynamic library -- `libprotobuf.dll` + `libprotobuf.lib` - Protocol Buffers runtime -- `abseil_dll.dll` + `abseil_dll.lib` - Abseil C++ library - -**User action**: Copy all DLLs alongside your executable. No additional installation required. - -### Linux (Minimal Package) -⚠️ **Requires system dependencies**: -- `liblivekit.a` - Main SDK static library (included) -- `liblivekit_ffi.so` - Rust FFI dynamic library (included, **must be placed alongside your executable**) -- `libprotobuf` - Must install via `apt install libprotobuf-dev` -- `libssl` - Must install via `apt install libssl-dev` -- `libabsl` - Only if built with Protobuf 6.0+: `apt install libabsl-dev` - -**User action**: Install required packages and copy `liblivekit_ffi.so` to your executable directory. - -### macOS (Minimal Package) -⚠️ **Requires system dependencies**: -- `liblivekit.a` - Main SDK static library (included) -- `liblivekit_ffi.dylib` - Rust FFI dynamic library (included, **must be placed alongside your executable**) -- `protobuf` - Must install via `brew install protobuf` -- `abseil` - Only if built with Protobuf 6.0+: `brew install abseil` - -**User action**: Install required packages and copy `liblivekit_ffi.dylib` to your executable directory. - ---- - -## Windows Dependencies - -When linking on Windows, you must add these system libraries: - -```cmake -target_link_libraries(your_app PRIVATE - # LiveKit static libraries - livekit - livekit_ffi - - # Windows system libraries (REQUIRED) - ntdll # NT kernel interface - userenv # User environment functions - winmm # Windows multimedia - iphlpapi # IP Helper API - msdmo # DirectX Media Objects - dmoguids # DMO GUIDs - wmcodecdspuuid # Windows Media codec DSP UUIDs - ws2_32 # Winsock 2 - secur32 # Security Support Provider Interface - bcrypt # Cryptography API - crypt32 # Cryptography API (certificates) -) -``` - -### Visual Studio Project Settings -If using Visual Studio directly, add to **Linker → Input → Additional Dependencies**: -``` -ntdll.lib;userenv.lib;winmm.lib;iphlpapi.lib;msdmo.lib;dmoguids.lib;wmcodecdspuuid.lib;ws2_32.lib;secur32.lib;bcrypt.lib;crypt32.lib -``` - ---- - -## macOS Dependencies - -When linking on macOS, you must add these system frameworks: - -```cmake -find_library(FW_COREAUDIO CoreAudio REQUIRED) -find_library(FW_AUDIOTOOLBOX AudioToolbox REQUIRED) -find_library(FW_COREFOUNDATION CoreFoundation REQUIRED) -find_library(FW_SECURITY Security REQUIRED) -find_library(FW_COREGRAPHICS CoreGraphics REQUIRED) -find_library(FW_COREMEDIA CoreMedia REQUIRED) -find_library(FW_VIDEOTOOLBOX VideoToolbox REQUIRED) -find_library(FW_AVFOUNDATION AVFoundation REQUIRED) -find_library(FW_COREVIDEO CoreVideo REQUIRED) -find_library(FW_FOUNDATION Foundation REQUIRED) -find_library(FW_APPKIT AppKit REQUIRED) -find_library(FW_QUARTZCORE QuartzCore REQUIRED) -find_library(FW_OPENGL OpenGL REQUIRED) -find_library(FW_IOSURFACE IOSurface REQUIRED) -find_library(FW_METAL Metal REQUIRED) -find_library(FW_METALKIT MetalKit REQUIRED) -find_library(FW_SCREENCAPTUREKIT ScreenCaptureKit REQUIRED) - -target_link_libraries(your_app PRIVATE - # LiveKit static libraries - livekit - livekit_ffi - - # macOS frameworks (REQUIRED) - ${FW_COREAUDIO} - ${FW_AUDIOTOOLBOX} - ${FW_COREFOUNDATION} - ${FW_SECURITY} - ${FW_COREGRAPHICS} - ${FW_COREMEDIA} - ${FW_VIDEOTOOLBOX} - ${FW_AVFOUNDATION} - ${FW_COREVIDEO} - ${FW_FOUNDATION} - ${FW_APPKIT} - ${FW_QUARTZCORE} - ${FW_OPENGL} - ${FW_IOSURFACE} - ${FW_METAL} - ${FW_METALKIT} - ${FW_SCREENCAPTUREKIT} -) - -target_link_options(your_app PRIVATE "LINKER:-ObjC") -``` - -### Xcode Project Settings -Add to **Build Phases → Link Binary With Libraries**: -- CoreAudio.framework -- AudioToolbox.framework -- CoreFoundation.framework -- Security.framework -- CoreGraphics.framework -- CoreMedia.framework -- VideoToolbox.framework -- AVFoundation.framework -- CoreVideo.framework -- Foundation.framework -- AppKit.framework -- QuartzCore.framework -- OpenGL.framework -- IOSurface.framework -- Metal.framework -- MetalKit.framework -- ScreenCaptureKit.framework - -Also add `-ObjC` to **Other Linker Flags**. - ---- - -## Linux Dependencies - -### Required System Packages - -First, install the required development packages: - -```bash -# Ubuntu/Debian -sudo apt install libprotobuf-dev protobuf-compiler libabsl-dev libssl-dev - -# Fedora/RHEL -sudo dnf install protobuf-devel abseil-cpp-devel openssl-devel -``` - -### CMake Configuration - -```cmake -find_package(Protobuf REQUIRED) -find_package(OpenSSL REQUIRED) - -target_link_libraries(your_app PRIVATE - # LiveKit static libraries - livekit - livekit_ffi - - # Protobuf (REQUIRED) - protobuf::libprotobuf - - # Linux system libraries (REQUIRED) - OpenSSL::SSL - OpenSSL::Crypto - pthread - dl -) - -# NOTE: If using Protobuf 6.0+, you also need to link Abseil: -# find_package(absl REQUIRED) -# target_link_libraries(your_app PRIVATE absl::log absl::strings absl::base) -``` - -### Manual Linking (Makefile/gcc) -```bash -g++ your_app.cpp \ - -I/path/to/livekit/include \ - -L/path/to/livekit/lib \ - -llivekit -llivekit_ffi \ - -lprotobuf -lssl -lcrypto -lpthread -ldl -``` - ---- - -## Common Linking Errors - -### Windows -``` -error LNK2019: unresolved external symbol __imp_WSAStartup -``` -**Solution**: Add `ws2_32.lib` to your linker dependencies. - -``` -error LNK2019: unresolved external symbol BCryptGenRandom -``` -**Solution**: Add `bcrypt.lib` to your linker dependencies. - -### macOS -``` -Undefined symbols for architecture x86_64: - "_AudioObjectGetPropertyData", referenced from: -``` -**Solution**: Link against `CoreAudio.framework`. - -### Linux -``` -undefined reference to `SSL_CTX_new' -``` -**Solution**: Install OpenSSL development package and link against it: -```bash -sudo apt install libssl-dev -``` - ---- - -## Quick Reference - -| Platform | System Libraries Count | Key Dependencies | -|----------|------------------------|------------------| -| Windows | 11 libraries | ws2_32, bcrypt, secur32 | -| macOS | 17 frameworks | CoreAudio, VideoToolbox, ScreenCaptureKit | -| Linux | 2+ libraries | OpenSSL (ssl, crypto) | - ---- - -## Verification - -To verify you have all dependencies linked correctly: - -1. **Build your application** -2. **Check for linker errors** - any `unresolved external symbol` or `undefined reference` indicates a missing system library -3. **Run the application** - if it crashes immediately, you may be missing runtime dependencies - ---- - -## Need Help? - -- See [`docs/building.md`](docs/building.md) for complete build instructions -- Check `CMakeLists.txt` lines 287-381 for the exact CMake configuration -- Open an issue at: https://github.com/livekit/client-sdk-cpp/issues diff --git a/docs/building.md b/docs/building.md index 79f4e6e5..b09c6148 100644 --- a/docs/building.md +++ b/docs/building.md @@ -215,15 +215,18 @@ 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 +│ ├── liblivekit.{so,dylib} # Main SDK shared library (Linux/macOS) +│ ├── liblivekit_ffi.{so,dylib} # Rust FFI shared library (Linux/macOS) +│ └── livekit{,_ffi}.lib # Import libraries (Windows) ├── include/ # Public headers (auto-synced) │ └── livekit/ -└── bin/ # Example/test executables - └── liblivekit_ffi.{so,dylib} # (Linux/macOS: copied for runtime) +└── bin/ + └── livekit{,_ffi}.dll # SDK DLLs (Windows) ``` +Release archives use the same layout: `include/`, `lib/`, and (on Windows) +`bin/`. The exact build-tree layout can vary with the CMake generator. + ## Integrating into your project ### Using CMake @@ -234,8 +237,8 @@ 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) +find_package(LiveKit CONFIG REQUIRED) +target_link_libraries(your_target PRIVATE LiveKit::livekit) ``` ### Using prebuilt releases @@ -252,53 +255,44 @@ See the example collection's [`LiveKitSDK.cmake`](https://github.com/livekit-examples/cpp-example-collection/blob/main/cmake/LiveKitSDK.cmake) for the full pattern. -### Manual linking - -1. Add include path: `build-release/include` -2. Link the static SDK library: - - Windows: `build-release/lib/livekit.lib` - - Linux: `build-release/lib/liblivekit.a` - - macOS: `build-release/lib/liblivekit.a` -3. 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 -4. 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. +### Manual linking and deployment + +Prefer the CMake package above. It provides the correct include directory and +the `LiveKit::livekit` shared-library target. If you link a release archive +manually, add its `include/` directory and link only the main SDK library: + +| Platform | Link-time file | Runtime files to deploy | +|----------|----------------|-------------------------| +| Windows | `lib/livekit.lib` | `bin/livekit.dll` and `bin/livekit_ffi.dll` beside the application executable | +| Linux | `lib/liblivekit.so` | `liblivekit.so` and `liblivekit_ffi.so` in the same runtime-library directory | +| macOS | `lib/liblivekit.dylib` | `liblivekit.dylib` and `liblivekit_ffi.dylib` in the same runtime-library directory | + +Do not link the Rust FFI library directly: `livekit` already records it as a +shared-library dependency. On Linux, `liblivekit.so` uses a `$ORIGIN` runpath +to locate `liblivekit_ffi.so` next to it. On macOS, it uses `@loader_path` for +the same purpose. Your application must still be configured to find +`liblivekit` at runtime (for example, by using an appropriate executable +RPATH or platform packaging mechanism). + +### Runtime dependencies of release artifacts + +Official release archives bundle the two SDK libraries above. They do not +bundle, or dynamically depend on, Protobuf, Abseil, or OpenSSL. As of v1.7.0: + +- **Windows:** the SDK DLLs depend on Windows system libraries and the + Microsoft Visual C++ runtime. Install the supported Visual C++ Redistributable + with your application when it is not already present. The archive contains no + Protobuf or Abseil DLLs. +- **Linux:** `liblivekit.so` additionally depends on the system C++ runtime, + glibc, and `libcurl.so.4`; `liblivekit_ffi.so` depends on the system C++ + runtime and glibc. Install the matching runtime packages for your target + distribution. +- **macOS:** the SDK depends on system frameworks and the system `libcurl`; + no Homebrew Protobuf, Abseil, or OpenSSL runtime is required. + +These are release-artifact requirements, not source-build prerequisites. For +an updated audit of a specific release, inspect its binaries with `ldd` +(Linux), `otool -L` (macOS), or `dumpbin /dependents` (Windows). ## Troubleshooting