Installation Holoscan Debian/apt

Objectif

Installer le runtime C++ du Holoscan SDK + headers sur Ubuntu en utilisant le dépôt apt de NVIDIA, en sélectionnant le bon package holoscan-cuda-* selon le driver CUDA de l'hôte et en vérifiant avec les exemples C++ fournis.

Prérequis

• Ubuntu x86_64 (22.04 / 24.04) ou ARM64 (Jetson / IGX) avec un GPU NVIDIA et un driver fonctionnel (nvidia-smi).
• sudo et accès réseau à developer.download.nvidia.com et docs.nvidia.com.
• Package cuda-keyring (l'étape 2 l'installe s'il manque).

Limitations

• Pas de bindings Python depuis apt — combinez avec /holoscan-install-wheel si l'utilisateur en a besoin.
• Ubuntu uniquement. Les autres distros doivent utiliser le container ou l'installation wheel.
• La variante du package doit correspondre au driver CUDA de l'hôte (holoscan-cuda-12 vs holoscan-cuda-13) ; mauvaise variante → "CUDA driver version is insufficient".

Étape 0 : Consulter les instructions d'installation officielles

Récupérez la section Debian/apt de https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html avant d'installer. Extrayez :

• Les noms exacts des packages (holoscan-cuda-12, holoscan-cuda-13, holoscan)
• Les versions Ubuntu supportées
• L'URL cuda-keyring pour la bonne distro

Si la doc diffère de ce qui suit, la doc a raison.

Déterminez la version de l'OS et la variante CUDA si pas déjà connu — exécutez en parallèle :

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

Règle de variante CUDA — choisissez le package apt :

Étape 1 : Vérification des prérequis

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)"

Règles de décision selon ce que l'étape 1 a trouvé :

• Ignorez l'étape keyring si cuda-keyring est déjà installé.
• Ignorez apt-get update si le dépôt est déjà configuré et le package visible dans apt-cache show.
• Ignorez complètement l'étape 2 et allez directement à l'étape 3 si la bonne variante de package est déjà installée (ex. holoscan-cuda-12 quand ciblant cu12).

Étape 2 : Installation

Ignorez cette étape si le package est déjà installé (détecté à l'étape 1) ou si l'utilisateur est sur plateforme IGX.

# Si cuda-keyring manque (ajustez ubuntu2204/ubuntu2404 selon les besoins) et pas sur plateforme 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   # ou holoscan-cuda-13

Étape 3 : Vérification

Définissez l'env une fois pour le reste de cette étape, puis exécutez les trois vérifications 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 — attendu : "Hello World!"
$HS/examples/hello_world/cpp/hello_world

# tensor_interop — attendu : tenseurs doublant chaque passage, "Graph execution finished."
# Si "CUDA driver version is insufficient" : échangez la variante du package :
#   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) — attendu : Vulkan sélectionne le GPU NVIDIA, "Graph execution finished."
# Toujours exécuter headless : fonctionne avec ou sans affichage, évite les défaillances GUI sur 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

Étape 4 : Fournir à l'utilisateur le snippet d'env réutilisable

Une fois vérifié, partagez ce snippet avec l'utilisateur et suggérez de l'ajouter à son fichier de démarrage shell (ex., ~/.bashrc) s'il veut qu'il persiste entre les sessions :

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

Proposez ensuite les étapes suivantes :

• Ajouter le support Python : /holoscan-install-wheel
• Explorer les exemples : ls /opt/nvidia/holoscan/examples/
• Parcourir un exemple spécifique : /explain-example
• Commencer à construire une application Holoscan personnalisée

Dépannage

• python3 -c "import holoscan" échoue après l'installation apt. Normal — le package Debian est C++ uniquement depuis v3.0.0. Exécutez /holoscan-install-wheel pour ajouter les bindings Python.
• "CUDA driver version is insufficient" lors de l'exécution d'un exemple. Mauvaise variante du package. Revérifiez la version CUDA de nvidia-smi et échangez les variantes : sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12 (ou vice versa).
• E: Unable to locate package holoscan-cuda-12. cuda-keyring non installé ou dépôt pas encore tiré. Exécutez le bloc keyring + apt-get update de l'étape 2 (ajustez ubuntu2204/ubuntu2404 pour correspondre à l'hôte).
• Segmentation fault au lancement d'un exemple. ulimit -s 32768 non défini dans le shell actuel. Placez-le avant la commande (pattern étape 3).
• error while loading shared libraries: libholoscan_core.so. LD_LIBRARY_PATH n'est pas défini. Utilisez le snippet d'env de l'étape 4 — export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib.
• video_replayer ne trouve pas les données. Définissez HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data, ou exécutez sudo /opt/nvidia/holoscan/examples/download_example_data pour récupérer le dataset racerx.