OpenUSD 高级构建配置完全指南:从 build_usd.py 到 CMake 参数详解
2026/9/16 20:11:21 网站建设 项目流程

OpenUSD 高级构建配置完全指南:从 build_usd.py 到 CMake 参数详解

【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD

本文是 OpenUSD(Universal Scene Description)仓库中 BUILDING.md 的深度解读与实践指南,围绕"如何按需构建 OpenUSD"这一核心主题展开:既覆盖最简便的build_usd.py一键构建方式,也系统讲解直接调用 CMake 时的全部关键选项,包括可选组件开关、Imaging 插件、第三方插件、四种链接模式、测试运行与常见构建问题。读完本文,你将能够根据自身平台(Linux / macOS / Windows / WebAssembly)与功能需求(Python 绑定、Hydra 渲染、文档生成、插件集成等)定制出可复现的构建配置。

构建路径总览:两种方式如何选择

OpenUSD 提供两条构建路径:

  1. build_usd.py脚本:位于 build_scripts/build_usd.py,是最简单的构建方式。它会自动下载所需的第三方依赖(TBB、OpenSubdiv 等),与 USD 一起构建并安装到指定目录。适合大多数希望快速获得完整可用环境、又不愿手工管理依赖的用户。
  2. 直接使用 CMake:用户通过-D参数指定 USD 要链接的第三方库路径及各类构建选项。适合需要对构建产物进行精细控制(如嵌入自有工程、交叉编译、定制链接模式)的场景。

README 的 Getting and Building the Code 一节说明了脚本构建的默认行为:默认构建 USD 核心库、Imaging 与 USD Imaging 组件。关于脚本的更多选项,运行python build_scripts/build_usd.py --help即可查看。

需要特别注意的是:构建脚本设计为源码树外构建(out-of-source build),将构建产物直接安装进仓库克隆目录是未经测试的用法(见 README.md)。

使用 build_usd.py 一键构建

基本用法是为脚本传入一个安装目录作为位置参数,脚本会完成依赖下载、依赖构建、USD 构建与安装的全流程:

python OpenUSD/build_scripts/build_usd.py /path/to/my_usd_install_dir

从源码看,脚本的核心参数(build_scripts/build_usd.py)包括:

参数默认值说明
install_dir(位置参数)必填USD 安装目录
-n, --dry_run关闭仅汇总将要执行的操作,不实际构建
-j, --jobsCPU 核数并行构建任务数
--build<install_dir>/buildUSD 与第三方依赖的构建目录
--build-variantrelease取值debug/release/relwithdebuginfo
--build-target平台默认交叉编译目标,如iOSvisionOSwasmwasm64
--src<install_dir>/src依赖源码下载目录
--inst<install_dir>依赖安装目录
--generator/--toolsetCMake 默认指定 CMake 生成器与工具集
--build-args向指定库透传自定义构建参数,如--build-args USD,"-DPXR_STRICT_BUILD_MODE=ON ..."
--cmake-build-args向所有使用 CMake 的构建统一透传参数(单个字符串)
--force/--force-all强制重新下载并构建指定库 / 全部库
--compiler-cache/--no-compiler-cachemacOS/Linux 开、Windows 关是否使用 ccache 加速增量编译
--materialx/--no-materialx开启是否构建 MaterialX 支持(脚本默认启用,与纯 CMake 默认关闭不同)

平台差异要点

  • macOS:先执行xcode-select确保命令行开发者工具可用;Apple Silicon 上默认启用代码签名(可用--codesign-id指定签名 ID),且提供--ignore-homebrew让 CMake 忽略 Homebrew 包(build_scripts/build_usd.py)。
  • iOS / visionOS:在 macOS 上通过--build-target iOS/--build-target visionOS交叉编译,此类构建不支持 Python 绑定与命令行工具,建议配合--build-monolithic单体构建以便嵌入应用。还可用--build-apple-framework产出 Apple Framework(实验特性,默认要求单体构建)。
  • Windows:需在 Visual Studio 的 "x64 Native Tools Command Prompt"(或 ARM64 版本)中运行脚本。
  • Linux:可传--use-cxx11-abi 0|1选择 libstdc++ 的 C++11 ABI。

