holoscan-install-source

Holoscan SDK — 从源代码构建

目的

使用 nvidia-holoscan/holoscan-sdk 源代码树中的 ./run 脚本（在 Docker 容器内构建）构建 Holoscan SDK，生成可用作 CMake 依赖项的本地安装目录树。

先决条件

• Linux 主机，配备 NVIDIA GPU 和驱动程序（nvidia-smi）。
• git、Docker 和 NVIDIA Container Toolkit（docker run --gpus all 可正常运行），以及 docker-buildx-plugin。
• 构建容器和构建／安装目录树需要约 20 GB 可用磁盘空间。
• 首次全新构建需要 10–30 分钟。

限制

• 仅当已发布的软件包（Conda／容器／apt／wheel）无法满足需求时才建议使用此方式，例如需要调试符号、自定义 CMake 选项或不受支持的配置。
• 仍然需要 Docker——./run 脚本会在容器内构建；这并非真正的裸机构建。
• 交叉编译到 aarch64 需要在主机上安装 qemu-user-static。

步骤 0：查阅官方安装说明

构建前，务必获取 https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html 中的“Build from Source”部分（以及所选标签对应的 GitHub README.md／DEVELOP.md）。提取以下信息：目标架构和 CUDA 主版本所需的 ./run 标志、支持的分支／标签、该版本要求的任何 Dockerfile 补丁，以及建议用于验证的测试名称。如果文档与下文有任何不一致，以文档为准。

步骤 1：先决条件

检查 git 和 Docker（支持 GPU 直通）是否可用：

git --version
docker --version
docker run --rm --gpus all ubuntu:22.04 nvidia-smi

• 如果未安装 Docker → 请参阅 https://docs.docker.com/engine/install/ 了解安装方法
• 如果 GPU 直通失败 → 安装 NVIDIA Container Toolkit：

  curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
  curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
    | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
  sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
  sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker
  

• 如果缺少 Docker buildx：sudo apt-get install docker-buildx-plugin

步骤 2：克隆仓库

如有需要，将仓库克隆到 ~/holoscan/holoscan-sdk

mkdir -p ~/holoscan/
git clone https://github.com/nvidia-holoscan/holoscan-sdk.git
cd ~/holoscan/holoscan-sdk

若要构建特定发行版标签（稳定性更佳，推荐使用）：

git tag | grep -E '^v[0-9]' | sort -V | tail -5   # list recent tags
git checkout v<VERSION>                             # e.g. v4.1.0

步骤 3：构建

./run build 脚本会一步完成容器创建、CMake 配置、编译和安装。请提醒用户，首次运行需要 10–30 分钟（下载基础镜像并进行编译）。

./run build

常用选项：

标志	用途
--type debug	调试构建（包含符号，不进行优化）
--type RelWithDebInfo	发布构建 + 调试符号
--arch aarch64	交叉编译到 ARM64（需要 sudo apt install qemu-user-static）
--gpu igpu	面向 Jetson／IGX 的 iGPU 构建
--dryrun	预览命令但不执行

更改选项后若出现 CMake 缓存错误：

./run clear_cache && ./run build

输出会放在以下目录中，可通过 ./run get_build_dir 和 ./run get_install_dir 获取

• 构建目录：build-cu<N>-<arch>/
• 安装目录：install-cu<N>-<arch>/。

步骤 4：运行测试

运行以下测试

• EXAMPLE_CPP_HELLO_WORLD_TEST
• EXAMPLE_PYTHON_HELLO_WORLD_TEST
• EXAMPLE_CPP_TENSOR_INTEROP_TEST
• EXAMPLE_PYTHON_TENSOR_INTEROP_TEST
• EXAMPLE_CPP_VIDEO_REPLAYER_TEST
• EXAMPLE_PYTHON_VIDEO_REPLAYER_TEST

./run test

若要一次运行全部六项必需测试，请使用单引号括起的正则表达式（必须给 | 加引号，以免 bash 将其视为管道）：

./run test --options "-R 'EXAMPLE_CPP_HELLO_WORLD_TEST|EXAMPLE_PYTHON_HELLO_WORLD_TEST|EXAMPLE_CPP_TENSOR_INTEROP_TEST|EXAMPLE_PYTHON_TENSOR_INTEROP_TEST|EXAMPLE_CPP_VIDEO_REPLAYER_TEST|EXAMPLE_PYTHON_VIDEO_REPLAYER_TEST' --output-on-failure"

按名称或正则表达式运行特定测试：

./run test --name <test_name>
./run test --options "-R '<regex>' --output-on-failure"
./run test --verbose

重要： 正则表达式中包含 | 时，务必使用单引号括起字符串——不加引号时，bash 会将 | 解释为管道，导致命令失败并提示 command not found。

预期结果：所有测试均通过。请记录任何失败，并在继续之前告知用户。

步骤 5：将应用指向安装目录树

构建完成后，应用可以将该安装目录树用作 CMake 依赖项。向用户提供此路径：

/path/to/holoscan-sdk/install-cu<N>-<arch>/

他们可以在构建自己的应用时，将 Holoscan_ROOT 或 CMAKE_PREFIX_PATH 设置为此目录。

故障排查

症状	解决方法
运行测试时出现 bash: <TEST_NAME>: command not found	正则表达式中包含 |，请用单引号括起来：--options "-R '<regex>'"
更改选项后出现 CMake 缓存错误	./run clear_cache && ./run build
找不到 Docker buildx	sudo apt-get install docker-buildx-plugin
构建容器内看不到 GPU	检查 NVIDIA Container Toolkit，然后重新运行 sudo nvidia-ctk runtime configure --runtime=docker
交叉编译失败（aarch64）	安装 qemu：sudo apt-get install qemu-user-static