SMLib 安装与构建指南：wheel、源码构建、三平台差异与 6 个实测坑

前 10 篇讲的是 SMLib 的架构、API、修复和 Agent 用法。但第一步永远是"先装起来" ------而这一步劝退了不少人：文档写着 pip install usd-brep，实际却要面对 Python 版本卡 3.12、Windows 缺 MSVC v142、macOS 装了发现没有 usd_brep 等一连串问题。

这篇把三条安装路线、wheel 里到底装了什么、三平台构建差异，以及我实际踩到的 6 个坑一次讲清，最后给一份 20 行自检脚本。

一、先选路：三条安装路线

路线	适用场景	代价	能力完整度
PyPI wheel （pip install usd-brep）	只想用 Python API 建模/转 USD	1 分钟，但 Python 必须 3.12	⭐⭐⭐⭐ 有 usd_brep、brep_validator，无 _smlib_dev
源码构建 （prebuild + repo.sh build）	要 C++ 内核、改内核、跑全套测试	10--40 分钟 + 数 GB 磁盘 + 工具链	⭐⭐⭐⭐⭐ 全部（含 _smlib_dev.assert_valid）
Packman 布局	接 Omniverse Kit / 已有 Packman 依赖树	依赖 Packman 生态	⭐⭐⭐⭐⭐ 与源码构建等价，布局不同

一句话建议：只想用就 wheel，要调内核或跑测试就源码，进 Omniverse 生态走 Packman。 下面按这个顺序讲。

二、PyPI wheel：平台矩阵与版本约束

从 PyPI 拉到的 usd-brep 发布记录（实测）：

版本	平台标签	体积	上传日期
1.0.0	manylinux_2_34_x86_64	90.2 MB	2026-10-09
1.0.0	manylinux_2_34_aarch64	87.6 MB	2026-10-09
1.0.0	win_amd64	17.6 MB	2026-10-09
1.0.1	manylinux_2_34_x86_64	91.2 MB	2026-10-22
1.0.1	manylinux_2_34_aarch64	88.8 MB	2026-10-22
1.0.1	win_amd64	17.6 MB	2026-10-22

三个立刻要注意的点：

1. 没有 macOS wheel 。macOS 用户只能源码构建，而且默认构建不含 usd_brep（见第五节）。
2. Python 版本被焊死 ：Requires-Python: >=3.12,<3.13。3.11 装不上，3.13 也装不上。用 conda/uv 单独开个 3.12 环境是最省事的做法。
3. Linux 91MB vs Windows 17.6MB 的差距不是压缩率，而是内容不同：Linux wheel 把 Python 运行时相关的库也打进去了，Windows 则复用宿主 Python 的 CRT。下一节有实测清单。

# 推荐的隔离安装（uv 比 pip 快很多）
uv venv --python 3.12 .venv-smlib
source .venv-smlib/bin/activate      # Windows: .venv-smlib\Scripts\activate
pip install usd-brep==1.0.1
# 需要 USD 校验工具链（会拉 usd-validation-nvidia）
pip install "usd-brep[validation]==1.0.1"

三、wheel 里到底装了什么（实测解包）

把 usd_brep-1.0.1-cp312-cp312-win_amd64.whl 解开，共 206 个文件，结构如下：

内核与绑定（这是 SMLib 本体）

文件	体积	作用
SMLib.dll	11.86 MB	BRep 内核（几何/拓扑/布尔）
_omni_solid.pyd	2.78 MB	Python 绑定，import usd_brep 最终加载它
SM_API.dll	1.94 MB	对外 C API
BREP_SM_USD.dll	1.94 MB	BREP ↔ USD 桥接
SM_API_USD.dll	1.77 MB	USD 侧的 API 包装
BREP_USD_DATA.dll	0.29 MB	USD 数据结构

自带的 OpenUSD 运行时（不需要你另装 usd-core 就能读写 USD）

usd_sdf.dll 6.15MB、usd_usd.dll 3.78MB、usd_vt 2.02MB、usd_pcp 1.47MB、usd_usdGeom 1.19MB、usd_tf 0.86MB、usd_usdUtils 0.71MB、usd_usdShade 0.57MB，加上 usd_ts / usd_trace / usd_sdr / usd_plug / usd_arch / usd_ar / usd_python / usd_js / usd_kind / usd_work 等------19 个 USD 核心库。

