<a id="build-system"></a>

# Build System

<a id="project-structure"></a>

## Project structure

The layout below reflects the actual `CMakeLists.txt` hierarchy (root `CMakeLists.txt` and `src/core/CMakeLists.txt`):

```text
IsaacCapture/
├── CMakeLists.txt              # Top-level: deps, core, examples, plugins, etc.
├── cmake/
│   ├── DepthAIVcpkgManifest.cmake  # OAK/DepthAI vcpkg manifest (pre-project)
│   ├── SetupPython.cmake       # BUILD_PYTHON_BINDINGS, uv-managed Python
│   ├── ClangFormat.cmake       # clang_format_check / clang_format_fix
│   └── ...
├── deps/
│   ├── CMakeLists.txt          # Adds third_party
│   ├── third_party/CMakeLists.txt  # FetchContent: OpenXR, yaml-cpp, pybind11, etc.
│   └── cloudxr/                # CloudXR (CI / optional)
├── src/core/
│   ├── CMakeLists.txt          # Core options, subdirs in dependency order
│   ├── schema/                 # FlatBuffer schemas and generated code
│   ├── oxr_utils/              # Header-only OpenXR utilities
│   ├── plugin_manager/         # Plugin manager (C++ and Python)
│   ├── oxr/                    # OpenXR session management (C++ and Python)
│   ├── pusherio/               # PusherIO (depends on oxr)
│   ├── deviceio/               # Device I/O library (C++ and Python)
│   ├── mcap/                   # MCAP recording (depends on deviceio)
│   ├── retargeting_engine/     # Retargeting (Python)
│   ├── retargeting_engine_ui/  # Retargeting UI (Python)
│   ├── teleop_session_manager/ # Teleop session manager (Python)
│   ├── cloudxr/                # CloudXR runtime helper (Python)
│   └── python/                 # Python wheel packaging (when BUILD_PYTHON_BINDINGS=ON)
├── src/python/isaaccapture/
│   └── ovxr_session_manager/   # OVXR session ownership and presentation
├── src/plugins/                # Built when BUILD_PLUGINS=ON
│   ├── plugin_utils/
│   ├── controller_synthetic_hands/
│   ├── generic_3axis_pedal/
│   ├── manus/
│   ├── oak/                    # When BUILD_PLUGIN_OAK_CAMERA=ON
|   └── haptikos/
├── tests/python/core/
│   └── ovxr_session_manager/   # OVXR session and presentation tests
└── examples/
    ├── oxr/                    # OpenXR examples (C++ and Python)
    ├── retargeting/
    ├── teleop_session_manager/
    ├── teleop_ros2/
    ├── schemaio/
    └── native_openxr/
```

<a id="cmake-integration"></a>

## CMake integration

The project uses a modern CMake target-based approach. Libraries export namespaced alias targets (e.g. `oxr::oxr_core`, `deviceio::deviceio_session`, `isaacteleop_schema`); include directories are propagated. Package config files are generated for use after install. See the respective `CMakeLists.txt` in `src/core` and under `examples/` for target names and usage.

<a id="using-the-python-wheel"></a>

## Using the Python wheel

