project-venv-setup

name	project-venv-setup
version	1.19.1
license	Apache-2.0
description	Use when setting up a local usd-validation-nvidia venv for builds, tests, or nvidia_usd_validate. Do NOT use for plugin scaffolding.
metadata	{"author":"NVIDIA","tags":["usd-validation","venv","build","test"]}
compatibility	Requires Python 3.10-3.12, pip and venv, network access to Python package indexes, and Linux/macOS shell or Windows PowerShell command syntax.

Project Virtual Environment Setup

Purpose

usd-validation-nvidia can be built and tested from a plain Python virtual environment. This skill shows how to create a local .venv, generate the capabilities package required by source builds, build the wheel, install that wheel into the virtual environment, run the unit tests, and use the nvidia_usd_validate command.

Prerequisites

• Python 3.10-3.12.
• pip, venv, and package-index access.

Project Structure

usd-validation-nvidia/
  .venv/
  dist/
  specs/
  src/
  tests/

Run these commands from the repository root. The generated src/usd_validation_nvidia/capabilities/ package is an ignored build prerequisite and must not be edited by hand.

Verify Python Version

This skill requires Python 3.10-3.12. Before creating .venv, run python3.11 --version or py -3.11 --version on Windows; use 3.10 or 3.12 instead if that is the supported interpreter. If no supported interpreter is available, stop with: "This skill requires Python 3.10-3.12. Install a supported interpreter, then rerun."

Setup with venv (Recommended)

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip build
python -m pip install usd-profiles-nvidia

On Windows:

py -3.11 -m venv .venv
./.venv/Scripts/Activate.ps1
python -m pip install --upgrade pip build
python -m pip install usd-profiles-nvidia

Build from Source

Generate the capabilities package, then build the wheel:

python -m usd_profiles_nvidia.codegen \
  --docs-root specs \
  --destination-dir src \
  --package-name usd_validation_nvidia.capabilities \
  --reverse-domain com.nvidia.usd

python -m build --wheel --outdir dist

On Windows:

python -m usd_profiles_nvidia.codegen `
  --docs-root specs `
  --destination-dir src `
  --package-name usd_validation_nvidia.capabilities `
  --reverse-domain com.nvidia.usd

python -m build --wheel --outdir dist

Install Built Wheel

Install the built wheel into the virtual environment with the same OpenUSD and NumPy versions used by the CI smoke test:

wheel=$(ls -t dist/usd_validation_nvidia-*.whl | head -n 1)
python -m pip install "$wheel" "usd-core==25.11" "numpy==2.2"

On Windows:

$wheel = (
  Get-ChildItem ./dist/usd_validation_nvidia-*.whl |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1
).FullName
python -m pip install $wheel usd-core==25.11 numpy==2.2

Use python -m pip install --force-reinstall "$wheel" after rebuilding if the virtual environment already has an older local wheel installed.

Run

Run the test suite against the installed wheel:

python -m unittest discover -s tests

On Windows:

python -m unittest discover -s tests

Run the command line validator from the activated virtual environment:

nvidia_usd_validate --help
nvidia_usd_validate --no-init-rules --rule DefaultPrimChecker examples/assets/asset.usda

On Windows:

nvidia_usd_validate --help
nvidia_usd_validate --no-init-rules --rule DefaultPrimChecker examples/assets/asset.usda

Key Types / Functions

• python -m venv .venv: creates the local virtual environment.
• python -m usd_profiles_nvidia.codegen: generates usd_validation_nvidia.capabilities from specs/.
• python -m build --wheel --outdir dist: builds the source tree into a wheel.
• python -m unittest discover -s tests: runs the repository test suite.
• nvidia_usd_validate: validates USD assets from the installed package's console script.

Key Dependencies

Package	Purpose
build	PEP 517 wheel build frontend for source builds inside the venv
usd-profiles-nvidia	Capability, feature, and requirement code generation package
usd-core==25.11	OpenUSD runtime dependency used by the CI wheel smoke test example
numpy==2.2	Optional NumPy dependency used by the CI wheel smoke test example

Limitations

• Sets up a local Python virtual environment only; it does not publish release artifacts.
• CI parity depends on testing the built wheel rather than importing the editable source tree.

Common Pitfalls

• Use Python 3.10-3.12; the examples above prefer Python 3.11.
• Activate the virtual environment before installing build tools, generated-code dependencies, the wheel, or test dependencies.
• Generate src/usd_validation_nvidia/capabilities before building; skipping it causes hatchling to fail because a forced include is missing.
• Build and test against the wheel in dist/ rather than the editable source tree when checking CI parity.
• Reinstall the wheel after rebuilding, otherwise nvidia_usd_validate may still run code from the previous build.
• Use a focused rule such as DefaultPrimChecker for CLI smoke tests; running the full default rule set can exercise optional OpenUSD shader resources that are environment-dependent.

Troubleshooting

• If the wheel build fails because a forced include is missing, generate src/usd_validation_nvidia/capabilities before running python -m build.
• If nvidia_usd_validate still runs old code after a rebuild, reinstall the newest wheel from dist/ in the active virtual environment.