Project Setup (C)
When to Use
Use this skill when the user asks to create a new C/C++ consumer of ovstage, declare an ovstage dependency, include the ovstage headers, or build/link code against ovstage.
Inputs
Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.
- The consuming target type: unit test, benchmark, plugin, or application.
- Whether the consumer also interns tokens / builds path lists (the path dictionary,
obtained from the instance via
ovstage_get_path_dictionary) and/or exchanges tensor data (DLPack,<dlpack/...>). Both come with<ovstage/ovstage.h>. - How the consumer's build system adds an include directory and a link dependency.
- Repository source snippets referenced below. Treat these snippets as the API source of truth.
Prerequisites
- Use an ovstage checkout that contains the
include/headers and the referenced example. - Read the relevant
> **Source:**snippet before writing or explaining API usage. - Be able to add an include directory and a link dependency in the consumer's build system.
Instructions
- Include
<ovstage/ovstage.h>for the data-plane API,ovstage_get_path_dictionary, and the path-dictionary/DLPack types. To call the path-dictionary functions, also include<ovx/path_dictionary/path_dictionary.h>and<ovx/path_dictionary/path_dictionary_utils.h>(the inline wrappers) directly, as the minimal example does;<dlpack/dlpack.h>covers the tensor types. - Add ovstage's
include/to the consumer's include path and link the ovstage library. - Follow the minimal example's lifecycle (see Minimal Usage) for the create → query → write → advance → read → release ordering.
- Build and run the narrow target; see the
error-handlingskill for status checking.
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.
- Pre-release. The ovstage package and its CMake config ship pre-release; pins and packaging details may change between releases.
- C only. For Python project setup see
project-setup-python. - ⚠️ Draft — API in flux. The ovstage C API is still changing materially; treat this setup (especially exact symbol/usage in the minimal example) as provisional.
- Snippets are sourced from the shipping example
examples/c/minimal/main.cpp.
Overview
ovstage is a pure C API:
- Public headers:
include/—<ovstage/ovstage.h>(data plane + path-dictionary/DLPack types), plus<ovx/path_dictionary/path_dictionary.h>(+path_dictionary_utils.h) to call the path-dictionary functions, and<dlpack/dlpack.h>for tensor types. - Library: consumers link a public ovstage loader and include the public headers.
The released package ships a CMake config (
lib/cmake/ovstage/), so a standalone consumer usesfind_package(ovstage REQUIRED)+target_link_libraries(<target> PRIVATE ovstage::ovstage).
Dependency Declaration (CMake, standalone)
Model a new standalone consumer on the shipping examples: each example's
CMakeLists.txt (e.g. examples/c/minimal/CMakeLists.txt) includes the shared
module examples/c/cmake/ovstage.cmake and calls ovstage_fetch() — which tries
find_package(ovstage QUIET) first and otherwise downloads the pinned released
package zip — then:
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE ovstage::ovstage)
ovstage_setup_runtime(myapp)
ovstage_setup_runtime() sets an rpath onto the package bin/ on Linux; on
Windows put the package bin/ on PATH at runtime. ovstage::ovstage is the
shared forwarding loader; it opens the colocated runtime on the first
initialize/create call. Keep the package bin/ layout intact so the runtime
remains beside its plugins/ closure.
To consume a manually downloaded package without the examples' fetch module, see "Standalone build and run (published package)" below.
Headers
| Header | Purpose |
|---|---|
<ovstage/ovstage.h> |
Include this. Declares instance lifecycle (ovstage_create_instance / ovstage_destroy_instance) and transitively pulls the whole ovstage_api/ surface below plus the path-dictionary + DLPack types. |
↳ ovstage_api/ovstage_api_utils.h |
The flat inline ovstage_* wrappers you call — ovstage_get_path_dictionary, ovstage_query_from_path_list, ovstage_write_attribute, ovstage_advance_write_floor, ovstage_read_attributes, ovstage_wait_op, ovstage_release_op, … (reached via ovstage.h; no need to include directly). |
↳ ovstage_api/ovstage_api.h |
The vtable those wrappers dispatch through, plus the execution-model reference. Reached via ovstage.h. |
↳ ovstage_api/ovstage_api_types.h |
Structs / enums — ovstage_enqueue_result_t, ovstage_op_wait_result_t, status codes, and the DLPack + path-dictionary types. |
<ovx/path_dictionary/path_dictionary.h> (+ path_dictionary_utils.h) |
The path-dictionary functions — path_dictionary_* interning, path lists, and the inline wrappers. Not pulled in transitively by <ovstage/ovstage.h>; include directly to call them (as the minimal example does). |
<dlpack/dlpack.h> |
DLTensor types for attribute data exchange (available transitively; the example includes it explicitly). |
Minimal Usage
Create an instance, get its (instance-owned) path dictionary, intern tokens / build path
lists, then write/advance/read. The path dictionary is owned by the instance — there is no
app-side create/destroy; you obtain it with ovstage_get_path_dictionary(instance) (check
for a NULL return before use). The minimal example shows the end-to-end shape:
Source:
examples/c/minimal/main.cppsnippetminimal-write-read
The essential ordering is: ovstage_create_instance → ovstage_get_path_dictionary →
path_dictionary_create_path_list_from_strings / intern tokens →
ovstage_query_from_path_list → ovstage_write_attribute → ovstage_advance_write_floor →
ovstage_read_attributes / ovstage_fetch_read_next → release (release path-list
references via path_dictionary_release_path_list_reference, then destroy the instance).
See the error-handling skill for status checking and the minimal-write-read snippet
above for the full lifecycle.
The write declares attribute kind explicitly: the fixed-size write in minimal-write-read
sets write.is_array = false; array attributes set write.is_array = true. Attribute kind
is never inferred from tensor shape or count.
Standalone build and run (published package)
An external C/C++ consumer builds against the published ovstage package — public headers,
the shared loader, runtime, and a CMake config — with no ovstage source checkout.
The config exports ovstage::ovstage (shared loader) and
ovstage::ovstage_static (static loader).
Get the package
Download the ovstage package archive for your platform — manylinux_2_35_x86_64,
manylinux_2_35_aarch64, or windows-x86_64 — from the repository releases page
(each release attaches the per-platform package zips), and unzip it (e.g. to
ovstage-pkg/).
The unzipped tree has include/ (ovstage + ovx + dlpack headers), bin/ (the shared
loader, runtime, and runtime closure), and lib/cmake/ovstage/ (the CMake config). Pin the exact package version your
code targets — it tracks the build the API matches — the same way the Python example pins
its wheel.
Build against it
Point CMAKE_PREFIX_PATH at the unzipped package and find_package(ovstage):
cmake_minimum_required(VERSION 3.20)
project(ovstage_consumer CXX)
find_package(ovstage REQUIRED) # from lib/cmake/ovstage/ovstageConfig.cmake
add_executable(app main.cpp)
target_link_libraries(app PRIVATE ovstage::ovstage) # include dir + library come with the target
cmake -B build -DCMAKE_PREFIX_PATH="$PWD/ovstage-pkg"
cmake --build build --config Release
# The shared library ships under the package's bin/; put it on the loader path at runtime:
LD_LIBRARY_PATH="$PWD/ovstage-pkg/bin" ./build/app # Linux
# Windows: add ovstage-pkg\bin to PATH before running app.exe
No manual -I/-l is needed — the ovstage::ovstage target carries the include directory and
links the shared loader. Note the path-dictionary split: <ovstage/ovstage.h> pulls the
path-dictionary types but not the path_dictionary_* functions — include
<ovx/path_dictionary/path_dictionary.h> directly to call them (see Headers above).
Troubleshooting
- Headers not found (
ovstage/ovstage.hmissing): ensure the consumer's include path contains ovstage'sinclude/; the data-plane API is reached transitively via<ovstage/ovstage.h>→ovstage_api/ovstage_api.h. - Link errors for
ovstage_*symbols: linkovstage::ovstageorovstage::ovstage_static; do not link runtime implementation libraries directly. ovstage_get_error_string/ diagnostics need an instance: these are vtable-dispatched and take theovstage_instance_t*; you cannot stringify an error beforeovstage_create_instancereturns — print the numeric code in that window.- Linux link fails with
libX11.so.6/libGL.so.1 ... not found (try using -rpath or -rpath-link)or undefinedXOpenDisplay/glX*references againstlibov_*usd_ms.so: the linker cannot resolve the pre-packaged runtime's system dependencies. Either the host is missinglibx11-6/libgl1/libgomp1(install them), or a Homebrew/LinuxbrewldonPATHreplaced the distribution linker (see next bullet). - Linux build fails with
GLIBC_2.xx' not found(possibly already at compile time, fromas) or X11/GL link errors although the system libraries are installed, and Homebrew/Linuxbrew exists on the host: GCC findsasandldviaPATH, and Homebrew links its ownbinutilsby default (since June 2026), so the system compiler silently uses Homebrew's tools and resolves glibc/libgomp against Homebrew's copies. Fix:brew unlink binutils, or strip the Homebrewbindir fromPATHfor the build, or add-B/usr/binto compiler flags.find_package(ovstage)warns at configure time when it detects a Homebrew linker; pass-DOVSTAGE_SKIP_LINKER_CHECK=ONto CMake (or set that environment variable) to silence the check.
References
- Use the
> **Source:**directives in this skill to locate tested snippets before reusing API patterns. error-handling,string-handlingskills — API usage detail.- Keep related skills, docs, and snippets synchronized when changing the workflow.