Holoscan SDK — Construire à partir des sources

Objectif

Construire le Holoscan SDK à partir de l'arborescence source nvidia-holoscan/holoscan-sdk en utilisant son script ./run (qui construit à l'intérieur d'un conteneur Docker), produisant un arbre d'installation local consommable comme dépendance CMake.

Prérequis

• Hôte Linux avec GPU NVIDIA + driver (nvidia-smi).
• git, Docker avec NVIDIA Container Toolkit (docker run --gpus all fonctionne), et docker-buildx-plugin.
• ~20 GB d'espace disque libre pour le conteneur de construction + les arbres de construction/installation.
• 10–30 min pour une première construction complète.

Limitations

• Recommandé uniquement si les packages publiés (Conda / container / apt / wheel) ne conviennent pas — symboles de débogage, options CMake personnalisées, ou configurations non supportées.
• Nécessite toujours Docker — le script ./run construit à l'intérieur d'un conteneur ; ce n'est pas une véritable construction bare-metal.
• La compilation croisée vers aarch64 nécessite qemu-user-static sur l'hôte.

Étape 0 : Consulter les instructions d'installation officielles

Toujours consulter la section « Build from Source » de https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html (et le README.md / DEVELOP.md GitHub lié pour le tag choisi) avant de construire. Extraire : drapeaux ./run requis pour l'architecture cible et CUDA majeur, branches/tags supportés, tous les patches Dockerfile appelés pour la version, et les noms de test recommandés pour la vérification. Si la doc contredit quoi que ce soit ci-dessous, la doc a raison.

Étape 1 : Prérequis

Vérifier que git et Docker (avec passthrough GPU) sont disponibles :

git --version
docker --version
docker run --rm --gpus all ubuntu:22.04 nvidia-smi

• Si Docker est manquant → aide pour l'installation depuis https://docs.docker.com/engine/install/
• Si le passthrough GPU échoue → installer 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

• Si docker buildx est manquant : sudo apt-get install docker-buildx-plugin

Étape 2 : Cloner le dépôt

Cloner le repo vers ~/holoscan/holoscan-sdk si nécessaire

mkdir -p ~/holoscan/
git clone https://github.com/nvidia-holoscan/holoscan-sdk.git
cd ~/holoscan/holoscan-sdk

Pour construire un tag de version spécifique (recommandé pour la stabilité) :

git tag | grep -E '^v[0-9]' | sort -V | tail -5   # lister les tags récents
git checkout v<VERSION>                             # ex. v4.1.0

Étape 3 : Construire

Le script ./run build gère la création du conteneur, la configuration CMake, la compilation et l'installation en une seule étape. Avertir l'utilisateur que cela prend 10–30 minutes à la première exécution (télécharge l'image de base + compile).

./run build

Options communes :

Si des erreurs de cache CMake surviennent après modification des options :

./run clear_cache && ./run build

La sortie se trouve dans ces dossiers et peut être récupérée avec ./run get_build_dir et ./run get_install_dir

• Répertoire de construction : build-cu<N>-<arch>/
• Répertoire d'installation : install-cu<N>-<arch>/.

Étape 4 : Exécuter les tests

Exécuter les tests suivants

• 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

Pour exécuter les six tests requis à la fois, utiliser une regex entre guillemets simples (le | doit être échappé pour empêcher bash de le traiter comme un pipe) :

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

Exécuter un test spécifique par nom ou regex :

./run test --name <test_name>
./run test --options "-R '<regex>' --output-on-failure"
./run test --verbose

Important : Toujours mettre la chaîne regex entre guillemets simples quand elle contient | — sans guillemets, bash interprète | comme un pipe et la commande échoue avec command not found.

Attendu : tous les tests réussissent. Noter les échecs et les signaler à l'utilisateur avant de continuer.

Étape 5 : Pointer les applications vers l'arbre d'installation

Une fois construit, les applications peuvent utiliser l'arbre d'installation comme dépendance CMake. Donner à l'utilisateur ce chemin :

/path/to/holoscan-sdk/install-cu<N>-<arch>/

Il peut définir Holoscan_ROOT ou CMAKE_PREFIX_PATH sur ce répertoire lors de la construction de ses propres applications.

Dépannage