fix: improve cross-platform build scripts and documentation

- Initialize optional variables in build.sh to fix 'unbound variable' errors
- Fix protozero_plugin.o removal to handle both Debug/Release and ignore missing errors
- Add debug-examples presets for Windows/Linux/macOS in CMakePresets.json
- Fix build.cmd clean to properly clean both Debug and Release configurations
- Fix vcpkg debug DLL naming (libprotobufd.dll vs libprotobuf.dll)
- Update README_BUILD.md to use build scripts instead of raw cmake commands

Author: Sqhh99

CMakeLists.txt

@@ -245,11 +245,14 @@ if(UNIX AND NOT APPLE)
   if(NOT CMAKE_AR)
     find_program(CMAKE_AR ar REQUIRED)
   endif()
+  # Remove protozero_plugin.o from static library to avoid duplicate symbols
+  # The file may not exist in all builds, so we use '|| true' to ignore errors
   add_custom_command(
     TARGET build_rust_ffi
     POST_BUILD
-    COMMAND ${CMAKE_AR} -dv "${RUST_LIB_RELEASE}" protozero_plugin.o
-    COMMENT "Removing protozero_plugin.o from liblivekit_ffi.a"
+    COMMAND ${CMAKE_AR} -dv "${RUST_LIB_RELEASE}" protozero_plugin.o || true
+    COMMAND ${CMAKE_AR} -dv "${RUST_LIB_DEBUG}" protozero_plugin.o || true
+    COMMENT "Removing protozero_plugin.o from liblivekit_ffi.a (if present)"
   )
 endif()
 
@@ -367,48 +370,50 @@ if(LIVEKIT_IS_TOPLEVEL)
     set(VCPKG_LIB_DIR_DEBUG "${LIVEKIT_ROOT_DIR}/vcpkg_installed/x64-windows/debug/lib")
     set(VCPKG_LIB_DIR_RELEASE "${LIVEKIT_ROOT_DIR}/vcpkg_installed/x64-windows/lib")
 
-    # List of required DLL files (runtime)
-    set(REQUIRED_DLLS
-      "libprotobuf.dll"
-      # "libprotobuf-lite.dll"
-      # "libprotoc.dll"
-      "abseil_dll.dll"
+    # vcpkg uses 'd' suffix for debug builds (e.g., libprotobufd.dll)
+    # We need to copy with the correct source name but keep the output name consistent
+    
+    # abseil_dll.dll (same name for both debug and release)
+    add_custom_command(
+      TARGET livekit POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+              "$<IF:$<CONFIG:Debug>,${VCPKG_BIN_DIR_DEBUG}/abseil_dll.dll,${VCPKG_BIN_DIR_RELEASE}/abseil_dll.dll>"
+              "$<TARGET_FILE_DIR:livekit>/abseil_dll.dll"
+      COMMENT "Copying abseil_dll.dll to lib directory"
+      VERBATIM
     )
 
-    # List of required LIB files (for linking)
-    set(REQUIRED_LIBS
-      "libprotobuf.lib"
-      # "libprotobuf-lite.lib"
-      # "libprotoc.lib"
-      "abseil_dll.lib"
+    # libprotobuf.dll - debug version has 'd' suffix
+    add_custom_command(
+      TARGET livekit POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+              "$<IF:$<CONFIG:Debug>,${VCPKG_BIN_DIR_DEBUG}/libprotobufd.dll,${VCPKG_BIN_DIR_RELEASE}/libprotobuf.dll>"
+              "$<TARGET_FILE_DIR:livekit>/$<IF:$<CONFIG:Debug>,libprotobufd.dll,libprotobuf.dll>"
+      COMMENT "Copying libprotobuf DLL to lib directory"
+      VERBATIM
     )
 
-    # Copy DLLs to the lib output directory
-    foreach(DLL_FILE ${REQUIRED_DLLS})
-      add_custom_command(
-        TARGET livekit POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E copy_if_different
-                "$<IF:$<CONFIG:Debug>,${VCPKG_BIN_DIR_DEBUG}/${DLL_FILE},${VCPKG_BIN_DIR_RELEASE}/${DLL_FILE}>"
-                "$<TARGET_FILE_DIR:livekit>/${DLL_FILE}"
-        COMMENT "Copying ${DLL_FILE} to lib directory"
-        VERBATIM
-      )
-    endforeach()
+    # abseil_dll.lib (same name for both debug and release)
+    add_custom_command(
+      TARGET livekit POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+              "$<IF:$<CONFIG:Debug>,${VCPKG_LIB_DIR_DEBUG}/abseil_dll.lib,${VCPKG_LIB_DIR_RELEASE}/abseil_dll.lib>"
+              "$<TARGET_FILE_DIR:livekit>/abseil_dll.lib"
+      COMMENT "Copying abseil_dll.lib to lib directory"
+      VERBATIM
+    )
 
-    # Copy LIBs (import libraries) to the lib output directory
-    foreach(LIB_FILE ${REQUIRED_LIBS})
-      add_custom_command(
-        TARGET livekit POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E copy_if_different
-                "$<IF:$<CONFIG:Debug>,${VCPKG_LIB_DIR_DEBUG}/${LIB_FILE},${VCPKG_LIB_DIR_RELEASE}/${LIB_FILE}>"
-                "$<TARGET_FILE_DIR:livekit>/${LIB_FILE}"
-        COMMENT "Copying ${LIB_FILE} to lib directory"
-        VERBATIM
-      )
-    endforeach()
+    # libprotobuf.lib - debug version has 'd' suffix
+    add_custom_command(
+      TARGET livekit POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy_if_different
+              "$<IF:$<CONFIG:Debug>,${VCPKG_LIB_DIR_DEBUG}/libprotobufd.lib,${VCPKG_LIB_DIR_RELEASE}/libprotobuf.lib>"
+              "$<TARGET_FILE_DIR:livekit>/$<IF:$<CONFIG:Debug>,libprotobufd.lib,libprotobuf.lib>"
+      COMMENT "Copying libprotobuf LIB to lib directory"
+      VERBATIM
+    )
 
-    message(STATUS "Third-party DLLs will be copied to lib directory: ${REQUIRED_DLLS}")
-    message(STATUS "Third-party LIBs will be copied to lib directory: ${REQUIRED_LIBS}")
+    message(STATUS "Third-party dependencies will be copied to lib directory")
   endif()
 endif()
 

CMakePresets.json

@@ -82,6 +82,17 @@
         "VCPKG_MANIFEST_FEATURES": "examples"
       }
     },