直接使用 CMake 构建

当需要精细控制时,可跳过脚本直接调用 CMake。文档给出的三个平台示例均以 TBB 与 OpenSubdiv 两个典型外部依赖为例:

Linux

cmake \ -DTBB_ROOT_DIR=/path/to/tbb \ -DOPENSUBDIV_ROOT_DIR=/path/to/opensubdiv \ /path/to/USD/source cmake --build . --target install -- -j <NUM_CORES>

macOS(生成 Xcode 工程)

cmake \ -G "Xcode" \ -DTBB_ROOT_DIR=/path/to/tbb \ -DOPENSUBDIV_ROOT_DIR=/path/to/opensubdiv \ /path/to/USD/source cmake --build . --target install -- -j <NUM_CORES>

Windows(生成 Visual Studio 工程)

"C:\Program Files\CMake\bin\cmake.exe" ^ -G "Visual Studio 15 2017 Win64" ^ -DTBB_ROOT_DIR=C:\path\to\tbb ^ -DOPENSUBDIV_ROOT_DIR=C:\path\to\opensubdiv ^ \path\to\USD\source cmake --build . --target install -- /m:%NUMBER_OF_PROCESSORS%

对于更新的 Visual Studio 版本,使用如下生成器参数:

  • VS2019:-G "Visual Studio 16 2019" -A x64
  • VS2022:-G "Visual Studio 17 2022" -A x64

WebAssembly 构建

Wasm 构建需要先安装 Emscripten 工具链,并先为 32/64 位 wasm 构建 oneTBB 并安装。随后执行:

emcmake cmake \ -DCMAKE_INSTALL_PREFIX="/path/to/build/openusd_wasm" \ -DCMAKE_PREFIX_PATH="/path/to/build/openusd_wasm" \ -DPXR_BUILD_TESTS=ON \ -DPXR_BUILD_EXAMPLES=OFF \ -DPXR_BUILD_IMAGING=OFF \ -DCMAKE_FIND_ROOT_PATH="/path/to/build/tbb_wasm" \ -DBUILD_SHARED_LIBS=OFF \ -DCMAKE_CXX_FLAGS="-pthread --use-port=zlib" \ -DCMAKE_C_FLAGS="-pthread --use-port=zlib" \ -DCMAKE_EXE_LINKER_FLAGS="-pthread" \ "/path/to/src/OpenUSD" emmake cmake --build . --config Release --target install -j 8

要点:

  • 默认构建32 位Wasm;如需 64 位,需在CMAKE_C_FLAGS中追加-sMEMORY64=1,并事先构建 Wasm64 版本的 oneTBB。
  • 从源码看,针对 Wasm 目标,构建系统会自动强制关闭不支持的组件:PXR_BUILD_EXEC=OFFBUILD_SHARED_LIBS=OFF(共享库在 wasm 下不受支持,见 cmake/defaults/Options.cmake)。
  • Wasm 构建会把plugInfo.json等资源文件在链接阶段嵌入产物二进制,挂载到虚拟文件系统的/usd目录下,供 usd 库加载类型与 schema 使用。

可选组件:按需裁剪或扩展构建

USD 含多个默认启用但可关闭的可选组件。关闭组件即可免去对应依赖。以下组件开关的默认值均可从 cmake/defaults/Options.cmake 中核实。

