原文开发者资源本文档旨在通过推荐的工作流和高级工作流指导用户构建和使用 Holoscan SDK。这通常不是使用该 SDK 最简单的方式因此在开始之前请务必先阅读项目 README。[!WARNING]免责声明我们仅建议以下人员从源码构建 SDKSDK 的开发者或需要使用调试符号或其他未包含在已发布软件包中的选项来构建 SDK 的人员。如果你想编写自己的算子operator或应用程序可以将 SDK 作为依赖项使用并向 HoloHub 贡献代码。如果你需要对 SDK 进行其他修改请提交功能或缺陷请求。有关从已发布软件包安装 Holoscan SDK 的指导请参阅 Holoscan SDK 用户指南安装说明。目录从源码构建 SDK前提条件推荐使用run脚本交叉编译高级Docker CMake高级本地环境 CMake构建变体与配置实用工具测试测试类型与类别测试执行方式测试环境测试配置复现测试失败代码检查LintingPre-commit 钩子构建用户指南VSCode从源码构建 SDK前提条件各受支持平台的前提条件记录在用户指南中。要在容器化环境中构建和运行 SDK推荐你需要NVIDIA Container Toolkit v1.12.2 或更高版本Docker包括 buildx 插件docker-buildx-plugin推荐使用run脚本在仓库中执行./run build来构建构建容器和 CMake 项目。如果在 CMake 构建过程中遇到错误可以执行./run clear_cache删除缓存/构建/安装文件夹执行./run build --help获取更多信息执行./run build --dryrun查看将要执行的命令该命令也可以拆分为更细粒度的命令./run check_system_deps# 确保系统已正确配置以进行构建./run build_image# 创建构建用 Docker 容器./run build# 运行 CMake 配置、构建和安装步骤执行./run launch命令启动并进入构建容器。你可以通过将工作目录作为参数传入从install或build目录树中运行例如./run launch install执行./run launch --help获取更多信息执行./run launch --dryrun查看将要执行的命令执行./run launch --run-cmd ...直接在容器中执行 bash 命令在容器内运行示例运行各目录 README 文件中列出的相应命令即可。交叉编译虽然用于构建 SDK 的 Dockerfile 目前不支持真正的交叉编译但你可以在 x86_64 主机上使用模拟环境为开发者套件arm64编译 Holoscan SDK。安装 qemu清除构建缓存./run clear_cache使用--arch|-a或HOLOSCAN_BUILD_ARCH为linux/arm64重新构建./run build --arch arm64HOLOSCAN_BUILD_ARCHarm64 ./run build然后你可以将 CMake 生成的install文件夹复制到已配置好环境的开发者套件中或复制到容器内用于运行和开发应用程序。高级Docker CMake上文提到的run脚本有助于理解 Docker 和 CMake 是如何配置和运行的因为在运行该脚本或使用--dryrun时会打印出相关命令。如果你想手动使用 Docker 和 CMake我们建议查看这些命令并阅读脚本内的注释以了解每个参数的详细信息特别是build()和launch()方法。高级本地环境 CMake[!WARNING]免责声明这种构建 SDK 的方式未经过积极测试或维护。以下说明可能会过时。软件要求要在本地环境中构建 Holoscan SDK请参阅顶层 Dockerfile 中安装的依赖项列表。为了让 CMake 找到这些依赖项请将它们安装到默认系统路径或在配置时传入CMAKE_PREFIX_PATH、CMAKE_LIBRARY_PATH和/或CMAKE_INCLUDE_PATH。构建示例# 配置cmake-S$source_dir-B$build_dir\-GNinja\-DCMAKE_BUILD_TYPERelease\-DCUDAToolkit_ROOT:PATH/usr/local/cuda# 构建cmake--build$build_dir-j# 安装cmake--install$build_dir--prefix$install_dir之后运行示例的命令与在 Docker 化环境中相同可以在各自的源码目录 README 中找到。构建变体与配置SDK 可以通过不同的配置进行构建以匹配各种部署目标CUDA 版本12、13示例中默认exportCUDA_MAJOR13# 或 12./run build架构x86_64默认、aarch64./run build--archaarch64# 或exportHOLOSCAN_BUILD_ARCHaarch64 ./run buildGPU 类型dgpu默认、igpu仅 aarch64./run build--gpuigpu# 仅适用于 aarch64# 或exportHOLOSCAN_BUILD_GPU_TYPEigpu ./run build构建类型Release默认、Debug、RelWithDebInfo./run build--typedebug# 或exportCMAKE_BUILD_TYPEDebug ./run build构建目录遵循以下模式build-cu版本-架构[-GPU]安装目录遵循以下模式install-cu版本-架构[-GPU]实用工具一些实用工具位于scripts文件夹中其他与构建过程关系更密切的工具列于下文测试现有测试中C 使用 GTestPython 使用 pytest分别位于 tests 和 python/tests 目录下。Holoscan SDK 使用 CTest 作为构建和执行这些测试的框架。测试类型与类别SDK 包含以下几类测试核心 HSDK 测试针对 SDK 核心功能的单元测试、集成测试和系统测试位于tests/目录C 测试使用 GTestPython 测试使用 pytest示例测试验证 SDK 示例能否正确构建和运行测试来自安装目录树的示例确保示例能与已安装的 SDK 协同工作测试执行方式你可以使用./run脚本运行测试# 运行所有测试./runtest# 按名称运行特定测试支持正则表达式./runtest--name测试名称# 以详细输出模式运行./runtest--verbose# 带附加 CTest 选项运行./runtest--options-R 测试正则表达式 --output-on-failure[!TIP]运行run test --help查看更多选项。测试环境使用./run test命令时测试在容器内运行这确保了无论宿主系统如何环境都保持一致通过 NVIDIA Container Toolkit 访问 GPU与宿主系统依赖项隔离./run脚本会自动管理容器环境。对于高级场景测试也可以直接在宿主系统上容器外运行但这需要手动设置和配置。测试配置测试配置通过以下方式控制环境变量HOLOSCAN_INPUT_PATH测试数据路径HOLOSCAN_TESTS_DATA_PATH测试专用数据路径PYTHONPATHPython 模块搜索路径测试数据所需的测试数据应位于data/和tests/data/目录中复现测试失败当测试失败时尤其是在 CI 中你可以在本地复现确定测试从 CI 日志或 CDash 中记下确切的测试名称匹配构建配置exportCUDA_MAJOR13# 或 12与 CI 匹配exportARCHx86_64# 或 aarch64与 CI 匹配exportGPUdgpu# 或 igpu与 CI 匹配运行特定测试# 使用 run 脚本./runtest--name测试名称--verbose# 或带附加 CTest 选项./runtest--options-R 测试名称 --verbose --output-on-failure在交互式容器中调试从构建目录树./run launch build-cu13-x86_64# 在容器内cdbuild-cu13-x86_64 ctest-R测试名称--verbose--output-on-failure注意容器由./run脚本自动管理。从安装目录树运行测试用于示例# 启动挂载了安装目录树的容器./run launch install-cu13-x86_64# 在容器内# 方式 1使用 run_example_tests 脚本构建并测试所有示例/workspace/holoscan-sdk/install-cu13-x86_64/examples/testing/run_example_tests# 方式 2手动构建并测试示例cd/workspace/holoscan-sdk/install-cu13-x86_64/examples cmake-S.-B../examples-build cmake--build../examples-build-jctest --test-dir../examples-build-R测试名称--verbose# 方式 3从示例所在目录测试特定示例cd/workspace/holoscan-sdk/install-cu13-x86_64/examples/示例名称/cpp# 或 python# 构建并运行该示例的测试检查测试产物对于可视化测试例如 Holoviz请检查*_fail.png失败的实际输出*_ref.png预期的参考图像代码检查Linting代码检查通过pre-commit实现。各钩子Ruff、cpplint、cmakelint、codespell、copyright、clang-format、markdownlint 以及标准文件检查列在git 仓库根目录的.pre-commit-config.yaml中pre-commit 会在首次运行时下载并缓存各钩子所需的工具。在构建容器或任何运行./run的环境中使用./run lint# 从仓库根目录运行 pre-commit run --all-files./run lint会自动解析pre-commit优先使用uvx如可用它在隔离环境中运行不会污染你的 Python 安装其次回退到 PATH 上已有的pre-commit最后才会通过 pip 安装。然后它会解析 git 顶层目录检查该处的.pre-commit-config.yaml并对每个被跟踪的文件运行所有钩子。这与完整的 CI 式检查过程一致。若想在提交时更快地对暂存文件进行检查请使用pre-commit install安装钩子并直接执行git commit或从仓库根目录运行pre-commit run参见 Pre-commit 钩子。[!TIP]有关特定钩子的选项和过滤请参阅pre-commit run --help和 .pre-commit-config.yaml。Pre-commit 钩子贡献者应启用pre-commit以便在git commit时自动运行检查。请使用git 仓库根目录即包含.pre-commit-config.yaml的目录。设置在宿主机上或你执行提交的 shell 中——不只是在 Docker 内部# 方式 A使用 uvx推荐——隔离运行不污染 pip# 如需要请先安装 uvhttps://docs.astral.sh/uv/getting-started/installation/uvx pre-commitinstall# 方式 B使用 pippython3-mpipinstallpre-commit pre-commitinstall手动运行对整棵树运行时与./run lint相同# 方式 A使用 uvxuvx pre-commit run --all-files# 方式 B使用 pip 安装的 pre-commitpre-commit run --all-files按 id 运行单个钩子参见配置文件例如pre-commit run ruff-check --all-files pre-commit run clang-format --all-files各钩子涵盖的范围领域钩子 / 说明仓库整洁trailing-whitespace、end-of-file-fixer、check-yaml、check-json、check-added-large-files标准 pre-commit-hooksNVIDIA SPDX 头部check-copyright—— 运行scripts/check_copyright.py空白字符remove-tabs—— 在 C、CMake、Dockerfile、Markdown、Python 和 shell 源码中将制表符替换为空格第三方目录树在配置中已排除Pythonruff-check带--fix和ruff-format—— 规则见.ruff.toml拼写codespell—— 可能会改写文件--write-changes设置见.codespell.toml[tool.codespell]可以使用// codespell-ignore或# codespell-ignore忽略某行C/C/CUDA 风格cpplint和clang-formatclang-format 版本在镜像仓库中固定该钩子要求相应二进制文件可用CMakecmakelintMarkdownmarkdownlint—— 路径和配置文件在.pre-commit-config.yaml中设置与本目录树中的.markdownlint.yaml配套check-copyright由scripts/check_copyright.py实现。在git commit时pre-commit 仅传递已暂存的路径。对于pre-commit run --all-files脚本会接收一个大范围文件列表并将其与自默认基线origin/main/main或origin/release/latest/release/latest根据你当前的分支选择以来的变更取交集。设置HOLOSCAN_COPYRIGHT_BASE_REF或向该脚本传入--intersect-since-ref REF以固定基线。运行python3 scripts/check_copyright.py --help查看所有选项。与./run lint的关系两者从同一配置运行相同的钩子。./run lint始终在 git 根目录执行pre-commit run --all-files整个目录树。执行pre-commit install之后git commit只对已暂存的文件运行钩子。部分钩子会自动修复例如 Ruff 和 codespell在对整棵树运行后请检查git diff。构建用户指南托管在 https://docs.nvidia.com/holoscan/sdk-user-guide 的用户指南源码位于 docs 目录。在holoscan-sdk 仓库根目录下使用 Fern 构建并验证python3 public/docs/scripts/build_holoscan_docs.py python3 public/docs/scripts/build_holoscan_docs.py--preview有关撰写和发布的详细信息请参阅 docs/README.md。VSCode可以使用 Visual Studio Code或 Cursor开发 Holoscan SDK。.devcontainer文件夹保存了用于搭建开发容器的配置其中已安装所有必要的工具和库。./run脚本包含vscode和vscode_remote命令分别用于在容器中启动 Visual Studio Code 或 Cursor或从远程机器启动。要在开发容器中启动 IDE请使用./run vscode可以使用-j 工作线程数或--parallel 工作线程数指定构建过程中并行任务的数量。该命令会自动检测并启动 Cursor如果可用否则默认使用 VSCode。更多信息请参阅./run vscode -h的说明。要从远程机器附加到已有的开发容器请使用./run vscode_remote。更多信息请参阅./run vscode_remote -h的说明。IDE 启动后开发容器将被构建推荐的扩展将自动安装同时 CMake 也会完成配置。IDE 选择选项./run vscode命令支持多种 IDE 选项自动检测如果 Cursor 可用则启动 Cursor否则使用 VSCode手动选择使用--ide IDE 名称指定 IDEvscode、vscode-insiders、cursor快捷选项使用--code或--cursor直接选择 IDE自定义二进制文件使用--cmd 路径指定自定义 IDE 二进制文件示例./run vscode# 自动检测如有 Cursor 则用 Cursor否则用 VSCode./run vscode--code# 强制使用 VSCode./run vscode--cursor# 强制使用 Cursor./run vscode--idecursor# 明确指定 Cursor./run vscode--cursor--cmd/path/to/cursor_binary# 使用自定义 Cursor 二进制文件在开发容器中配置 CMake如需手动配置 CMake请打开命令面板Ctrl Shift P并运行CMake: Configure命令。在开发容器中构建源代码在开发容器中构建源代码可以按Ctrl Shift B或从命令面板Ctrl Shift P执行Tasks: Run Build Task。在开发容器中调试源代码要在开发容器中调试源代码请打开运行和调试视图Ctrl Shift D从下拉列表中选择一个调试配置然后按F5开始调试。