+    {
+      "name": "windows-debug-examples",
+      "displayName": "Windows x64 Debug with Examples",
+      "description": "Build for Windows x64 Debug with example applications",
+      "inherits": "windows-base",
+      "binaryDir": "${sourceDir}/build",
+      "cacheVariables": {
+        "LIVEKIT_BUILD_EXAMPLES": "ON",
+        "VCPKG_MANIFEST_FEATURES": "examples"
+      }
+    },
     {
       "name": "linux-release",
       "displayName": "Linux Release",
@@ -113,6 +124,17 @@
         "LIVEKIT_BUILD_EXAMPLES": "ON"
       }
     },
+    {
+      "name": "linux-debug-examples",
+      "displayName": "Linux Debug with Examples",
+      "description": "Build for Linux Debug with example applications",
+      "inherits": "linux-base",
+      "binaryDir": "${sourceDir}/build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "LIVEKIT_BUILD_EXAMPLES": "ON"
+      }
+    },
     {
       "name": "macos-release",
       "displayName": "macOS Release",
@@ -143,6 +165,17 @@
         "CMAKE_BUILD_TYPE": "Release",
         "LIVEKIT_BUILD_EXAMPLES": "ON"
       }
+    },
+    {
+      "name": "macos-debug-examples",
+      "displayName": "macOS Debug with Examples",
+      "description": "Build for macOS Debug with example applications",
+      "inherits": "macos-base",
+      "binaryDir": "${sourceDir}/build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "LIVEKIT_BUILD_EXAMPLES": "ON"
+      }
     }
   ],
   "buildPresets": [
@@ -161,6 +194,11 @@
       "configurePreset": "windows-release-examples",
       "configuration": "Release"
     },
+    {
+      "name": "windows-debug-examples",
+      "configurePreset": "windows-debug-examples",
+      "configuration": "Debug"
+    },
     {
       "name": "linux-release",
       "configurePreset": "linux-release"
@@ -173,6 +211,10 @@
       "name": "linux-release-examples",
       "configurePreset": "linux-release-examples"
     },
+    {
+      "name": "linux-debug-examples",
+      "configurePreset": "linux-debug-examples"
+    },
     {
       "name": "macos-release",
       "configurePreset": "macos-release"
@@ -184,6 +226,10 @@
     {
       "name": "macos-release-examples",
       "configurePreset": "macos-release-examples"
+    },
+    {
+      "name": "macos-debug-examples",
+      "configurePreset": "macos-debug-examples"
     }
   ]
 }

README_BUILD.md

@@ -46,44 +46,74 @@ sudo apt update && sudo apt install -y \
 brew install cmake ninja protobuf abseil
 ```
 
-### Method 1: Using CMake Presets (Recommended)
+## Quick Start
 
-The project provides a `CMakePresets.json` configuration file for simplified building.
+### Method 1: Using Build Scripts (Recommended)
 
-**Windows (requires VCPKG_ROOT):**
+The project provides `build.cmd` (Windows) and `build.sh` (Linux/macOS) scripts for simplified building.
+
+**Windows:**
 ```powershell
-# Set vcpkg root
+# Set vcpkg root (required for Windows)
 $env:VCPKG_ROOT = "C:\path\to\vcpkg"
 
-# Configure and build
-cmake --preset windows-release
-cmake --build --preset windows-release
+# Build Release version
+.\build.cmd release
+
+# Build Release with examples
+.\build.cmd release-examples
+
+# Build Debug version
+.\build.cmd debug
+
+# Build Debug with examples
+.\build.cmd debug-examples
 
