Installation NVSHMEM

Objectif

Guider les installations sûres et conscientes de la version de NVSHMEM et NVSHMEM4Py sur des postes de travail, des clusters, des systèmes multi-nœuds et des conteneurs. Sélectionner une méthode d'installation à partir des exigences documentées et des faits système observés, puis fournir les commandes exactes et les étapes de validation. Exécuter les actions d'installation uniquement après approbation explicite séparate.

Prérequis

$nvshmem-docs doit être disponible dans le registre des skills ou lisible à ../nvshmem-docs/SKILL.md pour résoudre les exigences officielles spécifiques à la version. Si aucune des deux routes n'est disponible, les exigences exactes et les commandes d'installation sont bloquées ; retourner les liens officiels mappés et identifier les prétentions non résolues. Aucune clé API n'est requise.
Utiliser le $nvshmem-troubleshoot-and-report-bugs enregistré pour les défaillances post-installation au lancement, initialisation, runtime ou validation. S'il est indisponible, préserver la preuve de diagnostic et fournir une guidance de support officiel au lieu de supposer qu'une solution de secours locale illisible existe.
Confirmer l'accès réseau pour les artefacts distants et l'autorité d'écriture pour le préfixe d'installation choisi avant l'exécution.
Ne pas inspecter la cible automatiquement. D'abord compléter l'intake d'installation, puis demander si l'utilisateur veut exécuter la probe en lecture seule lui-même ou s'il veut que l'agent l'exécute. L'exécuter uniquement après que l'utilisateur sélectionne explicitement cette dernière option.
Résoudre les dépendances NVSHMEM, CUDA, pilote, compilateur, launcher, bootstrap et transport à partir de la documentation de version exacte et de l'inspection de cible au lieu de les traiter comme des prérequis fixes.
Inspecter la cible uniquement via un shell non privilégié déjà disponible. Si l'inspection directe n'est pas disponible, fournir la probe pour que l'utilisateur l'exécute et retourner son résultat. Ne jamais demander ni utiliser sudo, un accès root ou une escalade de privilège pour l'inspection.

Entrées

Utiliser l'intake détaillé sous Résoudre la demande.

Obligatoires : surface API, type de cible, autorité administrateur et portée cible, portée et préfixe d'installation, sélection launcher/bootstrap ou recommend, et faits système cible suffisants pour évaluer les exigences documentées.
Optionnels : une version NVSHMEM complète, par défaut latest, et une méthode d'installation préférée.
Conditionnels : configuration de construction source quand source est sélectionné.
Choix de probe : obligatoire avant l'inspection directe de cible : probe exécutée par l'utilisateur ou par l'agent.
Approbation d'exécution : optionnelle et non approuvée par défaut ; l'approbation s'applique uniquement au bloc de commande exacte présenté.

Utiliser la première valeur sans conflit dans cet ordre de source :

Fichier d'état.
Arguments de prompt explicites.
Contexte de l'agent.
Prompt utilisateur libre.

Signaler les conflits au lieu de les fusionner silencieusement. L'exécution exige toujours une approbation explicite actuelle pour le bloc de commande exacte présenté ; l'absence de réponse n'est pas une approbation.

Limitations

Dépendre de la documentation officielle en direct pour les exigences exactes de version et les commandes. Si la récupération échoue, fournir les liens officiels mappés et identifier les prétentions non vérifiées au lieu de synthétiser une réponse.
Traiter la probe système comme un instantané du shell et du nœud actuel ; elle ne peut pas établir la cohérence à l'échelle du cluster, la politique du site, la configuration conteneur-hôte ou un chemin réseau non testé.

Instructions

Sécurité et valeurs par défaut

Par défaut, fournir des commandes, pas les exécuter. Une demande d'installation exprime l'intention, pas l'approbation.
Ne jamais demander ni utiliser sudo, accès root ou escalade de privilège pour l'inspection. Utiliser uniquement un shell non privilégié existant ; sinon donner à l'utilisateur la probe à exécuter.
Traiter les téléchargements, les modifications de référentiel, les opérations de package, les tirages/constructions de conteneur, les constructions source et les écritures de préfixe d'installation comme des actions d'installation. Avant d'exécuter toute action de ce type, présenter le bloc de commande exacte, les effets et les chemins, puis obtenir l'approbation explicite pour ce bloc. Le silence n'est pas une approbation ; les commandes révisées exigent une approbation nouvelle.
Ne pas modifier les pilotes, modules noyau, configuration système, modulefiles ou état de cluster partagé sauf si explicitement demandé et approuvé séparément.
S'arrêter à la première commande d'installation échouée et préserver sa sortie. Permettre au maximum trois tentatives révisées séparément approuvées avant de transférer.