并行运行时 ：tbb12.dll 322KB、tbbbind_2_5.dll 256KB、tbbmalloc.dll 114KB。

Schema 与着色资源 ：50 个 .glslfx、46 个 .json、34 个 .usda（omniSolid schema 插件与渲染描述）。

Python 侧 ：brep_validator/ 包（brep_validator.py 402 KB、validate.py 10.5 KB）、__init__.pyi 33 KB 类型存根、usd.pyi、py.typed（支持 mypy/pyright 类型检查）。

结论：这个 wheel 是"自包含"的------内核、OpenUSD 运行时、TBB、schema 资源一次给全。这也是 Linux 版接近 90MB 的原因。

四、pip 装完的 10 行验证

import math
import usd_brep as sm                    # 入口：_omni_solid 的封装

box  = sm.create_box((-5, -5, 0), 10, 10, 3)      # 角点 + 长宽高
ball = sm.create_sphere((0, 0, 5), 2.0)
part = sm.boolean_difference(box, ball)           # 布尔差，挖球坑

print("体积:", sm.compute_volume(part))            # 约 300 - 半.. 具体见输出
mesh = sm.tessellate(part, chord_height=0.1, angle=math.radians(15))
print("三角面片数:", len(mesh))                    # 能出数就说明几何+镶嵌都正常

三项全能过，说明内核、布尔、镶嵌都工作正常。若只想过一遍 USD：

import usd_brep.usd as usd
stage = usd.open_stage("/path/to/model.usd")        # 读
usd.heal_file("in.usd", "out.usd")                  # 修复后另存

五、源码构建：prebuild 不能跳

源码构建的正确顺序只有三步，但第一步最容易被忽略：

# Linux
./prebuild.sh
./repo.sh build
./tests.sh linux-x86_64

# macOS（仅 Apple Silicon）
./prebuild.sh -p macos-universal
./repo.sh build -p macos-universal
./tests.sh macos-universal

# Windows
prebuild.bat
repo.bat build
tests.bat

为什么 prebuild 必须跑？ 官方 BUILDING.md 写得很直接：它把 omniSolid schema 插件 布置到 _build/schema/omniSolid/resources，USD 工具在运行时要从这里加载 schema；repo build 单独跑不会创建这个目录。跳过它的典型症状是：编译全绿，但一读带 BRep 的 USD 文件就报 schema 未注册。

源码构建还多给一个 wheel 里没有的模块：_smlib_dev （开发者模块，官方明示"不在 PyPI 包里"），它提供 assert_valid，可以直接跑内核自己的几何一致性检查：

import usd_brep, _smlib_dev
_smlib_dev.assert_valid(brep)      # debug / release 构建都可用

这在排查"布尔结果看起来对但下游报错"时非常有用。

六、三平台差异（每平台都有专属陷阱）

维度	Linux	Windows	macOS
前置依赖	sudo apt-get install build-essential	VS 2019 或 2022 + MSVC v142 + Windows SDK + VC++ Redist	Xcode 命令行工具
依赖从哪来	Packman 自动拉 OpenUSD / Python 3.12 / pybind11 / premake	同 Linux（编译器用宿主装的，不是 Packman 的 msvc）	部分拉不到，需手动补
Python 入口	usd_brep 全功能	usd_brep 全功能（有 DLL 坑，见 7.2）	默认构建没有 usd_brep
平台参数	linux-x86_64 / linux-aarch64	无（默认 win64）	macos-universal（仅 Apple Silicon）
架构	x86_64 与 aarch64 均可	x64	仅 arm64

Windows 三个硬约束（官方明确写了，踩了就编译失败）：

1. msbuild.vs_version 被固定为 vs2019 ，所以装 VS 2022 的人必须补装 MSVC v142 生成工具；
2. 构建用的是宿主安装的编译器 （repo.toml 里 msbuild.link_host_toolchain），Packman 不会帮你装 msvc；
3. 只看 "Desktop development with C++" 装了但不含 C++ 工具集，等于没装。