-# To build with examples
-cmake --preset windows-release-examples
-cmake --build --preset windows-release-examples
+# Clean build artifacts
+.\build.cmd clean
+
+# Full clean (C++ + Rust + generated files)
+.\build.cmd clean-all
 ```
 
-**Linux (uses system packages):**
+**Linux:**
 ```bash
-# Configure and build
-cmake --preset linux-release
-cmake --build --preset linux-release
+# Install system dependencies first (see Prerequisites above)
+
+# Build Release version
+./build.sh release
+
+# Build Release with examples
+./build.sh release-examples
+
+# Build Debug version
+./build.sh debug
+
+# Build Debug with examples
+./build.sh debug-examples
 
-# To build with examples
-cmake --preset linux-release-examples
-cmake --build --preset linux-release-examples
+# Clean build artifacts
+./build.sh clean
+
+# Full clean
+./build.sh clean-all
 ```
 
-**macOS (uses Homebrew packages):**
+**macOS:**
 ```bash
-# Configure and build
-cmake --preset macos-release
-cmake --build --preset macos-release
+# Install Homebrew dependencies first (see Prerequisites above)
+
+# Build Release version
+./build.sh release
+
+# Build Release with examples
+./build.sh release-examples
+
+# Build Debug version
+./build.sh debug
 
-# To build with examples
-cmake --preset macos-release-examples
-cmake --build --preset macos-release-examples
+# Build Debug with examples
+./build.sh debug-examples
 ```
 
 #### Important Notes for Linux
@@ -116,17 +146,6 @@ export LIBCLANG_PATH=/usr/lib/llvm-14/lib  # Adjust version as needed
    - Cause: Rust bindgen cannot locate libclang library
    - Solution: Set `LIBCLANG_PATH` environment variable pointing to your LLVM installation
 
-**macOS:**
-```bash
-# Configure and build
-cmake --preset macos-release
-cmake --build --preset macos-release
-
-# To build with examples
-cmake --preset macos-release-examples
-cmake --build --preset macos-release-examples
-```
-
 ### Method 2: Using vcpkg Manifest Mode
 
 vcpkg will automatically install all required dependencies based on `vcpkg.json`.

build.cmd

@@ -143,32 +143,34 @@ echo ==^> Build complete!
 goto :eof
 
 :clean
-echo ==^> Cleaning CMake targets...
-if exist "%BUILD_DIR%" (
-    cmake --build "%BUILD_DIR%" --target clean
-) else (
-    echo    (skipping) %BUILD_DIR% does not exist.
+echo ==^> Cleaning CMake targets ^(Debug + Release^)...
+if not exist "%BUILD_DIR%\CMakeCache.txt" (
+    echo    ^(skipping^) Build directory does not exist or is not configured.
+    goto :eof
 )
+echo    Cleaning Debug...
+cmake --build "%BUILD_DIR%" --target clean --config Debug 2>nul
+echo    Cleaning Release...
+cmake --build "%BUILD_DIR%" --target clean --config Release 2>nul
+echo ==^> Clean complete.
 goto :eof
 
 :clean_all
-echo ==^> Running full clean-all (C++ + Rust)...
-if exist "%BUILD_DIR%" (
-    cmake --build "%BUILD_DIR%" --target clean_all
-) else (
-    echo    (info) %BUILD_DIR% does not exist; doing manual deep clean...
+echo ==^> Running full clean-all ^(C++ + Rust^)...
+if exist "%BUILD_DIR%\CMakeCache.txt" (
+    cmake --build "%BUILD_DIR%" --target clean_all 2>nul
 )
 
+echo Removing Rust debug artifacts...
 if exist "%PROJECT_ROOT%\client-sdk-rust\target\debug" (
-    echo Removing Rust debug artifacts...
     rmdir /s /q "%PROJECT_ROOT%\client-sdk-rust\target\debug" 2>nul
 )
+echo Removing Rust release artifacts...
 if exist "%PROJECT_ROOT%\client-sdk-rust\target\release" (
-    echo Removing Rust release artifacts...
     rmdir /s /q "%PROJECT_ROOT%\client-sdk-rust\target\release" 2>nul
 )
+echo Removing build directory...
 if exist "%BUILD_DIR%" (
-    echo Removing build directory...
     rmdir /s /q "%BUILD_DIR%" 2>nul
 )
 echo ==^> Clean-all complete.

build.sh

@@ -7,6 +7,15 @@ BUILD_TYPE="Release"
 VERBOSE=""
 PRESET=""
 
+# Initialize optional variables (required for set -u)
+DO_BUNDLE=""
+DO_ARCHIVE=""
+PREFIX=""
+ARCHIVE_NAME=""
+GENERATOR=""
+MACOS_ARCH=""
+LIVEKIT_VERSION=""
+
 # Detect OS for preset selection
 detect_os() {
   case "$(uname -s)" in