Try cpp-tools

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
       builds: ${{ steps.filter.outputs.builds }}
       tests:  ${{ steps.filter.outputs.tests }}
       docs:   ${{ steps.filter.outputs.docs }}
-      cpp_checks: ${{ steps.filter.outputs.cpp_checks }}
+      cpp_tools: ${{ steps.filter.outputs.cpp_tools }}
       rust_release_check: ${{ steps.filter.outputs.rust_release_check }}
       docker: ${{ steps.filter.outputs.docker }}
     steps:
@@ -40,6 +40,7 @@ jobs:
               - benchmarks/**
               - cpp-example-collection
               - cpp-example-collection/**
+              - client-sdk-rust
               - client-sdk-rust/**
               - cmake/**
               - CMakeLists.txt
@@ -52,6 +53,7 @@ jobs:
             tests:
               - src/**
               - include/**
+              - client-sdk-rust
               - client-sdk-rust/**
               - cmake/**
               - .token_helpers/**
@@ -70,20 +72,19 @@ jobs:
               - .github/workflows/ci.yml
               - .github/workflows/generate-docs.yml
               - .github/workflows/publish-docs.yml
-            cpp_checks:
+            cpp_tools:
               - src/**
               - include/**
               - benchmarks/**
+              - client-sdk-rust
               - client-sdk-rust/**
               - cmake/**
               - CMakeLists.txt
               - CMakePresets.json
-              - scripts/clang-format.sh
-              - scripts/clang-tidy.sh
-              - .clang-format
-              - .clang-tidy
+              - cpp-tools
+              - cpp-tools/**
+              - .gitmodules
               - .github/workflows/ci.yml
-              - .github/workflows/cpp-checks.yml
             docker:
               - docker/**
               - .github/workflows/ci.yml
@@ -129,11 +130,37 @@ jobs:
     name: Link Check
     uses: ./.github/workflows/link_check.yml
 
-  cpp-checks:
-    name: C++ Checks
+  cpp-tools:
+    name: C++ Tools
     needs: changes
-    if: ${{ needs.changes.outputs.cpp_checks == 'true' || github.event_name == 'workflow_dispatch' }}
-    uses: ./.github/workflows/cpp-checks.yml
+    if: ${{ needs.changes.outputs.cpp_tools == 'true' || github.event_name == 'workflow_dispatch' }}
+    # GitHub loads this workflow from the separate cpp-tools repository. Keep
+    # this immutable ref aligned with the cpp-tools submodule gitlink.
+    uses: livekit/cpp-tools/.github/workflows/cpp-tools.yml@f2dbc227187f9434f6bba9e95e0a2da4638b973b
+    with:
+      clang_format: true
+      clang_tidy: true
+      checkout_submodules: recursive
+      clang_format_paths: src include benchmarks
+      clang_tidy_dependencies_command: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          build-essential cmake ninja-build pkg-config \
+          llvm-dev libclang-dev clang \
+          libssl-dev libcurl4-openssl-dev wget ca-certificates gnupg
+      clang_tidy_install_rust: true
+      clang_tidy_setup_command: |
+        echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
+        echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
+        LLVM_VERSION=$(llvm-config --version | cut -d. -f1)
+        echo "LIBCLANG_PATH=/usr/lib/llvm-${LLVM_VERSION}/lib" >> "$GITHUB_ENV"
+      clang_tidy_configure_command: cmake --preset linux-release
+      clang_tidy_generate_command: cmake --build build-release --target livekit_proto
+      clang_tidy_build_dir: build-release
+      clang_tidy_file_regex: '^(?!.*/(_deps|build-[^/]*|client-sdk-rust|cpp-example-collection|vcpkg_installed|docker|docs|data)/).*/src/(?!tests/).*\.(c|cpp|cc|cxx)$'
+      clang_tidy_header_filter: '.*/(include/livekit|src)/.*\.(h|hpp)$'
+      clang_tidy_exclude_header_filter: '(.*/src/tests/.*)|(.*/_deps/.*)|(.*/build-[^/]*/.*)'
+      clang_tidy_require_generated_protobuf: build-release/generated
 
   generate-docs:
     name: Generate Docs
@@ -162,7 +189,7 @@ jobs:
       - docker-images
       - tests
       - license-check
-      - cpp-checks
+      - cpp-tools
       - generate-docs
       - link-check
       - rust-release-check

.gitignore

@@ -23,6 +23,9 @@ docs/doxygen/latex/
 .vs/
 .vscode/
 .cursor/
+# Installed by cpp-tools/install.sh
+.clang-format
+.clang-tidy
 # Compiled output
 bin/
 lib/

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "cpp-example-collection"]
 	path = cpp-example-collection
 	url = https://github.com/livekit-examples/cpp-example-collection.git
+[submodule "cpp-tools"]
+	path = cpp-tools
+	url = https://github.com/livekit/cpp-tools.git

AGENTS.md

@@ -76,10 +76,11 @@ Be sure to update the directory layout in this file if the directory layout chan
 | `src/tests/` | Google Test integration and stress tests |
 | `examples/` | In-tree example applications |
 | `client-sdk-rust/` | Git submodule holding the Rust core of the SDK|