After building, activate a virtual environment with the build’s Python version
([step 4 of Build from source](../development/build_from_source/index.md#build-from-source-install-package) shows how), then install the wheels with `uv` or
`pip`, pinning the local build’s version `X.Y+local` (`X.Y` from the repository’s `VERSION`
file):

```bash
# The pin keeps a newer release on the index from winning over the local build.
# --find-links exposes the sibling isaacteleop transition wheel built alongside isaaccapture.
uv pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture

# or
pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/ --force-reinstall
```

The wheel carries the `isaacteleop` compatibility alias, which will be removed
in 1.9, so
`import isaacteleop` resolves without a second install; see [Migrating to isaaccapture](../development/migration.md).

<a id="installing-from-source-with-pip-scikit-build-core"></a>

## Installing from source with pip (scikit-build-core)

In addition to the classic CMake flow above (which stages the package
and produces a wheel under `install/wheels/`), the repository ships a root
[pyproject.toml](https://github.com/NVIDIA/IsaacCapture/blob/main/pyproject.toml) that exposes `isaaccapture` through the
[scikit-build-core](https://scikit-build-core.readthedocs.io/) build backend,
driving the *same* top-level `CMakeLists.txt` (so the two paths coexist). Run it inside an
activated virtual environment as well:

```bash
pip install .            # build + install the compiled wheel from source
pip install -e .         # editable / developer install
```

This path installs no CloudXR runtime, so nothing that starts CloudXR runs under it.
For the walkthrough — how this scoped build differs from the classic flow (ABI,
omitted type stubs, versioning) and the caveat on iterating on pure-Python
subpackages under an editable install — see
[Build from Source](../development/build_from_source/index.md).

<a id="build-directory-layout-and-per-python-version-builds"></a>

## Build directory layout and per-Python-version builds

A CMake binary directory holds exactly one configured Python version — the
interpreter and ABI are baked into `CMakeCache.txt` and into the build venv. The
two build paths therefore never share a directory:

- **classic CMake** → whatever you pass to `-B`, `build/` by convention.
  `ISAAC_TELEOP_PYTHON_VERSION` selects the interpreter (default `3.11`), and
  changing it on an existing tree is rejected with an error rather than silently
  reusing the old one — delete the tree to switch versions.
  ```bash
  cmake -B build                                            # default 3.11
  cmake --build build --parallel
  cmake --install build

  cmake -B build -DISAAC_TELEOP_PYTHON_VERSION=3.12         # after rm -rf build
  ```
- **pip / scikit-build-core** → `build-wheel/<cache-tag>/` (e.g.
  `build-wheel/cpython-312/`), set by `build-dir` in
  [pyproject.toml](https://github.com/NVIDIA/IsaacCapture/blob/main/pyproject.toml) and chosen automatically per interpreter, keyed off
  `sys.implementation.cache_tag`. It lives outside `build/` so `pip install`
  and a classic `cmake -B build` never collide, and `rm -rf build` leaves the
  incremental wheel tree intact.

`build/` and `build-wheel/` are gitignored.

<a id="output-locations"></a>

## Output locations

After a successful build and install, relative to your build directory:

- **C++ libraries:** `src/core/` (and under each module)
- **Examples (binaries):** under `examples/` (e.g. `examples/oxr/cpp/`)
- **Installed files:** `install/` (or your `CMAKE_INSTALL_PREFIX`)
  - Libraries: `install/lib/`
  - Headers: `install/include/`
  - Wheels: `install/wheels/`
  - Examples: `install/examples/`

<a id="troubleshooting"></a>

## Troubleshooting

<a id="dependencies-fail-to-download"></a>

### Dependencies fail to download

FetchContent in `deps/third_party/CMakeLists.txt` requires network access. If downloads fail, check connectivity. Key repositories:

- OpenXR SDK: [https://github.com/KhronosGroup/OpenXR-SDK.git](https://github.com/KhronosGroup/OpenXR-SDK.git)
- pybind11: [https://github.com/pybind/pybind11.git](https://github.com/pybind/pybind11.git)
- yaml-cpp: [https://github.com/jbeder/yaml-cpp.git](https://github.com/jbeder/yaml-cpp.git)
- FlatBuffers, Catch2, MCAP: see `deps/third_party/CMakeLists.txt` for URLs and tags.

You can inspect the `_deps` directory in your build tree for fetch logs.

<a id="cmake-can-t-find-openxr"></a>

### CMake can’t find OpenXR

OpenXR is fetched automatically; it is not a system package. If configuration fails, try a clean configure
(`--fresh` wipes the CMake cache and reconfigures):

```bash
cmake -B build --fresh
```

<a id="examples-or-tests-can-t-find-the-library"></a>

### Examples or tests can’t find the library

When building from the top-level, examples and tests use the build tree. Ensure you run
`cmake --build build` from the project root and run executables from the build directory
(or use `cmake --install build` and run from `install/`).

<a id="uv-or-python-version"></a>

### uv or Python version

`cmake/SetupPython.cmake` requires **uv** and uses `ISAAC_TELEOP_PYTHON_VERSION`. Install uv as
in [One time setup](../development/build_from_source/index.md#one-time-setup) and pass `-DISAAC_TELEOP_PYTHON_VERSION=3.12` (or 3.11,
3.13) if you need a specific version.

<a id="reference"></a>

## Reference

- Root build and options: `CMakeLists.txt`
- Core modules and options: `src/core/CMakeLists.txt`
- Dependencies: `deps/third_party/CMakeLists.txt`
- Python and uv: `cmake/SetupPython.cmake`
- OAK/DepthAI vcpkg manifest: `cmake/DepthAIVcpkgManifest.cmake`
- CI (Ubuntu, matrix build_type/python_version/arch): `.github/workflows/build-ubuntu.yml`