Résoudre la demande

Avant d'exécuter une probe de cible ou toute autre commande d'inspection système, demander et résoudre l'intake d'installation. Ne pas déduire une réponse du shell actuel quand l'utilisateur n'a pas encore choisi la cible ou la portée d'installation prévues.

Poser les questions suivantes textuellement dans un seul message numéroté. Omettre uniquement une question dont la réponse est déjà explicite, sans ambiguïté et sans conflit dans la demande ou le fichier d'état. Ne pas sonder, récupérer la documentation spécifique à la version ou proposer une méthode d'installation jusqu'à ce que l'utilisateur réponde à la question 8.

API : Quelle interface NVSHMEM avez-vous besoin : C/C++, Python (NVSHMEM4Py) ou both ?
Version : Quelle version complète de NVSHMEM voulez-vous ? Répondez latest pour utiliser la dernière version entièrement documentée.
Cible : Où NVSHMEM doit-il s'exécuter : HPC cluster / multi-node system ou single machine ?
Autorité : Avez-vous les droits administrateur et l'autorité pour installer des logiciels à l'échelle du système dans la portée cible ? Répondez administrator ou unprivileged.
Portée : Où NVSHMEM doit-il être installé : user-owned prefix, system packages, container, virtual environment, ? Inclure le préfixe exact ou le chemin d'environnement quand ce n'est pas un conteneur ou des packages système.
Méthode : Avez-vous une préférence de méthode : binary archive, system repository/package, source build, HPC SDK container, PyPI, Conda, ? Répondez recommend si vous n'avez pas de préférence.
Probe : Puis-je exécuter la probe système en lecture seule fournie sur le shell cible ? Répondez agent-run, ou répondez user-run et je vous donnerai la commande à exécuter et coller en retour.
Launcher : Quel launcher/bootstrap l'application et la validation deux-PE doivent-ils utiliser : mpirun/mpiexec, nvshmrun, srun, oshrun, un autre launcher, ou recommend ?

Interpréter administrator, unprivileged exactement comme indiqué. Si la question 4 reste sans réponse après une demande, enregistrer unknown et appliquer la valeur par défaut de planification non privilégiée de Sécurité et valeurs par défaut. Rejeter une portée que l'autorité enregistrée ne peut pas modifier et offrir des alternatives viables. Si la question 2 fournit une version incomplète comme major.minor, la traiter comme une requête de préfixe : utiliser $nvshmem-docs pour résoudre la dernière version entièrement documentée correspondante, afficher la version résolue complète et obtenir une confirmation avant d'exécuter des commandes spécifiques à la version. Sinon préserver la version demandée littéralement ou latest. Traiter la question 8 comme l'intention launcher/bootstrap, pas la preuve que le launcher est installé ou compatible. Après la probe, vérifier une sélection explicite contre les commandes observées et la documentation versionnée. Pour recommend, sélectionner le launcher compatible impliqué par l'environnement d'exécution quand c'est sans ambiguïté ; demander quand plusieurs choix compatibles restent. Si aucun n'est disponible, enregistrer none plutôt que d'inventer un launcher, continuer la planification d'installation quand un launcher n'est pas une prérequis d'installation et marquer la validation runtime deux-PE comme bloquée jusqu'à ce qu'un launcher compatible soit disponible.

Après que la question 8 soit répondue, exécuter ou fournir la probe fournie comme sélectionné. Utiliser la probe non privilégiée choisie pour chaque fait qu'elle peut collecter, et demander uniquement les faits restants. Poser les questions conditionnelles suivantes uniquement quand leur condition s'applique :

Source build : "Quels topologie GPU et réseau la construction supportera-t-elle (nœuds, GPUs par nœud et interconnexion) ? Quels NICs RDMA/couche de liaison ou fournisseur de fabric sont requis ? Quelles architectures CUDA doivent être construites ? La construction doit-elle inclure les liaisons Python, tests, exemples, Hydra ou packages ?" Lire source-build.md.
Cluster Slurm/HPC géré : "L'installation résultante peut-elle être visible de chaque nœud de calcul prévu, et la politique du site permet-elle le préfixe utilisateur sélectionné ou le runtime conteneur ?"
Préfixe cluster partagé : "Qui possède ce préfixe, et tous les nœuds de calcul participant montent-ils le même chemin ?"
Conteneur existant ou nouveau : "Quel runtime sera utilisé (Docker, Apptainer/Singularity ou un autre runtime approuvé), et le passage GPU et des appareils réseau requis sont-ils autorisés par la politique du site ?"
Python ou both : "Quel interpréteur Python ou environnement existant doit contenir NVSHMEM4Py ? Puis-je créer un nouvel environnement virtuel si nécessaire ?"

