Skip to content

developer.rst

Latest commit

 

History

History
131 lines (98 loc) · 5.18 KB

developer.rst

File metadata and controls

131 lines (98 loc) · 5.18 KB
Raw

Developer Guide

This guide describes how to consume the published Usd Optimize package from your own packman and premake based build, so that you can link against the library and call its C++ API.

To build Usd Optimize itself from source, or to consume a prebuilt binary drop directly, see the repository README.md and the install guides under docs/install-prebuilt-linux.md and docs/install-prebuilt-windows.md. Platform-specific requirements of the source build are covered under Platform build notes below.

Linking against the package

  1. Update your deps/target-deps.packman.xml to add a usd_optimize dependency with linkPath="../_build/target-deps/usd_optimize".

  2. Add a new file deps/usd-optimize-deps.packman.xml with the following contents:

    <project toolsVersion="5.0">
  <import path="../_build/target-deps/usd_optimize/dev/deps/all-deps.packman.xml">
    <filter include="autouv-core" />
    <filter include="omnimesh_ops_usd" />
  </import>

  <dependency name="autouv-core" linkPath="../_build/target-deps/omni_autouv_core" tags="non-redist"/>
  <dependency name="omnimesh_ops_usd" linkPath="../_build/target-deps/omnimesh_ops_usd" tags="non-redist"/>
</project>

  3. Update your repo.toml to pull the new file. For example:

    [repo_build]
fetch.packman_target_files_to_pull = [
    "${root}/deps/target-deps.packman.xml",
    "${root}/deps/usd-optimize-deps.packman.xml",
]

  4. Access the use_usd_optimize() function in your premake by adding the following sections.

    ...
usd_optimize_build = require(path.replaceextension(os.matchfiles("_build/target-deps/usd_optimize/*/dev/tools/premake/usd-optimize-public.lua")[1], ""))
...
project "foo_bar"
    usd_optimize_build.use_usd_optimize()
...

Calling the API

Once your project links against Usd Optimize, include the public header and drive operations through the core singleton:

#include <usd_optimize/core/Core.h>

The public C++ interface is documented in the :doc:`../api/api` reference. The equivalent Python entry points are described in :doc:`python`, and the operation catalog (with JSON configuration examples that apply equally to the C++ and Python paths) is in :doc:`operations`.

Extending Usd Optimize

New optimizations are added as plugins that subclass usd_optimize::Operation and register themselves with the core library. The full plugin authoring guide lives in PLUGINS.md in the repository root.

Platform build notes

These apply when building Usd Optimize from source with ./repo.sh build / repo.bat build.

(Windows) Host toolchain discovery. The build links a host-installed compiler (msbuild.link_host_toolchain in repo.toml), not packman msvc. If discovery fails, set msbuild.vs_path / msbuild.vs_version (and msbuild.winsdk_path for the SDK) in repo.toml — see repo_build toolchains. A Visual Studio install without the C++ toolset is not enough: if Microsoft.VCToolsVersion.default.txt is missing under VC/Auxiliary/Build, add the Desktop development with C++ workload via the Visual Studio Installer.

(Windows, non-English locale) Set PYTHONUTF8=1. Repo tooling reads UTF-8 config files, but Python on Windows decodes text using the system ANSI code page (CP949, CP932, GBK), which surfaces as a UnicodeDecodeError during repo.bat build. Enable UTF-8 mode:

set PYTHONUTF8=1        :: current session
setx PYTHONUTF8 1       :: persist for new shells
$env:PYTHONUTF8 = "1"   # current session

English/US Windows defaults to CP1252, which overlaps UTF-8 for ASCII and so usually hides this; PYTHONUTF8=1 is a harmless, safe default. See PEP 540.

(Linux) Extra requirements for ./repo.sh py_package. It needs outbound HTTPS/PyPI access — tools/pyproject/pybuild.sh pip-installs Poetry, auditwheel, patchelf, and related tools into _build/host-deps/py_package_venv/. If that bootstrap fails partway, remove the venv and rerun: rm -rf _build/host-deps/py_package_venv.

The Linux wheel does not bundle OpenUSD, oneTBB, or MaterialX. The usd-exchange wheel ships them under their original library names, the same names our binaries depend on, so packaging excludes them from auditwheel repair. At import, the package imports the pxr modules that load every library the core and the operation plugins need, and the loader reuses those by name wherever usd-exchange is installed. This requires usd-exchange 3.0.1 or later; 3.0.0 named those libraries after content hashes. Windows packaging already excludes the corresponding DLLs.

(Linux x86_64) C++11 ABI is enabled via premake.linux_x86_64_cxx_abi in repo.toml.