mcpField
H
holoscan-install-source

holoscan-install-source

github.com/promptingcompany開発039 回インストール17 週間前に更新
リポジトリ

holoscan-install-source について

`nvidia-holoscan/holoscan-sdk` のソースから Holoscan SDK をビルドし、CMake で使える形でインストールする開発者向けガイドです。公開パッケージではデバッグや独自の CMake 設定に対応できない場合を対象とします。

主な機能

  1. 01`./run` による Docker 内ビルド
  2. 02デバッグおよびデバッグシンボル付きビルド
  3. 03aarch64 クロスコンパイルの選択肢
  4. 04SDK のサンプルテスト実行
  5. 05インストール先を CMake 依存として利用

活用シーン

  1. 01独自の CMake オプションで SDK をビルド
  2. 02デバッグシンボル付きビルドの準備
  3. 03ビルド後の C++ と Python サンプルの検証
  4. 04ローカル SDK を CMake アプリに接続

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/promptingcompany/nv-skills --skill holoscan-install-source

インストール後、Claude Code で/holoscan-install-sourceを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

BENCHMARK.md
skill-card.md
skill.oms.sig
evals/
evals.json

詳細

Holoscan SDK — ソースからビルド

目的

nvidia-holoscan/holoscan-sdk のソースツリーから ./run スクリプト（Docker コンテナ内でビルドします）を使用して Holoscan SDK をビルドし、CMake の依存関係として利用できるローカルのインストールツリーを作成します。

前提条件

  • NVIDIA GPU とドライバーを搭載した Linux ホスト（nvidia-smi）。
  • 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 の「Build from Source」セクションと、選択したタグに対応するリンク先の GitHub README.md／DEVELOP.md を取得してください。対象アーキテクチャと CUDA のメジャーバージョンに必要な ./run フラグ、サポートされているブランチ／タグ、リリースに関して指定されている Dockerfile のパッチ、検証に推奨されるテスト名を確認してください。以下の内容とドキュメントが異なる場合は、ドキュメントを優先してください。

ステップ 1：前提条件

GPU パススルーが有効な状態で git と Docker を利用できることを確認します。

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 aarch64ARM64 向けクロスコンパイル（sudo apt install qemu-user-static が必要）
--gpu igpuJetson／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

必須の 6 つのテストをまとめて実行するには、シングルクォートで囲んだ正規表現を使用します（| がパイプとして扱われないように引用符で囲む必要があります）。

./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

コメント

Markdown 対応