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 vs holoscan-cuda-13）；错误变体导致"CUDA driver version is insufficient"。

步骤 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

如果文档与以下内容不符，以文档为准。

如果尚未确定，请确定 OS 版本和 CUDA 变体 —— 并行运行：

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

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

步骤 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 平台上，跳过此步骤。

# 如果缺少 cuda-keyring（根据需要调整 ubuntu2204/ubuntu2404）且不在 IGX 平台上：
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   # 或 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 —— 预期："Hello World!"
$HS/examples/hello_world/cpp/hello_world

# tensor_interop —— 预期：张量每次传递加倍，"Graph execution finished."
# 如果显示"CUDA driver version is insufficient"：交换包变体：
#   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 帧，无头模式）—— 预期：Vulkan 选择 NVIDIA GPU，"Graph execution finished."
# 始终以无头模式运行：有或没有显示都能工作，避免通过 SSH 时的 GUI 失败模式。
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: truen  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 driver version is insufficient"。 错误的包变体。重新检查 nvidia-smi CUDA 版本并交换变体：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 数据集。