macOS 的"半个内核"陷阱 ：默认构建（不接 OpenUSD）只产出内核、C++ 测试，以及 _smlib_tests / _smlib_dev 两个 Python 模块；USD 支持、OCCT 转换器、usd_brep Python API（也就是 _omni_solid）都不会构建。想要完整功能必须自己先准备一个 Python 3.12 的 OpenUSD：

export SMLIB_USD_ROOT=~/opt/usd-25.11-py312
./tools/scripts/setup-macos-local-deps.sh
./repo.sh build -p macos-universal -j10

另外 macOS 上 Packman 的 premake 包不在公共服务器 ，得通过用户级 Packman 配置注入；清理构建也不要用 ./repo.sh build -x ，直接删 _build、_compiler、_repo 三个目录。

七、6 个实测坑

7.1 跳过 prebuild → schema 找不到

编译不报错，运行时报 schema 未注册或 BRep 相关类型解析失败。删了 _build 之后必须重跑 prebuild，这是最常见的自伤。

7.2 Windows 上 usd_brep 和 PyPI usd-core 不能同一个进程

装了 usd-brep[validation] 后，validation extra 会拉 PyPI usd-core 26.8 。而 wheel 自带 OpenUSD 25.11 的 usdVol 插件------两者对 UsdVolFieldAsset 的基类定义不同，同一进程里先 import usd_brep 再开 stage，会抛：

pxr.Tf.ErrorException  ← PlugPlugin::_DeclareType

Linux 上两者可以共存，Windows 不行 （官方 KNOWN_ISSUES 记录，对应 GitHub #15）。规避方式：把 usd_brep 的代码和 pxr 的代码拆到两个进程 跑，或者干脆别装 [validation] extra，用 wheel 自带能力。

7.3 Windows 的 DLL 搜索路径不能靠 PATH

usd_brep/__init__.py 里明确写了：Windows 上通过 os.add_dll_directory 追加目录，注释是 ------ "Not PATH: that loads whichever OpenUSD is installed system-wide"（不用 PATH，否则会加载系统里任意一个 OpenUSD）。它按三种布局找 DLL：

wheel 布局：  <site-packages>/usd_brep/
packman 布局：lib/ 与 omniSolid/ 在 python/ 旁边，OpenUSD 在 extraLibs/
其他布局：    回退到 pxr 自己的位置，或读 PXR_USD_WINDOWS_DLL_PATH

所以不要手工把 SMLib 的 dll 目录塞进 PATH，否则可能和别的 OpenUSD 撞车。

7.4 Windows 长路径 \\?\ 让插件路径失效