Python 支持(PXR_ENABLE_PYTHON_SUPPORT,默认ON

依赖 Python 的组件包括:USD 工具集(Toolset)、第三方插件、USD C++ API 的 Python 语言绑定、基于 Python 的单元测试。支持的 Python 版本见 VERSIONS.md。关闭方式:

-DPXR_ENABLE_PYTHON_SUPPORT=FALSE

默认情况下,Python 绑定安装到CMAKE_INSTALL_PREFIX下的标准 site-packages 目录:

  • Linux / macOS:<prefix>/lib/pythonX.Y/site-packages
  • Windows:<prefix>/Lib/site-packages

如需自定义安装目录,设置PXR_PYTHON_INSTALL_DIR(可为相对CMAKE_INSTALL_PREFIX的路径或绝对路径),例如恢复旧版布局:

-DPXR_PYTHON_INSTALL_DIR=lib/python

使用绑定时需将安装目录加入PYTHONPATH;但如果把CMAKE_INSTALL_PREFIX指向 virtualenv 根目录,默认设置下无需额外配置。

OpenGL(PXR_ENABLE_GL_SUPPORT,默认ON

-DPXR_ENABLE_GL_SUPPORT=FALSE

关闭后将跳过依赖 GL 的组件与库,包括 usdview 与 Hydra GL imaging。

Metal(PXR_ENABLE_METAL_SUPPORT,Apple 平台默认ON

构建需 macOS Mojave(10.14)及以上:

-DPXR_ENABLE_METAL_SUPPORT=FALSE

关闭后将跳过依赖 Metal 的组件与库(主要是 Hydra imaging)。从源码看,非 Apple 平台上该选项会被强制置回OFF(cmake/defaults/Options.cmake)。

Vulkan(PXR_ENABLE_VULKAN_SUPPORT,默认OFF,实验性)

启用需安装 Vulkan SDK 与 glslang,并将VULKAN_SDK环境变量指向 SDK 位置;Windows 上构建 debug 版时还需安装 Vulkan SDK 的 "Shader Toolchain Debug Symbols" 可选组件。启用:

-DPXR_ENABLE_VULKAN_SUPPORT=TRUE

MaterialX(PXR_ENABLE_MATERIALX_SUPPORT,CMake 默认OFF

-DPXR_ENABLE_MATERIALX_SUPPORT=TRUE

注意需要带共享库支持的 MaterialX。使用build_usd.py时默认启用,可用--materialx/--no-materialx覆盖。CMake 方式需额外提供依赖:

依赖名说明
MaterialX_DIRMaterialX SDK 安装的 CMake 包配置路径

OSL(PXR_ENABLE_OSL_SUPPORT,默认OFF

-DPXR_ENABLE_OSL_SUPPORT=TRUE

启用后,Shader Definition Registry(sdr)可以解析 OSL 着色器中的元数据。

文档生成(PXR_BUILD_DOCUMENTATION,默认OFF

-DPXR_BUILD_DOCUMENTATION=TRUE

需提供DOXYGEN_EXECUTABLE(Doxygen 位置)。文档分为两个子组件:

  • HTML 文档PXR_BUILD_HTML_DOCUMENTATION,默认TRUE):包含 USD 概述、通用概念与 C++ API 文档。需额外提供DOT_EXECUTABLE(GraphViz 的 dot)。仅在PXR_BUILD_DOCUMENTATION=TRUE时生效。
  • Python 文档PXR_BUILD_PYTHON_DOCUMENTATION,默认FALSE):为 Python 实体生成 docstring。前提是 Python 支持与文档生成均启用。该过程使用 docs/python 目录下的脚本,从生成的 Doxygen XML 中提取文档并与构建出的 Python 模块中的类、函数、属性匹配,生成__DOC.py文件安装到各 Python 模块目录,模块加载时注入 docstring。

Imaging(PXR_BUILD_IMAGING,默认ON

Imaging 组件包含 Hydra 高性能图形渲染引擎。关闭:

-DPXR_BUILD_IMAGING=FALSE

从 cmake/defaults/Options.cmake 可见,关闭 Imaging 会连带强制关闭 USD Imaging 组件与所有 Imaging 插件。

USD Imaging(PXR_BUILD_USD_IMAGING,默认ON

提供 Hydra 的 USD imaging delegates 以及独立 USD 查看器 usdview。usdview 也可单独关闭:PXR_BUILD_USDVIEW=FALSE。此外源码显示,usdview 还依赖 USD Imaging、Python 支持与 GPU 支持(GL/Metal/Vulkan 至少其一),任一不满足都会被强制关闭(cmake/defaults/Options.cmake)。

命令行工具(PXR_BUILD_USD_TOOLS,默认ON

默认构建若干用于验证与操作 USD 文件的命令行工具(如 usdcat、usdchecker 等)。关闭:

-DPXR_BUILD_USD_TOOLS=FALSE

示例与教程

  • PXR_BUILD_EXAMPLES(默认ON):构建若干演示如何开发扩展与插件的示例工程,关闭用-DPXR_BUILD_EXAMPLES=FALSE
  • PXR_BUILD_TUTORIALS(默认ON):构建 USD 教程所需的 USD 与 Python 文件,关闭用-DPXR_BUILD_TUTORIALS=FALSE

Imaging 插件:扩展 Hydra 渲染能力

以下插件默认关闭,按需开启:

插件CMake 开关额外依赖说明
PtexPXR_ENABLE_PTEX_SUPPORT=TRUEPtex 纹理支持
OpenImageIOPXR_BUILD_OPENIMAGEIO_PLUGIN=TRUE默认支持 bmp/jpg/png/tga/hdr;启用后扩展至 exr/tif/zfile/tx,支持子图像与 mipmap 等高级特性
OpenColorIOPXR_BUILD_OPENCOLORIO_PLUGIN=TRUE为 Hydra 视口提供色彩管理
Embree 渲染后端PXR_BUILD_EMBREE_PLUGIN=TRUEEMBREE_LOCATION(embree 安装根路径)基于 embree 光线追踪库的示例渲染后端
RenderMan 渲染后端PXR_BUILD_PRMAN_PLUGIN=TRUERENDERMAN_LOCATION(RenderMan 安装根路径)使用 Pixar RenderMan 作为 Hydra/usdview 渲染后端

源码中这些选项与依赖约束均已定义在 cmake/defaults/Options.cmake(如 Embree 插件要求 Imaging 与 GPU 支持同时开启,否则被强制关闭)。

第三方插件:与外部软件的集成

Alembic 与 Draco 插件默认不构建,需显式开启。Maya、Katana 的 USD 插件由 Autodesk、Foundry 各自维护的独立仓库提供,不在本仓库内。

Alembic 插件(PXR_BUILD_ALEMBIC_PLUGIN=TRUE

需额外提供:

依赖名说明
ALEMBIC_DIRAlembic 库位置
OPENEXR_LOCATIONOpenEXR 位置
Imath_DIR(不使用 OpenEXR 时)Imath SDK 的 CMake 包配置路径(OpenEXR 3+ 可显式用 Imath 代替 OpenEXR)

OpenEXR 与 Imath 二选一,取决于ALEMBIC_DIR指定的 Alembic 库所用后端。若需 HDF5 后端支持 Alembic 文件,另加:

-DPXR_ENABLE_HDF5_SUPPORT=TRUE

并提供HDF5_LOCATION(HDF5 位置)。

Draco 插件(PXR_BUILD_DRACO_PLUGIN=TRUE

需提供DRACO_ROOT(Draco SDK 安装根路径)。兼容 Draco 1.3.4(注意 VERSIONS.md 中当前测试版本为 1.5.6)。有一个重要的平台限制:Windows 上 Draco 插件无法与单体(monolithic)构建同时启用,否则会因符号缺失直接报错(cmake/defaults/Options.cmake)。

测试:构建、运行与失败诊断

测试默认构建,可通过-DPXR_BUILD_TESTS=FALSE关闭。

运行测试

在构建目录(即最初调用 cmake 的目录)中执行 ctest。运行全部测试(Release 配置、详细输出):

ctest -C Release -V

按名称正则过滤测试,例如只运行匹配testUsdShade的测试:

ctest -C Release -R testUsdShade -V

测试运行目录

每个测试都在自动创建的临时目录中运行。可用PXR_TEST_RUN_TEMP_DIR_PREFIX为这些目录名添加前缀,例如设为foo-后测试目录名为foo-<test dir>

失败测试的诊断产物

失败测试的生成文件会被显式保留,便于排查,其中<ctest_run_timestamp>格式为%Y-%m-%dT%H.%M.%S

${CMAKE_BINARY_DIR}/Testing/Failed-Diffs/<ctest_run_timestamp>/${TEST_NAME}/${filename}.result.${ext} ${CMAKE_BINARY_DIR}/Testing/Failed-Diffs/<ctest_run_timestamp>/${TEST_NAME}/${filename}.baseline.${ext}

即结果文件(.result)与基线文件(.baseline)成对存放,可直接对比差异。

其他构建选项

自定义任务管理系统(PXR_WORK_IMPL

USD 基于任务并行(task-based parallelism)提升可扩展性与性能,基础位于pxr/base/work库,默认用 Intel TBB 或 oneAPI oneTBB 实现。如需替换为自定义实现:

  1. PXR_WORK_IMPL设为提供自定义实现的 CMake 包名;
  2. 该包必须能被find_package(${PXR_WORK_IMPL} CONFIG)定位到;
  3. 包须提供名为${PXR_WORK_IMPL}::${PXR_WORK_IMPL}的库目标,含接口定义(include 目录、共享库等);
  4. 库必须实现所需函数与类,并提供一个名为impl.h的头文件,可通过#include <${PXR_WORK_IMPL}/impl.h>包含。

例如名为workExample的实现,需提供workExampleConfig.cmake,定义workExample::workExample目标,并保证impl.h能通过#include <workExample/impl.h>找到。该选项在 cmake/defaults/Options.cmake 中定义,默认为空。

插件元数据位置

每个核心库通常带有一个plugInfo.json文件,记录该库提供的 schema 类型等元数据,由 USD 内部插件系统用于按需懒加载库。构建系统会依据安装位置自动配置这些文件的位置;若要在构建后搬迁它们,需通过PXR_INSTALL_LOCATION告知最终位置(可为:分隔的路径列表)。

另一种定位插件的方式是PXR_PLUGINPATH_NAME环境变量(同样可为路径列表)。若不想使用这个默认环境变量名,可覆盖名称:

-DPXR_OVERRIDE_PLUGINPATH_NAME=CUSTOM_USD_PLUGINPATHS

之后 USD 将检查CUSTOM_USD_PLUGINPATHS而非默认的PXR_PLUGINPATH_NAME

路径值具备以下匹配特性(PXR_PLUGINPATH_NAMEPXR_INSTALL_LOCATION通用):

  • 可包含任意数量的路径;
  • /结尾的路径会自动追加plugInfo.json
  • *可匹配除斜杠外的任意字符;
  • **可匹配包括斜杠在内的任意字符;
  • 遵循 Unix$PATH式约定,重复定义时采用先找到者。

共享库前缀(PXR_LIB_PREFIX

默认共享库前缀为lib,例如 pxr/usd/usdGeom 组件对应生成libusdGeom对象(Linux 为libusdGeom.so,Windows 为libusdGeom.dll,macOS 为libusdGeom.dylib)。可通过PXR_LIB_PREFIX修改或移除前缀:

-DPXR_LIB_PREFIX=pxr

将生成pxrusdGeom.so(Linux)、pxrusdGeom.dll(Windows)、pxrusdGeom.dylib(macOS)。注意:此前缀不适用于Python 绑定使用的共享对象。

Address Sanitizer 构建

Address Sanitizer 的内存泄漏检测会触发大量本属于 Leak Sanitizer 的断言。如需不带泄漏检测的 ASan 构建,用-fsanitize=address编译并设置:

export ASAN_OPTIONS=detect_leaks=0

也可在代码中定义默认函数(参见 ASAN runtime flags 文档):

const char *__asan_default_options() { return "detect_leaks=0"; }

USD 开发者选项

C++ 命名空间配置

通过以下标志启用与定制 C++ 命名空间:

选项名说明默认值
PXR_SET_EXTERNAL_NAMESPACE外部命名空间标识符pxr
PXR_SET_INTERNAL_NAMESPACE内部命名空间标识符pxrInternal_v_x_y(对应版本 x.y.z)
PXR_ENABLE_NAMESPACES是否启用命名空间ON

启用后,生成的头文件 pxr/pxr.h.in 提供一组便于使用命名空间的宏:

宏名说明
PXR_NAMESPACE_OPEN_SCOPE打开命名空间作用域
PXR_NAMESPACE_CLOSE_SCOPE关闭命名空间
PXR_NS显式限定,如PXR_NS::TfToken foo = ...
PXR_NAMESPACE_USING_DIRECTIVE执行 using-directive,如using namespace PXR_NS;

USD Schema 生成

USD 通过称为 schema generation 的过程生成部分代码,需要以下 Python 模块安装并可在 syspath 中找到:

Python 模块名说明
Jinja2usdGenSchema 的核心代码生成器
Argparse基本命令行参数解析

优化选项:Malloc 库

经验表明 USD 在使用 Jemalloc 等分配器时性能最佳。可通过PXR_MALLOC_LIBRARY指定自定义分配器,值为分配器共享对象路径:

-DPXR_MALLOC_LIBRARY:path=/usr/local/lib/libjemalloc.so

未指定时使用默认分配器。

链接器选项:四种链接模式

USD 的链接方式由三个选项控制:

选项名默认值说明
BUILD_SHARED_LIBSON构建共享库或静态库
PXR_BUILD_MONOLITHICOFF构建单个库或多个库
PXR_MONOLITHIC_IMPORT(空)定义 usd_m 导入库的 CMake 文件

模式一:共享库(默认)

生成若干共享库,可按需只加载任务所需库:

cmake -DBUILD_SHARED_LIBS=ON ...

配置:BUILD_SHARED_LIBS=ONPXR_BUILD_MONOLITHIC=OFF

模式二:静态库

生成若干静态库,可只嵌入任务所需库;但不支持 USD 插件与 Python 模块,因为会导致符号多重定义(同一符号在主应用与每个插件/模块中各有一份实例):

cmake -DBUILD_SHARED_LIBS=OFF ...

配置:BUILD_SHARED_LIBS=OFFPXR_BUILD_MONOLITHIC=OFF

模式三:内部单体库

pxr/下所有核心库构建进单一库usd_m,静态或共享取决于BUILD_SHARED_LIBSpxr/外的插件与 Python 模块照常构建,但链接usd_m而非默认模式的各个独立库;pxr/内的插件被编译进usd_m,其plugInfo.json也指向usd_m。此模式可减少安装文件数量并简化链接:

# 单体共享库 cmake -DPXR_BUILD_MONOLITHIC=ON -DBUILD_SHARED_LIBS=ON ... # 单体静态库 cmake -DPXR_BUILD_MONOLITHIC=ON -DBUILD_SHARED_LIBS=OFF ...

命名说明:出于历史一致性,共享单体库的输出文件名为usd_ms,静态单体库为usd_m,但两种情况下 CMake 目标都叫usd_m

警告:链接静态单体库必须使用WHOLE_ARCHIVE选项(见下文),因此产物可执行文件与共享库会非常大——它们实际上引入了 USD 的每一个目标文件。

模式四:外部单体库

与内部单体类似,但由客户端负责构建单体共享库,适合将 USD 嵌入另一个共享库。构建步骤:

  1. 选定导入文件路径。该文件以add_library(usd_m SHARED IMPORTED)及若干set_property调用组成;文件不必事先存在,若存在应为空或合法 CMake 代码。
  2. PXR_BUILD_MONOLITHIC=ONPXR_MONOLITHIC_IMPORT=<第 1 步路径>常规配置构建。
  3. 正常构建,但目标改为monolithic
  4. 创建你的共享库:若用 CMake,可包含 USD 构建目录下的pxr/usd-targets-<CONFIG>文件(<CONFIG>为第 3 步的构建配置),然后链接usd_m。注意不能简单target_link_libraries(mylib PUBLIC usd_m),必须取得usd_m全部内容,见 "Linking Whole Archives"。
  5. 编辑导入文件描述你的库(构建过程可能通过export()直接生成)。文件大致如下:
add_library(usd_m SHARED IMPORTED) set_property(TARGET usd_m PROPERTY IMPORTED_LOCATION ...) # Windows 上需要以下设置 #set_property(TARGET usd_m PROPERTY IMPORTED_IMPLIB ...) set_property(TARGET usd_m PROPERTY INTERFACE_COMPILE_DEFINITIONS ...) set_property(TARGET usd_m PROPERTY INTERFACE_INCLUDE_DIRECTORIES ...) set_property(TARGET usd_m PROPERTY INTERFACE_LINK_LIBRARIES ...)
  1. 完成 USD 构建(默认目标或install目标)。

两点补充:

  1. 你的库不必命名为 usd_m,这只是导入文件给它的名称,IMPORTED_LOCATION才是真实名称与路径。
  2. USD 目前只支持你的库与 USD 其他安装文件位于同一相对位置的安装,即通过相对路径../share/usd/plugins../plugin/usd定位plugInfo.json
Linking Whole Archives(整库链接)

链接静态库时,链接器通常只拉取提供所需符号的目标文件。但 USD 有大量含静态全局对象(带副作用构造函数)的文件;若没有任何可见符号被使用,普通链接会将其排除,副作用不执行,USD 将无法工作。因此必须让链接器包含整个归档。具体链接标志因平台而异,但 CMake 3.24+ 支持平台无关的生成器表达式:

target_link_libraries(mylib "$<LINK_LIBRARY:WHOLE_ARCHIVE,usd_m>")
避免静态链接 Python

默认启用 Python 支持的构建会链接解释器的 Python 静态库,以支持从 C++ 运行 Python 代码。若不需要,可关闭:

-DPXR_PY_UNDEFINED_DYNAMIC_LOOKUP=ON

主要动机是生成 PyPI wheel 包(利用 Python 的 ABI 兼容性),该参数设计得较为通用以备他用。注意此标志在 Windows 上无效。

Spline 选项:默认抗回归创作模式

样条(关键帧动画)由pxr/base/ts库实现。Bezier 数学允许长切线形成时间上回溯的形状(非函数),通常需要在创作时阻止。各策略详见 pxr/base/ts/doxygen/regression.md。

硬编码默认模式为TsAntiRegressionKeepRatio(保持比例)。修改默认值的方式:

  • build_usd.py--build-args USD,"-DPXR_TS_DEFAULT_ANTI_REGRESSION_AUTHORING_MODE=TsAntiRegression..."
  • cmake:-DPXR_TS_DEFAULT_ANTI_REGRESSION_AUTHORING_MODE=TsAntiRegression...

客户端代码也可按需覆盖默认值。从源码看,该宏在 pxr/base/ts/CMakeLists.txt 中以编译期定义注入ts库,且在求值路径中(如 pxr/base/ts/eval.cpp)实际使用TsAntiRegressionKeepRatio作为求值时的默认行为。客户端还可通过TsAntiRegressionAuthoringSelector(pxr/base/ts/raii.h)临时切换当前创作模式。

构建问题 FAQ

Windows + Python 3.8+(非 Anaconda)

Windows 上 Python 3.8 及更高版本不再搜索 PATH 查找 DLL 依赖,客户端需调用os.add_dll_directory(p)设置搜索路径。该平台上 USD 默认遍历 PATH 并在导入 Python 模块时用os.add_dll_directory()添加所有路径。可通过环境变量PXR_USD_WINDOWS_DLL_PATH(PATH 风格字符串)覆盖,设置后 USD 将改用这些路径。

注意:以上不适用于 Anaconda 的 Python 3.8+ 解释器——它们被修改为类似 3.8 之前的行为,继续使用 PATH 查找 DLL。在 Anaconda 环境下,用户应按 Python 3.8 之前的习惯配置系统。

常见构建故障排查思路

  • 编译失败优先核对第三方依赖版本是否在 VERSIONS.md 的测试范围内(如 Linux 测试环境为 gcc 11.5.0 + CMake 3.30.4,Windows 为 Visual Studio 2022 17.14 + CMake 3.27.9)。
  • 组件间存在强制依赖关系:关闭 Imaging 会连带关闭 USD Imaging 与全部 Imaging 插件;关闭 Python 支持会连带关闭 usdview;usdview 还要求 GPU 支持开启。若配置结果与预期不符,构建日志中的STATUS信息(如Setting PXR_BUILD_USDVIEW=OFF because ...)会明确说明被强制关闭的原因。
  • Wasm 目标下 Exec 组件与共享库自动禁用;Windows 上 Draco 插件与单体构建互斥。

结语

OpenUSD 的构建体系高度模块化:build_usd.py适合快速获得完整环境,CMake 直调则赋予最大控制力。本文覆盖了从平台级构建命令、可选组件开关、渲染与第三方插件,到四种链接模式、测试诊断与 FAQ 的完整知识链。实际使用时,建议先运行python build_scripts/build_usd.py --help或对照 cmake/defaults/Options.cmake 中的默认值,再结合 VERSIONS.md 的依赖版本矩阵,即可定制出可靠、可复现的构建配置。

【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询