[1.6.x] build: preflight xkbcommon and document GLFW prerequisites

cmake/CheckBuildDeps.cmake

@@ -4,8 +4,8 @@
 # ==============================================================================
 # CheckBuildDeps.cmake
 # ==============================================================================
-# Preflight for the command-line tools the build shells out to. Runs before any
-# FetchContent, so a missing tool is one error naming every gap at once instead
+# Preflight for system dependencies needed by the build. Runs before any
+# FetchContent, so missing dependencies produce one error naming every gap instead
 # of a FATAL_ERROR ~60 s deep in a fetched dependency's CMake, or a feature
 # dropped from the build with no diagnostic louder than a `--` status line.
 #
@@ -53,6 +53,14 @@ function(isaac_teleop_check_build_deps)
             list(APPEND _missing_pkgs "libwayland-dev")
             set(_wayland_gap TRUE)
         endif()
+        if(PkgConfig_FOUND)
+            pkg_check_modules(XKBCOMMON QUIET xkbcommon>=0.5.0)
+            if(NOT XKBCOMMON_FOUND)
+                list(APPEND _missing_tools "xkbcommon>=0.5.0 (BUILD_VIZ=ON -- GLFW Wayland backend)")
+                list(APPEND _missing_pkgs "libxkbcommon-dev")
+                set(_wayland_gap TRUE)
+            endif()
+        endif()
     endif()
 
     # glslangValidator compiles src/viz's GLSL to SPIR-V. Caching it here also

docs/source/development/build_from_source/index.rst

@@ -40,10 +40,11 @@ Prerequisites
 
    ``BUILD_VIZ=ON`` additionally requires **glslangValidator** to compile shaders to SPIR-V
    (``glslang-tools`` on Linux, ``brew install glslang`` on macOS; ships with the Vulkan SDK
-   on Windows), and on Linux **wayland-scanner** (``libwayland-dev``) for GLFW's Wayland
-   backend — pass ``-DGLFW_BUILD_WAYLAND=OFF`` to build Televiz against X11 only instead.
-   Neither gates the auto-default: if one is missing, the configure fails naming it rather
-   than quietly dropping the module. Most users do not need any of this:
+   on Windows). On Linux, GLFW's Wayland backend also requires **wayland-scanner**
+   (``libwayland-dev``) and **xkbcommon >= 0.5.0** (``libxkbcommon-dev``). Pass
+   ``-DGLFW_BUILD_WAYLAND=OFF`` to build Televiz against X11 only instead.
+   These dependencies do not gate the auto-default: if one is missing, configure fails
+   naming it rather than quietly dropping the module. Most users do not need any of this:
    ``pip install isaaccapture`` already ships the compiled ``isaaccapture.viz`` module. See
    `Other Build options`_ for the full option table.
 
@@ -58,7 +59,9 @@ the list of dependencies. On **Ubuntu**, install build tools and clang-format:
 .. code-block:: bash
 
    sudo apt-get update
-   sudo apt-get install -y build-essential cmake libegl-dev libx11-dev libwayland-dev clang-format-14 ccache patchelf pkg-config glslang-tools
+   sudo apt-get install -y build-essential cmake clang-format-14 ccache patchelf pkg-config glslang-tools \
+       libegl-dev libwayland-dev libx11-dev libxcursor-dev libxext-dev libxi-dev \
+       libxinerama-dev libxkbcommon-dev libxrandr-dev
 
 Runtime-only dependencies (needed to actually run teleop, not to build):
 

docs/source/device/cameras/oak.rst

@@ -34,6 +34,9 @@ subsequent builds are fast.
 Prerequisites
 ~~~~~~~~~~~~~
 
+Complete the :ref:`source-build prerequisites <one-time-setup>` first, then install
+the OAK-specific dependencies:
+
 .. code-block:: bash
 
    # Install build tools for vcpkg to build libusb (Linux)

docs/source/device/hand_tracking/wuji_glove.rst

@@ -35,6 +35,8 @@ Prerequisites
 -------------
 
 - **Linux** — x86_64 or aarch64 (tested on Ubuntu 22.04 / 24.04).
+- **Source-build prerequisites** — complete :ref:`one-time-setup` before running
+  ``install.sh``.
 - **wuji_sdk C SDK v2026.7.14** — the
   ``wuji-sdk-c-2026.7.14-<arch>-linux-gnu.tar.gz`` GitHub release asset, which
   extracts to ``include/wuji_sdk.h`` plus ``lib/libwuji_sdk_c.so`` and its

docs/source/integrations/lerobot/data_collection_sim.rst

@@ -114,17 +114,8 @@ Collect Teleop Data
          source. If ``./install/plugins/so101_leader/so101_leader_plugin`` does not exist, this
          step has not been completed.
 
-      Install the build prerequisites first — a missing ``clang-format-14`` is the most common
-      cause of a failed build, because the format check is enforced by default on Linux:
-
-      .. code-block:: bash
-
-         sudo apt-get update
-         sudo apt-get install -y build-essential cmake libx11-dev clang-format-14 ccache patchelf pkg-config glslang-tools
-
-      Then clone, configure, build, and install (see
-      :doc:`/development/build_from_source/index` for the full prerequisite list and all
-      build options):
+      Install the :ref:`source-build prerequisites <one-time-setup>` first, including
+      ``clang-format-14`` for the Linux format check. Then clone, configure, build, and install:
 
       .. code-block:: bash
 

examples/camera_viz/scripts/_install_deps.sh

@@ -442,9 +442,9 @@ EOF
 isaaccapture can be built from this checkout instead:
   $REPO_ROOT
 
-That is a full C++ / CUDA / Vulkan build and takes a while. It needs CMake,
-the CUDA toolkit, Vulkan headers, glslangValidator, and clang-format-14 (the
-format gate runs as part of the build).
+That is a full C++ / CUDA / Vulkan build and takes a while. Install the
+source-build prerequisites first:
+  $REPO_ROOT/docs/source/development/build_from_source/index.rst
 EOF
 
     if ! $BUILD_FROM_SOURCE; then