Back to Details

holoscan-install-source

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Holoscan SDK — Build from Source

Holoscan SDK — 从源码构建

Purpose

目的

Build the Holoscan SDK from the 
nvidia-holoscan/holoscan-sdk
source tree using its 
./run
script (which builds inside a Docker container), producing a local install tree consumable as a CMake dependency.
使用
nvidia-holoscan/holoscan-sdk
源码树中的
./run
脚本（在Docker容器内构建）从源码构建Holoscan SDK，生成可作为CMake依赖使用的本地安装目录树。

Prerequisites

前置条件

  • Linux host with NVIDIA GPU + driver (
    nvidia-smi
    ).
  • git
    , Docker with NVIDIA Container Toolkit (
    docker run --gpus all
    works), and 
    docker-buildx-plugin
    .
  • ~20 GB free disk for the build container + build/install trees.
  • 10–30 min for a clean first build.
  • 配备NVIDIA GPU及驱动的Linux主机（可运行
    nvidia-smi
    ）。
  • 已安装
    git
    、带有NVIDIA Container Toolkit的Docker（确保
    docker run --gpus all
    可正常运行），以及
    docker-buildx-plugin
    。
  • 构建容器及构建/安装目录树需要约20GB的可用磁盘空间。
  • 首次完整构建需要10-30分钟。

Limitations

限制说明

  • Only recommended when published packages (Conda / container / apt / wheel) don't fit — debug symbols, custom CMake options, or unsupported configs.
  • Still requires Docker — the 
    ./run
    script builds inside a container; this is not a true bare-metal build.
  • Cross-compiling to aarch64 needs 
    qemu-user-static
    on the host.
  • 仅当已发布的软件包（Conda/容器/apt/wheel）无法满足需求时推荐使用，比如需要调试符号、自定义CMake选项或不支持的配置。
  • 仍然需要Docker——
    ./run
    脚本在容器内构建，并非真正的裸机构建。
  • 交叉编译到aarch64架构需要在主机上安装
    qemu-user-static
    。

Step 0: Consult the Official Install Instructions

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

Always fetch the "Build from Source" section of 
https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html
(and the linked GitHub 
README.md
/ 
DEVELOP.md
for the chosen tag) before building. Extract: required 
./run
flags for the target architecture and CUDA major, supported branches/tags, any Dockerfile patches called out for the release, and the test names recommended for verification. If the doc disagrees with anything below, the doc wins.
在构建前，请务必查看
https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html
中的「从源码构建」章节（以及所选标签对应的GitHub上的
README.md
/
DEVELOP.md
文档）。提取以下信息：目标架构和CUDA主版本所需的
./run
参数、支持的分支/标签、该版本提及的任何Dockerfile补丁，以及推荐用于验证的测试名称。如果本文档与官方文档存在冲突，以官方文档为准。

Step 1: Prerequisites

步骤1：检查前置条件

Check that git and Docker (with GPU passthrough) are available:
bash
git --version
docker --version
docker run --rm --gpus all ubuntu:22.04 nvidia-smi
  • If Docker is missing → help install from https://docs.docker.com/engine/install/
  • If GPU passthrough fails → install NVIDIA Container Toolkit:
    bash
    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
  • If Docker buildx is missing: 
    sudo apt-get install docker-buildx-plugin
确认git和支持GPU透传的Docker已安装可用：
bash
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：
    bash
    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

Step 2: Clone the Repository

步骤2：克隆仓库

Clone repo to ~/holoscan/holoscan-sdk if needed
bash
mkdir -p ~/holoscan/
git clone https://github.com/nvidia-holoscan/holoscan-sdk.git
cd ~/holoscan/holoscan-sdk
To build a specific release tag (recommended for stability):
bash
git tag | grep -E '^v[0-9]' | sort -V | tail -5   # list recent tags
git checkout v<VERSION>                             # e.g. v4.1.0
如果需要，将仓库克隆到~/holoscan/holoscan-sdk目录：
bash
mkdir -p ~/holoscan/
git clone https://github.com/nvidia-holoscan/holoscan-sdk.git
cd ~/holoscan/holoscan-sdk
若要构建特定的发布版本标签（推荐用于稳定性）：
bash
git tag | grep -E '^v[0-9]' | sort -V | tail -5   # 列出最近的标签
git checkout v<VERSION>                             # 示例：v4.1.0