+| `cpp-tools/` | Git submodule holding shared LiveKit C++ clang-format / clang-tidy configs, scripts, docs, and CI workflow |
 | `client-sdk-rust/livekit-ffi/protocol/*.proto` | FFI contract (protobuf definitions, read-only reference) |
 | `cmake/` | Build helpers (`protobuf.cmake`, `spdlog.cmake`, `nlohmann_json.cmake`, `LiveKitConfig.cmake.in`) |
 | `docker/` | Dockerfile for CI and SDK distribution images |
-| `scripts/` | Developer / CI helper scripts (e.g. `clang-tidy.sh`) |
+| `scripts/` | Local helper scripts for SDK-specific development tasks |
 | `docs/` | Documentation root. `docs/` holds hand-written long-form Markdown intended to also read well on GitHub. |
 | `docs/doxygen/` | Doxygen tool config, theme assets, and Doxygen-only content (`Doxyfile`, `index.md` mainpage, `customization/*.css`, `customization/header.html`, `customization/favicon.ico`). Files here use Doxygen-only syntax (`@ref`, `@brief`, …) and are not intended for human reading on their own. |
 | `.github/workflows/` | GitHub Actions CI workflows |
@@ -326,11 +327,11 @@ malformed table, missing `@param` on a documented function, …) fails the build
 
 Code should be easy to read and understand. If a sacrifice is made for performance or readability, it should be documented.
 
-Adhere to clang-format checks configured in `.clang-format`. After C++ code changes, run `./scripts/clang-format.sh` to confirm styling, or `./scripts/clang-format.sh --fix` to auto-format.
+Adhere to clang-format checks configured in `.clang-format`, which is installed as a symlink to `cpp-tools/.clang-format`. Run `./cpp-tools/clang-format.sh --path src --path include --path benchmarks` to confirm code styling, or add `--fix` to rewrite files.
 
 ### Static Analysis
 
-Adhere to clang-tidy checks configured in `.clang-tidy`. After C++ code changes, run `./scripts/clang-tidy.sh` to confirm code quality.
+Adhere to clang-tidy checks configured in `.clang-tidy`, which is installed as a symlink to `cpp-tools/.clang-tidy`. Run `./cpp-tools/clang-tidy.sh` with the repository-specific build directory and filters documented in `docs/tools.md`.
 
 ## Dependencies
 
@@ -340,6 +341,7 @@ Adhere to clang-tidy checks configured in `.clang-tidy`. After C++ code changes,
 | spdlog | **Private** | FetchContent or system package; must NOT leak into public API |
 | nlohmann/json | **Private** | Header-only; vendored via FetchContent (Unix) or vcpkg (Windows); must NOT leak into public API |
 | client-sdk-rust | Build-time | Git submodule, built via cargo during CMake build |
+| cpp-tools | Developer / CI | Git submodule containing shared LiveKit C++ formatting and static-analysis tooling |
 | Google Test | Test only | FetchContent in `src/tests/CMakeLists.txt` |
 
 When adding a new private/vendored dependency to this table, also add a
@@ -398,8 +400,9 @@ all filtered stages; normal pull requests and pushes use the path filters.
 - `.github/workflows/builds.yml` — Reusable SDK and example-collection build
   matrix.
 - `.github/workflows/tests.yml` — Reusable unit/integration test matrix.
-- `.github/workflows/cpp-checks.yml` — Reusable `clang-format` and
-  `clang-tidy` checks.
+- `livekit/cpp-tools/.github/workflows/cpp-tools.yml` — Shared reusable
+  workflow called directly by `ci.yml` for `clang-format` and `clang-tidy`
+  checks.
 - `.github/workflows/generate-docs.yml` — Reusable Doxygen docs validation.
 - `.github/workflows/rust-release-check.yml` — Reusable check that the pinned
  `client-sdk-rust` submodule commit maps to a published release. Gated by the
@@ -423,9 +426,10 @@ When adding or renaming files that affect a CI stage, update the matching
 `ci.yml` `changes` filter in the same PR. For example, new build scripts,
 CMake files, package manifests, or reusable build workflows should be added to
 the `builds` filter; test-only helpers to `tests`; formatting/static-analysis
-configuration to `cpp_checks`; and docs generation inputs to `docs`.
+configuration (including `cpp-tools` submodule bumps) to `cpp_tools`; and docs
+generation inputs to `docs`.
 
 Keep broad agent guidance files such as `AGENTS.md` out of the expensive
-`builds`, `tests`, `cpp_checks`, and `docs` filters unless they start affecting
+`builds`, `tests`, `cpp_tools`, and `docs` filters unless they start affecting
 generated docs or build artifacts. An `AGENTS.md`-only change should not trigger
 those stages; only the always-on cheap checks should run.

README.md

@@ -244,12 +244,13 @@ local `livekit-server --dev`, and run via `ctest` or directly. See
 
 ## Developer tools
 
-`clang-tidy`, `clang-format`, `valgrind`, and Doxygen are all wired up via
-scripts under `scripts/`. Set up the pre-commit auto-formatter
+`clang-tidy` and `clang-format` are provided by the `cpp-tools` submodule.
+`valgrind` and Doxygen remain documented with the rest of the local developer
+tools. Install the shared clang configuration and pre-commit auto-formatter
 with:
 
 ```bash
-./scripts/install-pre-commit.sh
+./cpp-tools/install.sh
 ```
 
 See [docs/tools.md](docs/tools.md).