/project-setup-c

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: project-setup-c
description: >
  Setting up a new CMake C/C++ project that uses ovrtx. Use when user asks to create a
  new C project, set up CMake with ovrtx, scaffold a C++ app, or configure build
  dependencies.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - c
  - setup
tools:
  - Read
  - Grep
  - Shell
  - Write

Project Setup (C)

When to Use

Use this skill when the user asks to create a new C project, set up CMake with ovrtx, scaffold a C++ app, or configure build dependencies.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Project language, package manager, build system, and target platform from the user request.
• Whether the project should use packaged ovrtx or the local dev-mode build.
• Repository source snippets and example projects referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Confirm Python, CMake, compiler, and package-index requirements before giving setup commands.
• Avoid modifying tracked dependency files unless the user explicitly asks for project scaffolding changes.

Instructions

1. Identify the requested project type, platform, package source, and expected run command. 2. Read the minimal example and setup snippets before writing scaffolding. 3. Use the repository's existing Python or CMake conventions instead of inventing a new layout. 4. Include renderer creation and first-frame validation only after the project dependency setup is complete. 5. When changing code, run the narrow example setup or docs test whenever practical.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

ovrtx provides a C API with a CMake config for easy integration. The recommended approach uses CMake FetchContent to download the ovrtx binary package from GitHub Releases. A convenience macro in `ovrtx.cmake` handles fetching, finding, and runtime setup.

Project Structure

my-ovrtx-app/
  CMakeLists.txt
  cmake/
    ovrtx.cmake       # Copy from examples/c/cmake/ovrtx.cmake
  main.cpp

CMakeLists.txt

> **Source:** `examples/c/minimal/CMakeLists.txt` snippet `project-setup` > > **Source (continued):** `examples/c/minimal/CMakeLists.txt` snippet `linking-models` > > The canonical example builds both loader models with ovstage attached. For an > ovrtx-only application, omit the ovstage fetch, link target, and setup call.

ovrtx.cmake

Copy `examples/c/cmake/ovrtx.cmake` into your project's `cmake/` directory. The key macro it provides:

• `ovrtx_fetch()` -- downloads the ovrtx package via FetchContent and makes both `ovrtx::ovrtx` (shared loader) and `ovrtx::ovrtx_static` (static loader) available.
• `ovrtx_setup_runtime(TARGET)` -- auto-selects the runtime layout from how the target links ovrtx. For `ovrtx::ovrtx_static` (model #1) it stages a single side-by-side `ovrtx/` link pointing at the package `bin/`. For `ovrtx::ovrtx` (model #2) it configures rpath (Linux) or copies DLLs and creates runtime-directory junctions (Windows).

Update the `FetchContent_Declare` URL inside `ovrtx.cmake` to point to the appropriate GitHub Releases package for your platform.

Minimal main.cpp

> **Source:** `examples/c/minimal/main.cpp` snippet `check-error-helper` > > **Source (continued):** `examples/c/minimal/main.cpp` snippet `create-renderer` > > **Source (continued):** `examples/c/minimal/main.cpp` snippet `load-usd-and-wait` > > See the full minimal example for the complete flow including step, fetch, map, and cleanup.

Build and Run

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/my-ovrtx-app

Runtime Packaging

The ovrtx binary distribution includes runtime dependencies under `bin/`:

bin/
  libovrtx-dynamic.so / ovrtx-dynamic.dll
  cache/
  library/
  libs/
  mdl/
  plugins/
  rendering-data/
  usd_plugins/

**Static loader (model #1).** Link `ovrtx::ovrtx_static` and pass the package root to `ovrtx_create_renderer()` via `ovrtx_config_entry_binary_package_root_path()`. Build the path from `OVX_CONFIG_EXECUTABLE_DIR_TOKEN "/ovrtx"` so the loader resolves it against the running executable's directory at runtime. `ovrtx_setup_runtime()` stages the matching side-by-side `ovrtx/` link pointing at the package `bin/`, keeping the exe directory self-contained without baking an absolute path into the binary:

> **Source:** `examples/c/minimal/main.cpp` snippet `create-renderer`

**Shared loader (model #2).** Link `ovrtx::ovrtx`; the operating system loads only the forwarding loader. The loader opens the ovrtx runtime on the first initialization call. ovrtx expects the `bin/` runtime directories (`cache/`, `library/`, `libs/`, `mdl/`, `plugins/`, `rendering-data/`, `usd_plugins/`) next to `ovrtx-dynamic.dll` / `libovrtx-dynamic.so`, and `ovrtx_setup_runtime()` configures rpath (Linux) or copies DLLs + creates junctions (Windows). In this mode `binary_package_root_path` is only needed when your install/deploy layo