holoscan-install-debian

Holoscan Debian/apt 安装

用途

使用 NVIDIA 的 apt 仓库在 Ubuntu 上安装 Holoscan SDK C++ 运行时和头文件，根据主机的 CUDA 驱动选择合适的 holoscan-cuda-* 软件包，并使用附带的 C++ 示例进行验证。

前提条件

• Ubuntu x86_64（22.04 / 24.04）或 ARM64（Jetson / IGX），配备 NVIDIA GPU，且驱动正常工作（nvidia-smi）。
• 具备 sudo 权限，并可访问网络以连接 developer.download.nvidia.com 和 docs.nvidia.com。
• cuda-keyring 软件包（如果缺少，步骤 2 会安装）。

限制

• apt 不提供 Python 绑定——如果用户需要 Python，请搭配 /holoscan-install-wheel 使用。
• 仅支持 Ubuntu。其他发行版必须使用容器或 wheel 安装。
• 软件包变体必须与主机的 CUDA 驱动匹配（holoscan-cuda-12 与 holoscan-cuda-13）；变体错误会导致“CUDA 驱动版本不足”。

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

安装前，获取 https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html 中的 Debian/apt 部分。提取以下信息：

• 确切的软件包名称（holoscan-cuda-12、holoscan-cuda-13、holoscan）
• 支持的 Ubuntu 版本
• 适用于相应发行版的 cuda-keyring URL

如果文档与以下内容有任何不一致，以文档为准。

如果尚不清楚，请确定操作系统版本和 CUDA 变体——并行运行：

lsb_release -a 2>/dev/null || cat /etc/os-release
nvidia-smi 2>&1 | head -5

CUDA 变体规则——选择 apt 软件包：

nvidia-smi CUDA Version	软件包
13.x+	holoscan-cuda-13
12.x（在 IGX 上）	holoscan
12.x（不在 IGX 上）	holoscan-cuda-12
12.x（nvgpu）	holoscan-cuda-12

步骤 1：检查前提条件

dpkg -l | grep cuda-keyring
dpkg -l | grep -E "holoscan-cuda-(12|13)|^ii  holoscan "
apt-cache show holoscan-cuda-13 holoscan-cuda-12 2>/dev/null | grep -E "^(Package|Version)"

根据步骤 1 的检查结果执行以下判断：

• 如果已安装 cuda-keyring，则跳过密钥环步骤。
• 如果仓库已配置，且可通过 apt-cache show 找到该软件包，则跳过 apt-get update。
• 如果已安装正确的软件包变体（例如，目标为 cu12 时已安装 holoscan-cuda-12），则完全跳过步骤 2，直接进入步骤 3。

步骤 2：安装

如果已安装该软件包（在步骤 1 中检测到）或用户使用的是 IGX 平台，则跳过此步骤。

# If cuda-keyring missing (adjust ubuntu2204/ubuntu2404 as needed) and not on IGX platform:
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb && sudo apt-get update

sudo apt-get install -y holoscan-cuda-12   # or holoscan-cuda-13

步骤 3：验证

为本步骤剩余部分设置一次环境变量，然后运行三项 C++ 检查：

HS=/opt/nvidia/holoscan
export LD_LIBRARY_PATH=$HS/lib
export HOLOSCAN_INPUT_PATH=$HS/data
ulimit -s 32768

ls $HS/examples/{hello_world,tensor_interop,video_replayer}/

# hello_world — expected: "Hello World!"
$HS/examples/hello_world/cpp/hello_world

# tensor_interop — expected: tensors doubling each pass, "Graph execution finished."
# If "CUDA driver version is insufficient": swap package variant:
#   sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12
$HS/examples/tensor_interop/cpp/tensor_interop

# video_replayer (10 frames, headless) — expected: Vulkan selects NVIDIA GPU, "Graph execution finished."
# Always run headless: works with or without a display, avoids GUI failure modes over SSH.
ls $HS/data/racerx 2>/dev/null || sudo $HS/examples/download_example_data
python3 -c "
c=open('$HS/examples/video_replayer/cpp/video_replayer.yaml').read()
c=c.replace('count: 0','count: 10').replace('repeat: true','repeat: false').replace('realtime: true','realtime: false')
c=c.replace('  width: 854','  headless: true\n  width: 854')
open('/tmp/vr.yaml','w').write(c)"
$HS/examples/video_replayer/cpp/video_replayer --config /tmp/vr.yaml

步骤 4：向用户提供可重复使用的环境变量片段

验证完成后，将此片段分享给用户，并建议他们将其添加到 shell 启动文件（例如 ~/.bashrc）中，以便在不同会话间保留设置：

export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib:${LD_LIBRARY_PATH}
export HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data
ulimit -s 32768

然后提供后续步骤：

• 添加 Python 支持：/holoscan-install-wheel
• 浏览示例：ls /opt/nvidia/holoscan/examples/
• 讲解特定示例：/explain-example
• 开始构建自定义 Holoscan 应用程序

故障排除

• apt 安装后运行 python3 -c "import holoscan" 失败。 这是预期行为——从 v3.0.0 起，Debian 软件包仅包含 C++ 内容。运行 /holoscan-install-wheel 以添加 Python 绑定。
• 运行示例时出现“CUDA 驱动版本不足”。 软件包变体错误。重新检查 nvidia-smi 的 CUDA Version，并切换变体：sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12（反之亦然）。
• E: Unable to locate package holoscan-cuda-12。 未安装 cuda-keyring，或尚未获取仓库。运行步骤 2 中的密钥环和 apt-get update 代码块（根据主机调整 ubuntu2204/ubuntu2404）。
• 启动示例时发生段错误。 当前 shell 中未设置 ulimit -s 32768。将其添加到命令前（参照步骤 3 的模式）。
• error while loading shared libraries: libholoscan_core.so。 未设置 LD_LIBRARY_PATH。使用步骤 4 中的环境变量片段：export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib。
• video_replayer 找不到数据。 设置 HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data，或运行 sudo /opt/nvidia/holoscan/examples/download_example_data 获取 racerx 数据集。