原文

开发者资源

本文档旨在通过推荐的工作流和高级工作流，指导用户构建和使用 Holoscan SDK。这通常不是使用该 SDK 最简单的方式，因此在开始之前，请务必先阅读项目 README。

[!WARNING]
免责声明：我们仅建议以下人员从源码构建 SDK：SDK 的开发者，或需要使用调试符号或其他未包含在已发布软件包中的选项来构建 SDK 的人员。

• 如果你想编写自己的算子（operator）或应用程序，可以将 SDK 作为依赖项使用（并向 HoloHub 贡献代码）。
• 如果你需要对 SDK 进行其他修改，请提交功能或缺陷请求。
• 有关从已发布软件包安装 Holoscan SDK 的指导，请参阅 Holoscan SDK 用户指南安装说明。

目录

• 从源码构建 SDK
  • 前提条件
  • （推荐）使用run脚本
  • 交叉编译
  • （高级）Docker + CMake
  • （高级）本地环境 + CMake
  • 构建变体与配置
• 实用工具
  • 测试
    • 测试类型与类别
    • 测试执行方式
    • 测试环境
    • 测试配置
    • 复现测试失败
  • 代码检查（Linting）
  • Pre-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。

1. 安装 qemu
2. 清除构建缓存：./run clear_cache
3. 使用--arch|-a或HOLOSCAN_BUILD_ARCH为linux/arm64重新构建：
   • ./run build --arch arm64
   • HOLOSCAN_BUILD_ARCH=arm64 ./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_TYPE=Release\-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_MAJOR=13# 或 12./run build

架构：x86_64（默认）、aarch64

./run build--archaarch64# 或exportHOLOSCAN_BUILD_ARCH=aarch64 ./run build

GPU 类型：dgpu（默认）、igpu（仅 aarch64）

./run build--gpuigpu# 仅适用于 aarch64# 或exportHOLOSCAN_BUILD_GPU_TYPE=igpu ./run build

构建类型：Release（默认）、Debug、RelWithDebInfo

./run build--typedebug# 或exportCMAKE_BUILD_TYPE=Debug ./run build

构建目录遵循以下模式：build-cu<版本>-<架构>[-<GPU>]
安装目录遵循以下模式：install-cu<版本>-<架构>[-<GPU>]

实用工具

一些实用工具位于scripts文件夹中，其他与构建过程关系更密切的工具列于下文：

测试

现有测试中，C++ 使用 GTest，Python 使用 pytest，分别位于 tests 和 python/tests 目录下。Holoscan SDK 使用 CTest 作为构建和执行这些测试的框架。

测试类型与类别

SDK 包含以下几类测试：

1. 核心 HSDK 测试：针对 SDK 核心功能的单元测试、集成测试和系统测试

   • 位于tests/目录
   • C++ 测试使用 GTest
   • Python 测试使用 pytest

2. 示例测试：验证 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：测试专用数据路径
  • PYTHONPATH：Python 模块搜索路径
• 测试数据：所需的测试数据应位于data/和tests/data/目录中

复现测试失败

当测试失败时（尤其是在 CI 中），你可以在本地复现：

1. 确定测试：从 CI 日志或 CDash 中，记下确切的测试名称

2. 匹配构建配置：

   exportCUDA_MAJOR=13# 或 12，与 CI 匹配exportARCH=x86_64# 或 aarch64，与 CI 匹配exportGPU=dgpu# 或 igpu，与 CI 匹配

3. 运行特定测试：

   # 使用 run 脚本./runtest--name<测试名称>--verbose# 或带附加 CTest 选项./runtest--options"-R <测试名称> --verbose --output-on-failure"

4. 在交互式容器中调试（从构建目录树）：

   ./run launch build-cu13-x86_64# 在容器内：cdbuild-cu13-x86_64 ctest-R<测试名称>--verbose--output-on-failure

   注意：容器由./run脚本自动管理。

5. 从安装目录树运行测试（用于示例）：

   # 启动挂载了安装目录树的容器./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# 构建并运行该示例的测试

6. 检查测试产物：对于可视化测试（例如 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）# 如需要，请先安装 uv：https://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

各钩子涵盖的范围：

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 名称>指定 IDE（vscode、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开始调试。