Si l'API demandée est Python (NVSHMEM4Py) et la méthode demandée est binary archive ou system repository/package, rejeter cette combinaison de méthode avant de sélectionner des artefacts ou de présenter des commandes. NVSHMEM4Py doit être installé via un canal de package Python supporté (PyPI ou Conda) ; sélectionner source build uniquement quand l'utilisateur a explicitement besoin de construire les liaisons. Ne pas traiter une archive NVSHMEM native ou un package NVSHMEM système comme un installateur NVSHMEM4Py ou en demander un à l'utilisateur. Pour both, une archive ou un package système peut fournir le runtime C/C++, mais NVSHMEM4Py exige toujours sa propre installation PyPI, Conda ou source-build explicitement demandée.

Enregistrer chaque réponse dans Résumé de cible, marquant les réponses fournies comme intention utilisateur observée et les valeurs optionnelles sans réponse comme unknown.

Enregistrer le launcher résolu et le bootstrap applicable dans Résumé de cible ou Vérification des exigences, utilisant none ou not applicable explicitement quand approprié. Un import Python, un chargement de bibliothèque native ou une exécution un-PE ne remplace pas le test runtime deux-PE même-nœud. Ne jamais silencieusement omettre ce test quand les prérequis launcher, GPU, scheduler ou allocation ne sont pas disponibles.

Après que l'utilisateur sélectionne un chemin de probe, ne pas demander d'informations qui peuvent être obtenues via l'inspection non privilégiée choisie.

Consulter la documentation en direct

Utiliser $nvshmem-docs avant de déclarer les exigences, compatibilité, versions supportées, noms de packages, URLs de référentiel, tags d'image, versions de dépendances, variables de construction ou commandes exactes. Quand on travaille à partir de cet arbre source et que le skill frère n'est pas enregistré, lire et suivre ../nvshmem-docs/SKILL.md directement.

Passer la version complète normalisée ou le littéral latest.
Résoudre latest vers la dernière version NVSHMEM dont la version, les exigences et la compatibilité sont établies par la documentation officielle NVSHMEM. Traiter la version PyPI/Conda d'une liaison Python comme une version de package indépendante, pas comme une version candidate NVSHMEM : sélectionner son artefact actuellement compatible et publié à partir de ses métadonnées de package et signaler les deux versions séparément. Appliquer la règle de candidat séparé uniquement quand un artefact représente une nouvelle version runtime/library NVSHMEM que la dernière documentation correspondante. Ne pas appliquer les prétentions de compatibilité de version plus ancienne à un tel candidat runtime.
Demander le guide d'installation, les limitations de compatibilité et release, la procédure de package ou source et la page NVSHMEM4Py quand pertinent.
Pour les conteneurs NVIDIA HPC SDK, demander aussi les routes NGC image et container-guide. Garder la version HPC SDK/image séparée de la version NVSHMEM fournie.
Coder en dur uniquement les familles de méthode stable et le processus de décision dans ce skill. Ne jamais supposer qu'un nom de package, option CMake, exigence numérique ou tag de conteneur d'une version précédente est toujours valide.
Pour les archives binaires et les téléchargements de package Linux (DEB, RPM ou packages Ubuntu), commencer par la page officielle de téléchargement NVIDIA NVSHMEM : https://developer.nvidia.com/nvshmem-downloads. Quand son manifeste de redistribution officiel lié fournit le relative_path d'artefact exact, le résoudre contre la base de téléchargement officielle de ce manifeste et montrer une commande copiable pour l'URL résultante. De même, montrer une commande quand la page officielle en direct expose une URL d'artefact complète. Sélectionner binary archive est suffisant pour présenter la commande, mais jamais pour l'exécuter. Inclure cet avis avec la commande : "En téléchargeant et utilisant le logiciel, vous acceptez de vous conformer pleinement aux termes et conditions du Contrat de licence NVIDIA Software." Si NVIDIA exige l'authentification ou l'acceptation interactive de licence et qu'aucune URL exacte ni chemin de manifeste officiel n'est disponible pour la session actuelle, signaler cette limitation externe et fournir la page officielle de téléchargement. Ne jamais construire un nom de fichier d'artefact ou une URL à partir d'un motif de dénomination mémorisé.
Pour chaque source build, obtenir la version sélectionnée à partir de la page officielle des releases NVIDIA NVSHMEM GitHub : https://github.com/NVIDIA/nvshmem/releases. Utiliser l'archive source ou le tag de release du release publié, vérifier que sa version correspond à la version NVSHMEM résolue et signaler l'URL de release comme provenance.
Si la documentation en direct ne peut pas être récupérée, retourner les liens roités officiels et identifier les prétentions bloquées. Ne pas inventer de commandes d'installation de mémoire.
Si les pages officielles entrent en conflit, signaler le conflit et éviter l'exécution jusqu'à ce qu'il soit résolu.

