docs(oak): fix the OAK build instructions - #914
Open
jiwenc-nv wants to merge 1 commit into
Open
Conversation
Contributor
|
📝 Docs preview is not auto-deployed for fork PRs. A maintainer with write access to |
Contributor
📝 WalkthroughWalkthroughThe documentation now describes OAK builds as C++-only CMake builds that use the DepthAI v3.x vcpkg toolchain and the Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/source/device/oak.rst`:
- Around line 50-53: Update the documentation text near the build directory
guidance to avoid claiming that build/ is always kept free; use conditional
wording that accounts for an existing cache, or consistently prescribe
build-oak/ instead. Preserve the explanation that the plugin has no Python
component and does not require a py3.NN preset.
In `@docs/source/getting_started/build_from_source/index.rst`:
- Around line 262-269: Update the standalone OAK camera plugin CMake configure
command to explicitly set BUILD_PYTHON_BINDINGS=OFF alongside
BUILD_PLUGIN_OAK_CAMERA, while preserving the existing vcpkg toolchain and
camera_plugin_oak build steps.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: bfc9ecd1-9d64-4fa3-a578-fdce329d7242
📒 Files selected for processing (4)
docs/source/device/oak.rstdocs/source/getting_started/build_from_source/index.rstdocs/source/references/build.rstsrc/plugins/oak/README.md
Comment on lines
+50
to
+53
| The plugin has no Python component, so it does not need one of the ``py3.NN`` | ||
| presets. Configure it into ``build/``, which is kept free for exactly this kind of | ||
| one-off tree (see :doc:`/references/build`): | ||
|
|
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- OAK documentation ---'
sed -n '1,90p' docs/source/device/oak.rst
printf '%s\n' '--- build-from-source documentation ---'
sed -n '115,145p' docs/source/getting_started/build_from_source/index.rst
printf '%s\n' '--- related build references and OAK commands ---'
rg -n -C 3 'build/|build-oak|toolchain|cmake' docs/source/device/oak.rst docs/source/references/build.rst docs/source/getting_started/build_from_source/index.rstRepository: NVIDIA/IsaacTeleop
Length of output: 30139
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- build configuration files ---'
git ls-files 'CMakeLists.txt' 'CMakePresets.json' 'cmake/**' | head -80
printf '%s\n' '--- toolchain and binary-directory configuration ---'
rg -n -C 3 'CMAKE_TOOLCHAIN_FILE|binaryDir|BUILD_PLUGIN_OAK_CAMERA|BUILD_PYTHON_BINDINGS|ISAAC_TELEOP_PYTHON_VERSION' \
CMakeLists.txt CMakePresets.json cmake docs/source
printf '%s\n' '--- read-only consistency check ---'
python3 - <<'PY'
from pathlib import Path
oak = Path("docs/source/device/oak.rst").read_text()
build = Path("docs/source/getting_started/build_from_source/index.rst").read_text()
checks = {
"oak uses build directory": "cmake -B build -DBUILD_PLUGIN_OAK_CAMERA=ON" in oak,
"oak uses toolchain file": "-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" in oak,
"build guide documents bare build": "A bare ``cmake -B build`` still works" in build,
"build guide documents OAK in build": "cmake -B build -DBUILD_PLUGIN_OAK_CAMERA=ON" in build,
"oak warns about stale toolchain cache": "If ``build/`` was already configured" in oak,
}
for name, result in checks.items():
print(f"{name}: {result}")
PYRepository: NVIDIA/IsaacTeleop
Length of output: 23150
Use conditional wording for build/. The general build guide also uses build/, so an existing cache can prevent the OAK configuration from adopting the vcpkg toolchain. Replace “kept free” with conditional wording or use build-oak/ consistently.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/source/device/oak.rst` around lines 50 - 53, Update the documentation
text near the build directory guidance to avoid claiming that build/ is always
kept free; use conditional wording that accounts for an existing cache, or
consistently prescribe build-oak/ instead. Preserve the explanation that the
plugin has no Python component and does not require a py3.NN preset.
Source: Path instructions
Comment on lines
+262
to
+269
| Build the OAK camera plugin. It is C++ only and needs the vcpkg toolchain, so it | ||
| uses its own ``build/`` tree rather than a Python preset (see :doc:`/device/oak`): | ||
|
|
||
| .. code-block:: bash | ||
|
|
||
| cmake --preset py3.12 -DBUILD_PLUGIN_OAK_CAMERA=ON | ||
| cmake --build --preset py3.12 | ||
| cmake -B build -DBUILD_PLUGIN_OAK_CAMERA=ON \ | ||
| -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake | ||
| cmake --build build --target camera_plugin_oak --parallel |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- documentation context ---'
sed -n '175,215p;250,280p' docs/source/getting_started/build_from_source/index.rst
printf '%s\n' '--- relevant build options and OAK references ---'
rg -n -C 3 'BUILD_PYTHON_BINDINGS|BUILD_PLUGIN_OAK_CAMERA|camera_plugin_oak|OAK_CAMERA' \
--glob '!build/**' --glob '!dist/**' --glob '!node_modules/**' .Repository: NVIDIA/IsaacTeleop
Length of output: 27682
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- top-level CMake configuration order ---'
sed -n '1,175p' CMakeLists.txt
printf '%s\n' '--- Python setup and OAK target configuration ---'
sed -n '1,185p' cmake/SetupPython.cmake
sed -n '1,245p' src/plugins/oak/CMakeLists.txt
printf '%s\n' '--- presets and standalone OAK documentation ---'
rg -n -C 4 'BUILD_PYTHON_BINDINGS|configurePresets|binaryDir|BUILD_PLUGIN_OAK_CAMERA' \
CMakePresets.json cmake docs/source/device/oak.rst 2>/dev/null || trueRepository: NVIDIA/IsaacTeleop
Length of output: 31665
🏁 Script executed:
#!/bin/bash
set -eu
python3 - <<'PY'
from pathlib import Path
import re
root = Path(".")
cmake = (root / "CMakeLists.txt").read_text()
setup = (root / "cmake/SetupPython.cmake").read_text()
docs = (root / "docs/source/getting_started/build_from_source/index.rst").read_text()
def option_default(text, name):
m = re.search(
rf'option\(\s*{re.escape(name)}\s+"[^"]*"\s+([A-Za-z]+)\s*\)',
text,
re.IGNORECASE,
)
return m.group(1).upper() if m else None
def command_block(text, marker):
start = text.index(marker)
end = text.find("\n\n", start)
return text[start:] if end == -1 else text[start:end]
oak = command_block(docs, "cmake -B build -DBUILD_PLUGIN_OAK_CAMERA=ON")
print("BUILD_PYTHON_BINDINGS default:", option_default(setup, "BUILD_PYTHON_BINDINGS"))
print("OAK configure overrides BUILD_PYTHON_BINDINGS:",
bool(re.search(r"-DBUILD_PYTHON_BINDINGS\s*=", oak)))
print("src/python added unconditionally:",
"add_subdirectory(src/python)" in cmake)
print("src/python has BUILD_PYTHON_BINDINGS guard:",
bool(re.search(r"if\(NOT BUILD_PYTHON_BINDINGS\)\s+return\(\)",
(root / "src/python/CMakeLists.txt").read_text(), re.S)))
print("OAK target sources are C++:",
bool(re.search(r"add_executable\(\s*camera_plugin_oak\b.*?\.cpp",
(root / "src/plugins/oak/CMakeLists.txt").read_text(), re.S)))
PYRepository: NVIDIA/IsaacTeleop
Length of output: 364
Disable Python bindings in the standalone OAK configure.
The command enables BUILD_PYTHON_BINDINGS by default. Add -DBUILD_PYTHON_BINDINGS=OFF to prevent Python binding targets from being configured and built.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/source/getting_started/build_from_source/index.rst` around lines 262 -
269, Update the standalone OAK camera plugin CMake configure command to
explicitly set BUILD_PYTHON_BINDINGS=OFF alongside BUILD_PLUGIN_OAK_CAMERA,
while preserving the existing vcpkg toolchain and camera_plugin_oak build steps.
The one preset example for OAK, `cmake --preset py3.12 -DBUILD_PLUGIN_OAK_CAMERA=ON`, omits the vcpkg toolchain and so fails at configure time. Drop it: the plugin is C++ only, so a py3.NN preset says nothing about the build, and it wants its own tree anyway. Point both the options table and the examples section at the `-B build` form the OAK page already uses, now that build/ is free for it. Also note the trap behind NVIDIA#893 — CMAKE_TOOLCHAIN_FILE is fixed at first configure, so an existing build/ has to be deleted rather than re-configured — and drop the stale Hunter references; OAK/DepthAI has used vcpkg plus FetchContent for a while. Signed-off-by: Jiwen Cai <jiwenc@nvidia.com>
jiwenc-nv
force-pushed
the
jiwenc/oak-build-docs
branch
from
August 6, 2026 03:23
b7cb51d to
33426b7
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The one preset example for OAK,
cmake --preset py3.12 -DBUILD_PLUGIN_OAK_CAMERA=ONinbuild_from_source/index.rst, omits the vcpkg toolchain and so fails at configure time. Rather than repair it, drop it: the OAK plugin is C++ only, so apy3.NNpreset communicates nothing about the build, and it wants its own build directory anyway. Both the options table and the examples section now point at the-B buildform the OAK page already uses.Also documents the trap behind #893:
CMAKE_TOOLCHAIN_FILEis fixed when a build directory is first configured, so an existing tree has to be deleted (or another chosen) rather than re-configured. That constraint is CMake's rather than ours and is easy to miss from the error.Finally, drops the stale
SetupHunter.cmake/ "pulls Hunter/DepthAI" references — OAK/DepthAI has been vcpkg plus FetchContent for a while.Docs only; no build files touched. Independent of #913 — they touch different hunks and can merge in either order.
Testing
camera_plugin_oakon this branch (Ubuntu 24.04 aarch64, vcpkg + DepthAI 3.7.1). There is no auto-detection in play here, so the toolchain flag is load-bearing exactly as written.sphinx -Wbuilds clean.