From 0ea09f0dcf0d7af0ec77d9c3fccafcb2a27f191d Mon Sep 17 00:00:00 2001 From: Doug Le Tough Date: Fri, 21 Jul 2017 12:00:45 +0200 Subject: [PATCH] "Conversion README en markdown" --- README.md | 427 +++++++++++++++++++++++++++--------------------------- 1 file changed, 215 insertions(+), 212 deletions(-) diff --git a/README.md b/README.md index 9079a3d..27c9b7d 100755 --- a/README.md +++ b/README.md @@ -39,21 +39,21 @@ en découlent. Sous l'arborescence ${NC_EXPL_ROOT} on trouve les dossiers suivants : -+-----------------+-----------------------------------------------------------------------------------------------+ -| Dossier | Description | -+-----------------+-----------------------------------------------------------------------------------------------+ -| {Racine}/bin | Contient les binaires (scripts Bash) | -| {Racine}/conf | Contient les fichiers de configuration des scripts, ainsi que du socle | -| {Racine}/cpt | Contient les fichiers de comtpe-rendus génerés par les script (purge auto, 8 jours par défaut)| -| {Racine}/dat | Contient les fichiers de données gérés par les scripts | -| {Racine}/hist | Contient l'historique d'exécution des scripts (pas de purge) | -| {Racine}/lib | Contient les bibliothèques chargées par le socle | -| {Racine}/log | Contient les fichiers de logs d exécution des scripts (purge auto , 8 jours par défaut ) | -| {Racine}/man | Contient les fichiers d'aide des scripts pour l'utilitaire "man" | -| {Racine}/mod | Contient les fichiers modèles (templates) à usage des scripts | -| {Racine}/msg | Contient les fichiers de messages des scripts utilisés par la bibliothèque "fct_erreur" | -| {Racine}/tmp | Contient les fichiers temporaires des scripts | -+-----------------+-----------------------------------------------------------------------------------------------+ + +-----------------+-----------------------------------------------------------------------------------------------+ + | Dossier | Description | + +-----------------+-----------------------------------------------------------------------------------------------+ + | {Racine}/bin | Contient les binaires (scripts Bash) | + | {Racine}/conf | Contient les fichiers de configuration des scripts, ainsi que du socle | + | {Racine}/cpt | Contient les fichiers de comtpe-rendus génerés par les script (purge auto, 8 jours par défaut)| + | {Racine}/dat | Contient les fichiers de données gérés par les scripts | + | {Racine}/hist | Contient l'historique d'exécution des scripts (pas de purge) | + | {Racine}/lib | Contient les bibliothèques chargées par le socle | + | {Racine}/log | Contient les fichiers de logs d exécution des scripts (purge auto , 8 jours par défaut ) | + | {Racine}/man | Contient les fichiers d'aide des scripts pour l'utilitaire "man" | + | {Racine}/mod | Contient les fichiers modèles (templates) à usage des scripts | + | {Racine}/msg | Contient les fichiers de messages des scripts utilisés par la bibliothèque "fct_erreur" | + | {Racine}/tmp | Contient les fichiers temporaires des scripts | + +-----------------+-----------------------------------------------------------------------------------------------+ Note : Sous chaque dossier vous trouverez un fichier texte lisezmoi.txt decrivant l'usage du répertoire. @@ -135,236 +135,239 @@ Remarque : Les variables SH_SILENCE et SH_NIV_DEBUG sont controlées par les opt si la gestion des options a été activée. -III - Utilisation du socle bash - ------------------------- +## III - Utilisation du socle bash - Cette partie decrit sommairmement les quelques regles d usage pour ecrire un script Bash sous le socle DTSI - Ceci ne concerne pas les script Ruby qui ne sont pas pris en charge par le socle decrit ici. +Cette partie decrit sommairmement les quelques regles d usage pour ecrire un script Bash sous le socle DTSI +Ceci ne concerne pas les script Ruby qui ne sont pas pris en charge par le socle decrit ici. + +### 1 - Cartouche + +Les scripts doivent commencer par le cartouche ci-dessous : + + +----------------------------------------------------------------------------------------------------+ + | | + | #!/bin/bash | + | ##---------------------------------------------------------------------------- | + | ## Script : | + | ## Module Puppet : | + | ## Auteur : | + | ## Date : | + | ## Version : | + | ## Objet : | + | ## | + | # ---------------------------------------------------------------------------- | + | # Mise a jour : | + | # - - : | + | # 0.0.1 08-06-2016 - Toto Laricot - Cre : Creation | + | # 0.0.2 08-09-2016 - Titi Alapeti - Ano : Ce truc est faux | + | # ---------------------------------------------------------------------------- | + | # Dependance : | + | # @DEP: : | + | # ---------------------------------------------------------------------------- | + | # Liste des options et arguments | + | # @OPT: ::::::: # | + | # @OPT: :... # | + | # @ARG: :::: # | + | ##---------------------------------------------------------------------------- | + | ## | + | ## Syntaxes : | + | ## -------- | + | ## | + | ## prompt> | + | ## | + | ## : | + | ## | + | ## Fonctionnement : | + | ## -------------- | + | ## | + | ## | + | ## | + | ##---------------------------------------------------------------------------- | + | . | + | . | + | . | + | | + +----------------------------------------------------------------------------------------------------+ - 1 - Cartouche - Les scripts doivent commencer par le cartouche ci-dessous : - +----------------------------------------------------------------------------------------------------+ - | | - | #!/bin/bash | - | ##---------------------------------------------------------------------------- | - | ## Script : | - | ## Module Puppet : | - | ## Auteur : | - | ## Date : | - | ## Version : | - | ## Objet : | - | ## | - | # ---------------------------------------------------------------------------- | - | # Mise a jour : | - | # - - : | - | # 0.0.1 08-06-2016 - Toto Laricot - Cre : Creation | - | # 0.0.2 08-09-2016 - Titi Alapeti - Ano : Ce truc est faux | - | # ---------------------------------------------------------------------------- | - | # Dependance : | - | # @DEP: : | - | # ---------------------------------------------------------------------------- | - | # Liste des options et arguments | - | # @OPT: ::::::: # | - | # @OPT: :... # | - | # @ARG: :::: # | - | ##---------------------------------------------------------------------------- | - | ## | - | ## Syntaxes : | - | ## -------- | - | ## | - | ## prompt> | - | ## | - | ## : | - | ## | - | ## Fonctionnement : | - | ## -------------- | - | ## | - | ## | - | ## | - | ##---------------------------------------------------------------------------- | - | . | - | . | - | . | - | | - +----------------------------------------------------------------------------------------------------+ - - Note : Les lignes commencant par 2 "#" sont utilisees pour generer l aide, leur maintient est donc necessaire - pour garantir la fiabilite de l information. Ce sont ces lignes, qui sont lues lors de l utilisation de - l'option par defaut "-h". +Note : Les lignes commençant par 2 "#" sont utilisees pour generer l'aide, leur maintient est donc nécéssaire +pour garantir la fiabilité de l'information. Ce sont ces lignes, qui sont lues lors de l'utilisation de +l'option par defaut "-h". - 1.1 Elements du cartouche - 1.1.1 Meta-donnees - - : peut prendre les valeurs suivantes -> cre, ano, evo, typo - cre : Creation du script. - evo : Evolution du script -> Ajout de nouvelles fonctionnalites, Amelioration du code. - ano : Correction du code suite a un comportement inattendu. - typo : Ajout de commentaires, de texte ou correction gramatical sans influence sur le code. - - - : - - - : Format x.y.z - Pour le suivie des versions on utilisera le versionnement semantique (voir paragraphe III-1.2). - - 1.1.2 Paragraphe - - Mise a jour : Ce paragraphe est utilise pour suivre l evolution des versions. La derniere version en - vigueur doit etre reportee dans le premier paragraphe. - - - Dependance : Permet de definir la liste ainsi que la version des scripts qui sont appeles. - Dans le cas d un changement cela permet de connaitre les scripts qui sont impactes. - Pour le moment aucun script n exploite cette meta-donnee. - Present pour un future usage. +### 1.1 Elements du cartouche - - Liste des options : La declaration des options n est pas obligatoire. - - Si aucune declaration n est presente alors la librairie params.lib ne fait aucune action. - Dans ce cas les options par defaut -h, -log, -hist, -cpt, -s et -dbg ne seront pas disponible. +#### 1.1.1 Meta-données - Si le script ne necessite pas d option mais que l on souhaite disposer des options par defaut, il - faudras declarer une option bidon. ex: "# @OPT: f:bidon::::::" + : peut prendre les valeurs suivantes -> cre, ano, evo, typo +* cre : Création du script. +* evo : Évolution du script -> Ajout de nouvelles fonctionnalités, Amélioration du code. +* ano : Correction du code suite à un comportement inattendu. +* typo : Ajout de commentaires, de texte ou corrections gramaticales sans influence sur le code. + + : - Si la declaration existe alors le socle gerera les parametres en entree du script, ainsi que - les options par defaut -h, -log, -hist, -cpt, -s et -dbg. Ces mots cle sont reserve et ne - peuvent pas etre utilise par le script. + : Format x.y.z +Pour le suivi des versions on utilisera le versionnement sémantique (voir paragraphe III-1.2). - La declaration est realise dans le paragraphe "Liste des options et arguments". Chaque - option est identifiee par l entete de ligne "# @OPT:" suivi de la description. - La description consiste en une liste de parametres separes par ":" - ::::::: - - L ordre des parametre est fige et tous doivent etre presents. - 8 champs sont obligatoires, soit 7 caracteres ":" (on ne compte pas le caracatere ":" suivant @OPT). - Exemple de declaration valide : - # @OPT: fb:h::0::: - # @OPT: fb:s::0::: - # @OPT: f:dbg:SH_NIV_DEBUG:0/1::: - # @OPT: fb:log::0::: - # @OPT: f:hist:SH_ARG_HIST:0/1:10:: - # @OPT: oM:i:G_INSTANCE:1/1:ALL:dbid: - # @OPT: oM:pr:G_PR_NOM:1/1:sq,t,l: +#### 1.1.2 Paragraphe - : Propriete de l attribu defini par l agregation des lettres suivantes - f -> Option falcultative - b -> Booleen - o -> Option obligatoire - M -> Argument transforme en majuscule +* Mise a jour : Ce paragraphe est utilisé pour suivre l'evolution des versions. La dernière version en +vigueur doit être reportée dans le premier paragraphe. - : nom de l option (sans le tiret) Attention le nom de l option est senssible a la casse. +* Dependance : Permêt de définir la liste ainsi que la version des scripts qui sont appelés. +Dans le cas d'un changement cela permêt de connaître les scripts qui sont impactés. +Pour le moment aucun script n'exploite cette méta-donnée qui est presente pour un future usage. - : nom de la variable dans laquelle sera stockee le(s) argument(s) - si plusieurs arguments alors un tableau sera initialise - L index [n] commence a zero. - Le nombre d arguments effectivement passes a la commande est "${#[*]}". - L valeur max de l index [n] est "${#[*]} - 1". +* Liste des options : La déclaration des options n'est pas obligatoire. + +Si aucune déclaration n'est présente alors la bibliothèque params.lib ne fait aucune action. +Dans ce cas les options par défaut -h, -log, -hist, -cpt, -s et -dbg ne seront pas disponible. - : nombre d arguments attendus de la forme "min/max", "min/", "max" ou "" - si vide ou "0" alors l option est booleene. - la forme "min/" considere le nombre max non determine (infini) +Si le script ne nécessite pas d'option mais que l'on souhaite disposer des options par défaut, il +faudra déclarer une option bidon. ex: "# @OPT: f:bidon::::::" - : Valeur par defaut assignee a - Fonctionne si vaut 0/1 1/1 +Si la déclaration existe alors le socle gèrera les paramètres en entrée du script, ainsi que +les options par défaut -h, -log, -hist, -cpt, -s et -dbg. Ces mots clé sont reservés et ne +peuvent pas être utilisé par le script. - : Liste des options mutellement exclusives separees par une virgule. +La déclaration est réalisée dans le paragraphe "Liste des options et arguments". Chaque +option est identifiée par l'entête de ligne "# @OPT:" suivi de la description. - : Liste des options inclusives separees par une virgule. +La description consiste en une liste de paramètres séparés par ":" + ::::::: + +L'ordre des paramètre est figé et tous doivent etre présents. - Lors de l initialisation les marqueurs "@OPT" sont lues et analysees. - Le resultat est compare aux arguments et options sousmis au script - et les variables suivantes son initialisees ... +8 champs sont obligatoires, soit 7 caracteres ":" (on ne compte pas le caracatere ":" suivant @OPT). +Exemple de déclaration valide : + # @OPT: fb:h::0::: + # @OPT: fb:s::0::: + # @OPT: f:dbg:SH_NIV_DEBUG:0/1::: + # @OPT: fb:log::0::: + # @OPT: f:hist:SH_ARG_HIST:0/1:10:: + # @OPT: oM:i:G_INSTANCE:1/1:ALL:dbid: + # @OPT: oM:pr:G_PR_NOM:1/1:sq,t,l: - - SH_OPTION_ : Initialisee a "1" (Vrai) ou "0" (Faux) selon que l option est respectivement utilise ou non. - Il existe toujours une variable par option declaree. Ceci concerne aussi les options par defaut - gere par la librairie params.lib - - SH_ARG_ : Cette variable existe uniquement si le champ est null et si le type n est pas booleen. - Par defaut elle est initialisee a null ou avec la valeur - Si le champ est renseigne, alors SH_ARG_ est remplacee pas . - Si l option associee peut prendre plusieurs arguments, alors les variables - SH_ARG_ ou sont des tableaux dont l index commence a zero. - La taille du tableau peut etre recuperee via ${#SH_ARG_[*]} ou ${#[*]}. +* : Propriété de l'attribu défini par l'aggrégation des lettres suivantes: + * f -> Option falcultative + * b -> Booléen + * o -> Option obligatoire + * M -> Argument transformé en majuscule - Les option -h, -s, -log [id], -hist [N] et -dbg N - sont prises en charge automatiquement. Ces noms sont donc reserves. +* : nom de l'option (sans le tiret). Attention le nom de l'option est sensible à la casse. - Les options par defaut realisent les actions suivantes : +* : nom de la variable dans laquelle sera stockée le(s) argument(s) +si plusieurs arguments alors un tableau sera initialisé +L'index [n] commence à zero. +Le nombre d'arguments éffectivement passés a la commande est "${#[*]}". +La valeur max de l'index [n] est "${#[*]} - 1". - -h : Affiche l aide du script (Ligne du cartouche qui commence par "##") - -s : Mode silence. Plus d'affichage sur le terminal. - Initialise la variable SH_SILENCE a "oui" - -log [id] : Affiche le dernier journal ou le journal "id" (identifiant de session d'execution). - -cpt [id] : Affiche le dernier compte-rendu ou le Compte-rendu "id" (identifiant de session d'execution). - -hist [N] : Affiche l historique des "N" dernieres executions (N=10 par dafaut) - -dbg N : Activation du mode debug au niveau "N". Active les messages geres par la librairie fct_message - dont l'option -debug est utilisee. +* : nombre d'arguments attendus de la forme "min/max", "min/", "max" ou "" +si vide ou "0" alors l'option est booléene. +la forme "min/" considere le nombre max non determiné (infini) - - Arguments : La declaration des argument du script n est pas obligatoire +* : Valeur par défaut assignée à +Fonctionne si vaut 0/1 1/1 - Attention : Si aucune option "@OPT:" n est declaree alors il n y auras pas de prise en charge des arguments. - Si votre script ne necessite pas d option, mais qu il presente des arguments, alors il faudras declarer - une option bidon :"# @OPT: f:bidon::::::" +* : Liste des options mutellement exclusives séparées par une virgule. - La declaration est realise dans le paragraphe "Liste des options et arguments". - Elle est identifiee par l entete de ligne "# @ARG:" suivi de la description. - Il ne peut y avoir qu une ligne de description pour les arguments. - (Si plusieurs lignes avec le marqueur @ARG existe, alors seul la premiere et prise en compte) +* : Liste des options inclusives séparées par une virgule. - La description consiste en une liste de parametres separes par ":" - :::: +Lors de l'initialisation les marqueurs "@OPT" sont lues et analysées. +Le résultat est comparé aux arguments et options sousmis au script +et les variables suivantes son initialisées ... - L ordre des parametres est fige et tous doivent etre presents. +* SH_OPTION_ : Initialisée à "1" (Vrai) ou "0" (Faux) selon que l'option est respectivement utilisée ou non. +Il existe toujours une variable par option déclarée. Ceci concerne aussi les options par défaut géré par la bibliothèque params.lib - : Propriete de l attribu defini par l agregation des lettres suivantes - f -> Argument falcultative - o -> Argument obligatoire - M -> Argument transforme en majuscule +* SH_ARG_ : Cette variable existe uniquement si le champ est null et si le type n'est pas booleen. +Par défaut elle est initialisée à null ou avec la valeur +Si le champ est renseigné, alors SH_ARG_ est remplacée pas . +Si l'option associée peut prendre plusieurs arguments, alors les variables SH_ARG_ ou sont des tableaux dont l'index commence a zéro. +La taille du tableau peut etre récuperée via ${#SH_ARG_[*]} ou ${#[*]}. - : nom de la variable dans laquelle sera stockee le(s) argument(s) - si plusieurs arguments alors un tableau sera initialise - L index [n] commence a zero. - Le nombre d arguments effectivement passes a la commande est "${#[*]}". - L valeur max de l index [n] est "${#[*]} - 1". +Les option -h, -s, -log [id], -hist [N] et -dbg N sont prises en charge automatiquement. Ces noms sont donc reservées. - Si n est pas renseigne alors la variable SH_ARGS[] est initialisee +Les options par défaut réalisent les actions suivantes : - : nombre d arguments attendus de la forme "min/max", "min/", "max" ou "". - si vide alors on considere que le nombre d arguments est a minima de 1. - la forme "min/" considere le nombre est a minima de "min". + -h : Affiche l aide du script (Ligne du cartouche qui commence par "##") + -s : Mode silence. Plus d'affichage sur le terminal. + Initialise la variable SH_SILENCE a "oui" + -log [id] : Affiche le dernier journal ou le journal "id" (identifiant de session d'execution). + -cpt [id] : Affiche le dernier compte-rendu ou le Compte-rendu "id" (identifiant de session d'execution). + -hist [N] : Affiche l historique des "N" dernieres executions (N=10 par dafaut) + -dbg N : Activation du mode debug au niveau "N". Active les messages geres par la librairie fct_message + dont l'option -debug est utilisee. - : Valeur par defaut assignee a - Fonctionne si vaut 0/1 1/1 - - ATTENTION - Si le caractere "&" est present dans la valeur d un argument, alors cette valeur doit etre encadree - par une simple cote et le caractere "&" doit etre proteger par un anti-slash "\". +- Arguments : La declaration des argument du script n est pas obligatoire - Le cas echeans le shell generera un fils qui tentera l execution d'un script portant le nom de la valeur de l argument. + Attention : Si aucune option "@OPT:" n est declaree alors il n y auras pas de prise en charge des arguments. + Si votre script ne necessite pas d option, mais qu il presente des arguments, alors il faudras declarer + une option bidon :"# @OPT: f:bidon::::::" - 1.2 Versionnement semantique - 1.2.1 Usage - L idee de l utilisation du versionnement semantique est de definir clairement les intentions - d un changement dans un code pour les clients de ce dernier. Ceci permet de fiabiliser la mise en - place de dependances et de determiner les impacts d un changement. - - 1.2.2 Format - Le format utilise est le suivant x.y.z - x est l identifiant de version majeure. - y est l identifiant de version mineure. - z est l identifiant de version de correction. - - 1.2.3 Semantique - - Version majeure X : Il vaut "0" lors du developpement, le script est considere non valide et ne - devrait pas etre appele par d autre script. Une fois le script valide la version - doit etre 1.0.0 (premiere version stable). - Il doit etre incremente si des changements dans le code n assure plus la compatibilite - ascendante. Les identifiants de version mineure et de correction doivent etre remis - a zero quand l identifiant de version majeure est incremente. + La declaration est realise dans le paragraphe "Liste des options et arguments". + Elle est identifiee par l entete de ligne "# @ARG:" suivi de la description. + Il ne peut y avoir qu une ligne de description pour les arguments. + (Si plusieurs lignes avec le marqueur @ARG existe, alors seul la premiere et prise en compte) - - Version mineur y : Doit etre incremente lors de l ajout de nouvelle fonctionnalite ou d amelioration - du code qui n on t pas d impact sur la compatibilite ascendante. L identifiant de - version de correction doit être remis a zero lorsque l identifiant de version mineure - est incremente. + La description consiste en une liste de parametres separes par ":" + :::: - - Version de correction z : Doit être incremente si seules des corrections retro-compatibles sont introduites. - Une correction est definie comme un changement interne qui corrige un comportement incorrect. - Il peut etre incremente lors de correction typographique ou grammaticale. + L ordre des parametres est fige et tous doivent etre presents. + + : Propriete de l attribu defini par l agregation des lettres suivantes + f -> Argument falcultative + o -> Argument obligatoire + M -> Argument transforme en majuscule + + : nom de la variable dans laquelle sera stockee le(s) argument(s) + si plusieurs arguments alors un tableau sera initialise + L index [n] commence a zero. + Le nombre d arguments effectivement passes a la commande est "${#[*]}". + L valeur max de l index [n] est "${#[*]} - 1". + + Si n est pas renseigne alors la variable SH_ARGS[] est initialisee + + : nombre d arguments attendus de la forme "min/max", "min/", "max" ou "". + si vide alors on considere que le nombre d arguments est a minima de 1. + la forme "min/" considere le nombre est a minima de "min". + + : Valeur par defaut assignee a + Fonctionne si vaut 0/1 1/1 + +ATTENTION + Si le caractere "&" est present dans la valeur d un argument, alors cette valeur doit etre encadree + par une simple cote et le caractere "&" doit etre proteger par un anti-slash "\". + + Le cas echeans le shell generera un fils qui tentera l execution d'un script portant le nom de la valeur de l argument. + +1.2 Versionnement semantique + 1.2.1 Usage + L idee de l utilisation du versionnement semantique est de definir clairement les intentions + d un changement dans un code pour les clients de ce dernier. Ceci permet de fiabiliser la mise en + place de dependances et de determiner les impacts d un changement. + + 1.2.2 Format + Le format utilise est le suivant x.y.z + x est l identifiant de version majeure. + y est l identifiant de version mineure. + z est l identifiant de version de correction. + + 1.2.3 Semantique + - Version majeure X : Il vaut "0" lors du developpement, le script est considere non valide et ne + devrait pas etre appele par d autre script. Une fois le script valide la version + doit etre 1.0.0 (premiere version stable). + Il doit etre incremente si des changements dans le code n assure plus la compatibilite + ascendante. Les identifiants de version mineure et de correction doivent etre remis + a zero quand l identifiant de version majeure est incremente. + + - Version mineur y : Doit etre incremente lors de l ajout de nouvelle fonctionnalite ou d amelioration + du code qui n on t pas d impact sur la compatibilite ascendante. L identifiant de + version de correction doit être remis a zero lorsque l identifiant de version mineure + est incremente. + + - Version de correction z : Doit être incremente si seules des corrections retro-compatibles sont introduites. + Une correction est definie comme un changement interne qui corrige un comportement incorrect. + Il peut etre incremente lors de correction typographique ou grammaticale. 2 - Initialisation du socle.