Step 3: Build

步骤3：构建

The 
./run build
script handles container creation, CMake configuration, compilation, and install in one step. Warn the user this takes 10–30 minutes on first run (downloads base image + compiles).
bash
./run build
Common options:
FlagPurpose
--type debug
Debug build (symbols, no optimization)
--type RelWithDebInfo
Release + debug symbols
--arch aarch64
Cross-compile for ARM64 (needs 
sudo apt install qemu-user-static
)
--gpu igpu
iGPU build for Jetson/IGX
--dryrun
Preview commands without executing
If CMake cache errors occur after changing options:
bash
./run clear_cache && ./run build
Output lands in these folders, and can be retrieved with 
./run get_build_dir
and 
./run get_install_dir
  • Build dir: 
    build-cu<N>-<arch>/
  • Install dir: 
    install-cu<N>-<arch>/
    .
./run build
脚本可一步完成容器创建、CMake配置、编译和安装操作。提醒用户首次运行需要10-30分钟（需下载基础镜像并完成编译）。
bash
./run build
常用选项：
参数用途
--type debug
调试版本构建（包含调试符号，无优化）
--type RelWithDebInfo
发布版本+调试符号
--arch aarch64
交叉编译为ARM64架构（需安装
sudo apt install qemu-user-static
）
--gpu igpu
为Jetson/IGX构建iGPU版本
--dryrun
预览命令但不执行
如果修改选项后出现CMake缓存错误：
bash
./run clear_cache && ./run build
构建输出会存放在以下目录，可通过
./run get_build_dir
和
./run get_install_dir
获取路径：
  • 构建目录：
    build-cu<N>-<arch>/
  • 安装目录：
    install-cu<N>-<arch>/
    .

Step 4: Run Tests

步骤4：运行测试

Run the following tests
  • 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
bash
./run test
To run all six required tests at once, use a single-quoted regex (the 
|
must be quoted to prevent bash from treating it as a pipe):
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 a specific test by name or regex:
bash
./run test --name <test_name>
./run test --options "-R '<regex>' --output-on-failure"
./run test --verbose
Important: Always single-quote the regex string when it contains 
|
— without quotes, bash interprets 
|
as a pipe and the command fails with 
command not found
.
Expected: all tests pass. Note any failures and report them to the user before continuing.
运行以下测试：
  • 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
bash
./run test
若要一次性运行全部六项必填测试，请使用单引号包裹正则表达式（必须对
|
进行转义，避免bash将其视为管道符）：
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"
按名称或正则表达式运行特定测试：
bash
./run test --name <test_name>
./run test --options "-R '<regex>' --output-on-failure"
./run test --verbose
重要提示： 当正则表达式包含
|
时，请务必用单引号包裹——如果不加引号，bash会将
|
解释为管道符，导致命令执行失败并提示
command not found
。
预期结果：所有测试通过。若出现任何测试失败，请记录并告知用户后再继续。

Step 5: Point Applications at the Install Tree

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

Once built, applications can use the install tree as a CMake dependency. Give the user this path:
/path/to/holoscan-sdk/install-cu<N>-<arch>/
They can set 
Holoscan_ROOT
or 
CMAKE_PREFIX_PATH
to this directory when building their own applications.
构建完成后，应用可将该安装目录树作为CMake依赖使用。告知用户以下路径：
/path/to/holoscan-sdk/install-cu<N>-<arch>/
用户在构建自己的应用时，可将
Holoscan_ROOT
或
CMAKE_PREFIX_PATH
设置为该目录。

Troubleshooting

故障排查

SymptomFix
bash: <TEST_NAME>: command not found
when running tests		The regex contains 
|
— wrap it in single quotes: 
--options "-R '<regex>'"
CMake cache errors after option change
./run clear_cache && ./run build
Docker buildx not found
sudo apt-get install docker-buildx-plugin
GPU not visible inside build containerVerify NVIDIA Container Toolkit and re-run 
sudo nvidia-ctk runtime configure --runtime=docker
Cross-compile fails (aarch64)Install qemu: 
sudo apt-get install qemu-user-static
症状解决方法
运行测试时出现
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