同文件里还有一条注释值得记住：Windows 可能把 wheel 路径报成 \\?\C:\...，而 OpenUSD 的 Windows glob 会把 ? 当通配符，导致一个 usd/*/resources/ 都匹配不到 。官方做法是直接把 usd 目录写进 PXR_PLUGINPATH_NAME：

# __init__.py 内部逻辑（不需要你改，但排查时要知道）
os.environ["PXR_PLUGINPATH_NAME"] = str(site_packages / "usd_brep" / "usd")

另外 schema 路径通过 OMNISOLID_PLUGIN_PATH 传递，且必须在打开 stage 之前完成注册（OpenUSD 规则：stage 打开后再注册插件无效）。

7.5 release 包里的 validator 脚本期望你有一份源码树

brep_validator_cli/validate_usd.sh 会去找 _build/ 和 tools/packman/。直接跑 release 包会：

• validate_usd.sh → 退出码 127
• validate_directory.sh → 退出码 1，且没有任何输出（最难查的一种）

替代方案（官方给的）：

# 方式一：直接用 python 脚本
python brep_validator_cli/validate_usd.py model.usd

# 方式二：安装 validation extra 后用命令
pip install "usd-brep[validation]"
nvidia_usd_validate model.usd

7.6 下载环节：Packman / git 都可能卡

实测（国内网络）：

• git clone GitHub 直连容易中断 → 用 release tarball 或镜像拉，本次拿到的是约 15 MB 的源码包；
• Packman 下载依赖会并发拉很多包，网差时容易超时。若用 uv 引导环境，把超时和并发调小更稳：

export UV_HTTP_TIMEOUT=180
export UV_CONCURRENT_DOWNLOADS=4

八、一份 20 行自检脚本

装完先跑这个，比逐个试错快：

import sys, os, importlib.util, pathlib

print("Python:", sys.version.split()[0])
assert sys.version_info[:2] == (3, 12), "SMLib wheel 要求 Python 3.12（>=3.12,<3.13）"

import usd_brep as sm
print("usd_brep:", pathlib.Path(sm.__file__).parent)

# schema 插件路径（空值 = prebuild 没跑或 wheel 不完整）
print("OMNISOLID_PLUGIN_PATH:", os.environ.get("OMNISOLID_PLUGIN_PATH", "(未设置)"))

# 内核是否真的能算
box = sm.create_box((0, 0, 0), 10, 10, 10)
print("体积:", round(sm.compute_volume(box), 3))       # 期望 1000.0
print("面片数:", len(sm.tessellate(box, chord_height=0.5)))

# 源码构建额外模块（wheel 里没有，报 ImportError 属正常）
dev = importlib.util.find_spec("_smlib_dev")
print("_smlib_dev:", "可用" if dev else "不存在（wheel 安装的正常现象）")

期望输出形如：

Python: 3.12.x
usd_brep: /.../site-packages/usd_brep
OMNISOLID_PLUGIN_PATH: /.../usd_brep/omniSolid/resources
体积: 1000.0
面片数: 12
_smlib_dev: 不存在（wheel 安装的正常现象）

九、小结

你的情况	建议
只想写 Python 建模、导出 USD	pip install usd-brep，Python 锁 3.12，别装 [validation] 或注意进程隔离
要跑官方测试 / 改内核 / 用 assert_valid	源码构建，记住 prebuild 必跑
在 Windows 上编译	VS 装 C++ 工作负载 + MSVC v142 ，路径别带括号、别放 Program Files (x86)（这是 1.0.1 才修的）
在 macOS 上要 usd_brep	必须先准备 Python 3.12 的 OpenUSD（SMLIB_USD_ROOT + setup-macos-local-deps.sh）
在 Omniverse Kit 里用	走 Packman 布局，注意 extraLibs/ 与 DLL 搜索顺序

下一篇会讲 1.0.1 相比 1.0.0 到底改了什么------6 条会影响你代码的行为变更，和 59 项修复里最该关心的几个。

仓库：https://github.com/NVIDIA-Omniverse/usd-brep（Apache 2.0，C++ / Python 3.12）

---

系列文章

SMLib 系列共 12 篇，本篇为第 11 篇，可互相跳转：

• 第 1 篇：《NVIDIA 开源 CAD 内核 SMLib：USD BRep 里有什么、能怎么用》
• 第 2 篇：《Agent 如何用 SMLib 做 CAD 创作：从 AGENTS.md 到 text-to-3D 流水线》
• 第 3 篇：《SMLib 五层架构深度解析》
• 第 4 篇：《SMLib Python API 实战：用 _omni_solid 建模的 10 个常用操作》
• 第 5 篇：《SMLib vs OpenCASCADE：2026 开源 CAD 内核怎么选？》
• 第 6 篇：《SMLib 的 usd.heal_file：STEP/IGES 导入模型修复实战》
• 第 7 篇：《SMLib 镶嵌（Tessellation）参数调优：chord-height 与角度容差怎么选》
• 第 8 篇：《用 SMLib + Claude Code 做一个 CAD 资产生成 Agent（实战）》
• 第 9 篇：《SMLib 的 20 个 Agent 技能详解：skill 化封装怎么做》
• 第 10 篇：《SMLib 的 Examples 导读：PyAPI / SM_API / SMLib 三组示例怎么读》
• 第 11 篇（本文）：《SMLib 安装与构建指南：wheel、源码构建、三平台差异与 6 个实测坑》
• 第 12 篇：《SMLib 1.0.1 升级指南：6 条行为变更与 59 项修复（附迁移检查表）》
• 第 11 篇（本文）：《SMLib 安装与构建指南：wheel、源码构建、三平台差异与 6 个实测坑》
• 第 12 篇：《SMLib 1.0.1 升级指南：6 条行为变更与 59 项修复（附迁移检查表）》

仓库：https://github.com/NVIDIA-Omniverse/usd-brep（Apache 2.0，C++ / Python）