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 提供两条构建路径:
build_usd.py脚本:位于 build_scripts/build_usd.py,是最简单的构建方式。它会自动下载所需的第三方依赖(TBB、OpenSubdiv 等),与 USD 一起构建并安装到指定目录。适合大多数希望快速获得完整可用环境、又不愿手工管理依赖的用户。- 直接使用 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, --jobs | CPU 核数 | 并行构建任务数 |
--build | <install_dir>/build | USD 与第三方依赖的构建目录 |
--build-variant | release | 取值debug/release/relwithdebuginfo |
--build-target | 平台默认 | 交叉编译目标,如iOS、visionOS、wasm、wasm64 |
--src | <install_dir>/src | 依赖源码下载目录 |
--inst | <install_dir> | 依赖安装目录 |
--generator/--toolset | CMake 默认 | 指定 CMake 生成器与工具集 |
--build-args | 空 | 向指定库透传自定义构建参数,如--build-args USD,"-DPXR_STRICT_BUILD_MODE=ON ..." |
--cmake-build-args | 空 | 向所有使用 CMake 的构建统一透传参数(单个字符串) |
--force/--force-all | 空 | 强制重新下载并构建指定库 / 全部库 |
--compiler-cache/--no-compiler-cache | macOS/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=OFF、BUILD_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=TRUEMaterialX(PXR_ENABLE_MATERIALX_SUPPORT,CMake 默认OFF)
-DPXR_ENABLE_MATERIALX_SUPPORT=TRUE注意需要带共享库支持的 MaterialX。使用build_usd.py时默认启用,可用--materialx/--no-materialx覆盖。CMake 方式需额外提供依赖:
| 依赖名 | 说明 |
|---|---|
MaterialX_DIR | MaterialX 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 开关 | 额外依赖 | 说明 |
|---|---|---|---|
| Ptex | PXR_ENABLE_PTEX_SUPPORT=TRUE | — | Ptex 纹理支持 |
| OpenImageIO | PXR_BUILD_OPENIMAGEIO_PLUGIN=TRUE | — | 默认支持 bmp/jpg/png/tga/hdr;启用后扩展至 exr/tif/zfile/tx,支持子图像与 mipmap 等高级特性 |
| OpenColorIO | PXR_BUILD_OPENCOLORIO_PLUGIN=TRUE | — | 为 Hydra 视口提供色彩管理 |
| Embree 渲染后端 | PXR_BUILD_EMBREE_PLUGIN=TRUE | EMBREE_LOCATION(embree 安装根路径) | 基于 embree 光线追踪库的示例渲染后端 |
| RenderMan 渲染后端 | PXR_BUILD_PRMAN_PLUGIN=TRUE | RENDERMAN_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_DIR | Alembic 库位置 |
OPENEXR_LOCATION | OpenEXR 位置 |
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 实现。如需替换为自定义实现:
- 将
PXR_WORK_IMPL设为提供自定义实现的 CMake 包名; - 该包必须能被
find_package(${PXR_WORK_IMPL} CONFIG)定位到; - 包须提供名为
${PXR_WORK_IMPL}::${PXR_WORK_IMPL}的库目标,含接口定义(include 目录、共享库等); - 库必须实现所需函数与类,并提供一个名为
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_NAME与PXR_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 模块名 | 说明 |
|---|---|
| Jinja2 | usdGenSchema 的核心代码生成器 |
| Argparse | 基本命令行参数解析 |
优化选项:Malloc 库
经验表明 USD 在使用 Jemalloc 等分配器时性能最佳。可通过PXR_MALLOC_LIBRARY指定自定义分配器,值为分配器共享对象路径:
-DPXR_MALLOC_LIBRARY:path=/usr/local/lib/libjemalloc.so未指定时使用默认分配器。
链接器选项:四种链接模式
USD 的链接方式由三个选项控制:
| 选项名 | 默认值 | 说明 |
|---|---|---|
BUILD_SHARED_LIBS | ON | 构建共享库或静态库 |
PXR_BUILD_MONOLITHIC | OFF | 构建单个库或多个库 |
PXR_MONOLITHIC_IMPORT | (空) | 定义 usd_m 导入库的 CMake 文件 |
模式一:共享库(默认)
生成若干共享库,可按需只加载任务所需库:
cmake -DBUILD_SHARED_LIBS=ON ...配置:BUILD_SHARED_LIBS=ON、PXR_BUILD_MONOLITHIC=OFF。
模式二:静态库
生成若干静态库,可只嵌入任务所需库;但不支持 USD 插件与 Python 模块,因为会导致符号多重定义(同一符号在主应用与每个插件/模块中各有一份实例):
cmake -DBUILD_SHARED_LIBS=OFF ...配置:BUILD_SHARED_LIBS=OFF、PXR_BUILD_MONOLITHIC=OFF。
模式三:内部单体库
将pxr/下所有核心库构建进单一库usd_m,静态或共享取决于BUILD_SHARED_LIBS。pxr/外的插件与 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 嵌入另一个共享库。构建步骤:
- 选定导入文件路径。该文件以
add_library(usd_m SHARED IMPORTED)及若干set_property调用组成;文件不必事先存在,若存在应为空或合法 CMake 代码。 - 以
PXR_BUILD_MONOLITHIC=ON与PXR_MONOLITHIC_IMPORT=<第 1 步路径>常规配置构建。 - 正常构建,但目标改为
monolithic。 - 创建你的共享库:若用 CMake,可包含 USD 构建目录下的
pxr/usd-targets-<CONFIG>文件(<CONFIG>为第 3 步的构建配置),然后链接usd_m。注意不能简单target_link_libraries(mylib PUBLIC usd_m),必须取得usd_m的全部内容,见 "Linking Whole Archives"。 - 编辑导入文件描述你的库(构建过程可能通过
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 ...)- 完成 USD 构建(默认目标或
install目标)。
两点补充:
- 你的库不必命名为 usd_m,这只是导入文件给它的名称,
IMPORTED_LOCATION才是真实名称与路径。 - 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),仅供参考