Inspecter et évaluer la cible

Uniquement après que l'intake d'installation soit complète et que l'utilisateur demande explicitement à l'agent de le faire, exécuter la probe en lecture seule fournie sans arguments :

run_script("scripts/collect-system-info.sh")

Si l'utilisateur choisit de l'exécuter lui-même, fournir cette commande et attendre sa sortie. Garder la probe non privilégiée. Sur un cluster, inspecter les nœuds de calcul représentatifs uniquement dans une allocation existante ; sinon fournir le script ou les commandes équivalentes pour que l'utilisateur l'exécute là-bas.

Comparer les faits collectés avec la documentation de version exacte et classifier chaque exigence pertinente :

pass : la cible satisfait l'exigence documentée.
fail : la cible contredit l'exigence documentée. S'arrêter et fournir des choix de remédiation.
unknown : la preuve disponible est insuffisante. Demander le plus petit fait manquant et ne pas exécuter les commandes d'installation.
not applicable : l'exigence appartient uniquement à une fonctionnalité optionnelle non sélectionnée.

Pour une dépendance de transport optionnelle manquante, ne pas activer ce transport et expliquer la perte de capacité. S'il s'agit du transport à distance de base adapté au NIC, demander avant de procéder sans support de transport distant. Ne pas affaiblir une exigence obligatoire.

Quand plusieurs fonctionnalités ou transports sont activés, exiger l'union de leurs prérequis documentés. Ne jamais désactiver un prérequis documenté en laissant la fonctionnalité dépendante activée.

Pour chaque source build, sélectionner un transport distant avant de générer la configuration. Quand la probe trouve un NIC RDMA utilisable ou un fournisseur de fabric supporté, choisir le transport distant de base correspondant à partir de source-build.md et évaluer ses prérequis. Ne pas omettre le support distant simplement parce que la première validation est même-nœud.

Uniquement un verdict pass permet à un transport d'être activé par défaut. Un prérequis unknown bloque la génération d'une configuration source exacte jusqu'à ce que le fait manquant soit résolu ; ne pas activer le transport ou l'omettre silencieusement. Un verdict fail désactive ce transport et exige que la perte de capacité soit signalée, avec acceptation utilisateur quand elle supprime le chemin distant de base adapté au NIC.

Quand aucun transport distant n'est sélectionné—parce que l'utilisateur limite la portée aux GPUs locaux, aucun NIC/fournisseur correspondant n'est présent ou l'utilisateur accepte un échec de prérequis documenté—laisser tous les options de support de transport distant éteintes. Si un transport correspondant a un prérequis unknown, obtenir le fait manquant ou demander à l'utilisateur avant de générer la commande d'installation.

Choisir, exécuter et valider

Après la vérification des exigences, lire installation-matrix.md pour sélectionner une méthode. Pour une source build, aussi lire source-build.md. Avant de présenter les commandes, de demander l'approbation d'exécution ou de valider une installation, lire execution-and-validation.md. En cas d'échec de planification, installation ou validation, lire failure-handoff.md.

Dépannage

Pour tout échec de planification, installation ou validation, préserver la commande, la sortie, le résumé de cible, le transport/bootstrap sélectionné et la version de documentation, puis suivre failure-handoff.md. Pour les défaillances post-installation au lancement, initialisation, runtime ou validation, utiliser $nvshmem-troubleshoot-and-report-bugs quand disponible ; sinon fournir la guidance de support officiel avec la preuve préservée.

Scripts disponibles

Script	Objectif	Arguments
`scripts/collect-system-info.sh`	Collecter des informations système, GPU, CUDA, launcher, RDMA et package-manager en lecture seule et non privilégiées pour la planification d'installation.	Aucun

Exemples

Demande : "Installer le dernier package de développement NVSHMEM C/C++ sur ce système Ubuntu."

Résoudre latest, demander l'autorité administrateur, inspecter le système et recommander APT uniquement quand l'utilisateur confirme l'autorité sur la cible. Présenter les commandes exactes et la validation avant de demander l'approbation d'exécution.

Demande : "Construire NVSHMEM à partir du source avec IBGDA pour ces GPUs connectés à Infiniband."

Inspecter le GPU, le NIC, le launcher et l'environnement de dépendance ; vérifier la version de release demandée et les prérequis IBGDA via $nvshmem-docs ; puis présenter une configuration CMake complète, une séquence d'installation et un plan de validation même-nœud et deux-nœuds avant de demander l'approbation.

nvshmem-install