# -*- coding: utf-8 mode: text -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8

Les scripts RUNS sont des scripts servant à déployer certains services ou à
faire certaines opérations.

runs diffère un peu de uinst, qui est orienté copie de fichiers et configuration
d'une arborescence. Avec runs, chaque script fait une seule opération, en
utilisant éventuellement certains fichiers disponibles dans le répertoire du
script.

RUNSPATH contient une liste de répertoires qu'il faut initialiser avec la
commande 'runs --init'. L'arborescence est de la forme:

    runsdir
      +- scripts
      |    \_ SCRIPTS...
      +- hosts
      |    \_ HOSTS...
      |         + runs.conf
      |         + sysinfos.conf
      |         + default
      |         \_ SCRIPTS...
      \_ DOMAINS...
           \_ HOSTS...
                + runs.conf
                + sysinfos.conf
                + default
                \_ SCRIPTS...

Le répertoire scripts contient les scripts généraux.

SCRIPTS correspondant aux fichiers de scripts, qui n'ont pas de contrainte sur
la façon de les nommer. HOSTS correspond aux répertoires d'hôtes, qui peuvent
contenir des fichiers de configuration ou d'autres scripts. DOMAINS correspond
aux domaines de hôtes pleinement qualifiés. Ces répertoire contiennent des
répertoires d'hôtes.

Le répertoire hosts contient des configuration pour des hôtes sans domaine. Les
hôtes pleinements qualifiés sont classés par domaine, puis par nom d'hôte. Par
exemple, si on cherche un script ou un fichier de configuration pour l'hôte
'medusa.univ.run', il sera d'abord cherché dans 'runsdir/univ.run/medusa' puis
dans 'runsdir/hosts/medusa'

Le fichier runs.conf contient des configuration qui sont partagées par tous les
scripts qui sont dans l'arborescence en-dessous. Ce fichier est au format CONF
(cf. ci-dessous).

Le fichier sysinfos.conf contient si nécessaire la configuration du système pour
l'hôte, pour les scripts qui doivent faire des préparations en local en fonction
du système distant. Ce fichier peut-être initialisé avec la configuration
affichée par le script usysinfos

Le fichier default contient la recette par défaut pour la configuration de
l'hôte. Il s'agit d'une suite de lignes de la forme:

    script [params]
      [params]
      ...

params correspond aux arguments de la fonction var. Chaque ligne indentée sous
le nom du script correspond à une invocation différente de var. Par exemple,
avec cette commande:

    script name=value arr0+=value0 arr1-=value1
        arr2 value21 value22

Le script 'script' est lancé avec la configuration de variable suivante:
name=value, rajouter value0 au tableau arr0, enlever value1 au tableau arr1, et
initialiser le tableau arr2 avec les valeur value21 et value22

Un script est composé de deux sections: CONF et SCRIPT, séparés par la ligne
'script:'. La forme d'un script est donc:

    CONF
    script:
    SCRIPT

Les deux sections sont écrites dans le langage de script bash.

Format de la section CONF
=========================

Dans cette section, les fonctions notamment disponibles sont: desc, conf, var,
out, ref, sysinfos

desc DESC
    Donner la description du script, à afficher avec 'runs --info'

conf flags...
    Activer certains flags. Les valeurs possible sont:
    root -- ce script requière d'être lancé avec l'utilisateur root
    local -- dans le cas d'un déploiement distant, ce script doit être lancé
        uniquement en local

after scriptpaths...
    Requérir que dans une même session, ce script soit lancé après tous les
    scripts mentionnés

after -r scriptpath [args...]
    Si le script spécifié a déjà été lancé dans la session en cours, ne rien
    faire. Sinon, lancer le script spécifié avec les arguments spécifiés avant
    de lancer le script en cours.

after -rr scriptpath [args...]
    Lancer de façon inconditionnelle le script spécifié avec les arguments
    spécifiés avant de lancer le script en cours.

var name=value
    Initialiser la variable name à la valeur value

var array+=value
    Ajouter la valeur value au tableau array

var array-=value
    Enlever la valeur value du tableau array

var array value0 value1... valueN
    Initialiser le tableau array avec la valeur (value0 value1...valueN)

out name[=file]
    Créer un fichier temporaire nommé file dans un espace partagé, et mettre son
    chemin absolu dans la variable name.

ref [-r] name[=file]
    Mettre dans la variable name le chemin absolu vers le fichier file, cherché
    d'abord dans le répertoire du script, puis dans le répertoire partagé, et
    enfin dans RUNSPATH. Si le fichier n'est trouvé nulle part, le chemin est
    relatif au répertoire partagé.
    Avec l'option -r, le fichier est requis: le script s'arrête si le fichier
    référencé n'est pas trouvé.

Format de la section SCRIPT
===========================

Cette section peut contenir n'importe quelle script. Par défaut, les librairies
DEFAULTS et runs sont chargées. Mais il est possible avec urequire de charger
d'autres librairies, notamment uinst ou uinc.

Les fonctions suivantes sont disponibles: shouldrun, setdone, resetdone.

shouldrun [subsystem [value]]
    Tester si le script (ou l'opération subsystem du script) doit être
    lancée. Tant que la fonction 'setdone' n'est pas lancée, cette fonction
    retourne vrai.

setdone [subsystem [value]]
    Spécifier que le script (ou l'opération subsystem du script) a été lancée
    correctement.

resetdone [subsystem]
    Réinitialiser les informations concernant l'état d'installation du script ou
    de l'opération subsystem du script.