
名称	holoscan-install-source
版本	“1.0.0”
描述	“通过仓库内的./run脚本从源码构建Holoscan SDK。仅在已发布的软件包无法满足用户需求时使用。”
开源协议	Apache-2.0 metadata:
作者	“Holoscan Team holoscan-team@nvidia.com” github-url: “https://github.com/nvidia-holoscan/holoscan-sdk” tags: - holoscan - install - source - build - cmake

Holoscan SDK —— 从源码构建

目的

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

先决条件

配备NVIDIA GPU和驱动（nvidia-smi）的Linux主机。
git、带NVIDIA Container Toolkit的Docker（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的“从源码构建”部分（以及所选标签对应的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`