Structure de script

2.3 Structure de script

Un script NSIS peut contenir des Attributs d'Installation et des Sections/Fonctions. Vous pouvez également utiliser les Commandes de Compilation pour des opérations de compilation conditionnelle. La structure minimale d'un script est OutFile, qui indique à NSIS où écrire l'installation, ainsi qu'une section.

2.3.1 Attributs de l'Installation

Les Attributs de l'Installation déterminent le comportement et l'apparence de votre installation. Avec ces attributs vous pouvez définir quelles pages seront montrées et dans quel ordre, les textes qui seront affichés durant l'installation, le nombre de types d'installation. La plupart de ces commandes peuvent uniquement être initialisées et ne sont pas changeables durant l'exécution.

Les attributs les plus basiques sont Name, InstallDir et DirText.

Pour plus d'information sur les attributs d'installations, regarder Attributs d'Installation.

2.3.2 Pages

Un installateur non-silencieux a plusieurs pages d'assistant pour que l'utilisateur configure l'installation. Vous pouvez définir quelles pages afficher avec la commande Page (ou PageEx pour les paramètres plus avancés). Un set de page typique ressemble à cela:

Page license
Page components
Page directory
Page instfiles
UninstPage uninstConfirm
UninstPage instfiles

Pour l'installateur, ce set de pages typique affichera un contrat de licence, permet la sélection de composants à installer, permet la sélection d'un répertoire d'installation, et finalement installe les composants sélectionnés dans la page instfiles. Pour le désinstallateur, il affichera une page de confirmation, et désinstallera dans la page instfiles.

2.3.3 Les Sections

Dans une installation commune il y a plusieurs choses que l'utilisateur peut installer. Par exemple, dans la distribution de l'installation NSIS, vous pouvez choisir d'installer le code source, des plug-ins supplémentaires, des exemples, ainsi que d'autres composants. Chacun d'eux a sa propre part de code. Si l'utilisateur choisit d'installer ces composants, alors l'installation exécutera ce code. Dans le script, ce code se trouve dans les sections. Chaque section corespond à un composant de la page des composants. Le nom de section est le nom de composant affiché, et le code de section sera exécuté si ce composant est sélectionné. Il est possible de construire votre installation avec une seule section, mais si vous voulez utiliser la page de sélection des composants et laisser l'utilisateur choisir ce qu'il veut installer, vous aurez besoin de plus d'une section.

Les désinstallateurs peuvent avoir plusieurs sections. Les sections de désinstallation sont préfixées avec 'un.'. Par exemple:

Section "Installer Section"
SectionEnd

Section "un.Uninstaller Section"
SectionEnd

Les instructions qui peuvent être utilisées dans les sections sont très différentes des instructions des attributs d'installations, elles s'exécutent sur l'ordinateur de l'utilisateur. Ces instructions peuvent extraire des fichiers, lire et écrire dans les registres, des fichiers INI ou des fichiers normaux, créer des répertoires, créer des raccourcis et plus encore. Vous pouvez en savoir plus dans le chapitre Instructions.

Les instructions de bases sont SetOutPath qui indique à l'installation où extraire les fichiers et File qui extrait les fichiers.

Exemple:

Section "Mon Programme"
  SetOutPath $INSTDIR
  File "Mon Programme.exe"
  File "Readme.txt"
SectionEnd

Pour plus d'informations sur les sections voir Sections.

2.3.4 Les Fonctions

Les fonctions, comme les sections, peuvent contenir du code. La différence entre les sections et les fonctions est la manière dont elles sont invoquées. Il y a deux types de fonctions, les fonctions utilisateur et les fonctions d'interaction.

Les fonctions utilisateur sont appelées par l'utilisateur depuis les sections ou d'autres fonctions utilisant l'instruction Call. Les fonctions ne seront exécutées que lorsqu'elles seront appelées. Une fois le code de la fonction exécuté l'installation continuera d'exécuter les instructions qui succède à l'instruction Call, à moins que vous n'abandonniez l'installation depuis la fonction. Les fonctions utilisateurs sont très utiles si vous disposez d'un jeu d'instructions qui a besoin d'être déclenché à différents moments de l'installation. Si vous mettez le code dans des fonctions vous pouvez améliorer le temps d'installation et ainsi maintenir le code plus facilement.

Les fonctions d'interaction sont appelées par l'installation une fois qu'un événement prédéfini se produit comme quand l'installation se lance. Les fonctions d'interaction sont optionnelles. Si par exemple vous voulez accueillir l'utilisateur avec votre installation vous définirez une fonction appelée .onInit. Le compilateur NSIS reconnaîtra cette fonction en tant que fonction d'interaction grâce à son nom et l'appellera quand l'installation se lancera.

Function .onInit
  MessageBox MB_YESNO "Ceci va installer Mon Programme. Voulez-vous continuer ?" IDYES gogogo
    Abort
  gogogo:
FunctionEnd

Abort a un sens spécial dans les fonctions d'interaction. Chaque fonction d'interaction en défini un sens propre, regardez les Fonctions d'interaction pour plus d'information. Dans l'exemple ci-dessus Abort demande à l'installation d'arrêter l'initialisation de l'installation et sort immédiatement.

Pour plus d'informations voir Les Fonctions.

2.3.5 Travailler avec les scripts

2.3.5.1 Structures de Code Logiques

L'exécution conditionnelle de code, ou l'exécution de code dans une boucle peut être réalisée avec StrCmp, IntCmp, IfErrors, Goto et plus encore. Même si il existe un moyen plus simple pour le faire. La LogicLib fourni certaines macros très simples qui permettent la contruction sans difficulté de structures logiques complexes. Sa syntaxe, expliquée dans LogicLib.nsh, est similaire aux autres langages de programmation et peut s'avérer plus simple pour les débutants comme pour les utilisateurs avancés.

Par exemple, vérifier la valeur d'une variable sans LogicLib peut être fait comme suit.

StrCmp $0 'une valeur' 0 +3
  MessageBox MB_OK '$$0 est une valeur'
  Goto done
StrCmp $0 'une autre valeur' 0 +3
  MessageBox MB_OK '$$0 est une autre valeur'
  Goto done
# else
  MessageBox MB_OK '$$0 est "$0"'
done:

Mais, avec LogicLib, le code devient plus lisible et simple à comprendre, comme on peut le voir dans l'exemple suivant.

${If} $0 == 'une valeur'
  MessageBox MB_OK '$$0 est une valeur'
${ElseIf} $0 == 'une autre valeur'
  MessageBox MB_OK '$$0 est une autre valeur'
${Else}
  MessageBox MB_OK '$$0 est "$0"'
${EndIf}

La même chose peut être faite avec un switch, comme montré dans l'exemple suivant.

${Switch} $0
  ${Case} 'une valeur'
    MessageBox MB_OK '$$0 est une valeur'
    ${Break}
  ${Case} 'une autre valeur'
    MessageBox MB_OK '$$0 est une autre valeur'
    ${Break}
  ${Default}
    MessageBox MB_OK '$$0 est "$0"'
    ${Break}
${EndSwitch}

Plusieurs conditions sont aussi supportées. L'exemple suivant avertira l'utilisateur, si $0 et $1 sont vides.

${If} $0 == ''
${AndIf} $1 == ''
  MessageBox MB_OK|MB_ICONSTOP 'les deux sont vides!'
${EndIf}

LogicLib supprime le besoin de labels et de sauts relatifs, prévient les conflits de noms de labels, et supprime lebesoin d'ajouster manuellement les offsets de sauts relatifs à chaque fois que le script est modifié.

Cela simplifie aussi le bouclage, en supportant les boucles communes while, do et for. Tous les exempels suivants utilisent LogicLib.

StrCpy $R1 0
${While} $R1 < 5
  IntOp $R1 $R1 + 1
  DetailPrint $R1
${EndWhile}

${For} $R1 1 5
  DetailPrint $R1
${Next}

StrCpy $R1 0
${Do}
  IntOp $R1 $R1 + 1
  DetailPrint $R1
${LoopUntil} $R1 >= 5

Pour utiliser LogicLib, la ligne suivante doit être rajoutée en haut du script.

!include LogicLib.nsh

Plus d'exemples peuvent être trouvés dans LogicLib.nsi.

2.3.5.2 Les variables

Vous pouvez déclarer vos propres variables ($VARNAME) avec la commande Var. Les variables sont globales et peuvent être utilisées dans n'importe quelle section ou Fonction.

Déclarer et utiliser les variables utilisateur:

Var BLA ; Déclare la variable

Section bla

  StrCpy $BLA "123" ; vous pouvez maintenant utiliser la variable $BLA

SectionEnd

En plus il y a une Pile, qui peut aussi servir de stockage temporaire. Pour accéder à la pile utilisez les commandes Push et Pop. Push ajoute une valeur à la pile, Pop en enlève une et fixe la variable. Par exemple, la valeur de $0 est 123.

Pour le code partagé, il y a 20 registres disponibles (comme $0 et $R0). Ces variables statiques n'ont pas à être déclarées et vous n'obtiendrez pas de conflit de nom. Si vous voulez utiliser ces variables dans du code partagé, stocker les valeurs originales de la pile et restaurer les valeurs originales ensuite.

Après avoir appelé la fonction, la variable contient la même valeur qu'avant. Notez l'ordre quand vous manipulez de multiples variables (last-in first-out):

Function bla

  Push $0
 Push $1

    ...code...

 Pop $1
 Pop $0

FunctionEnd

2.3.5.3 Debuguer les Scripts

Plus vous travaillerez avec NSIS plus vos scripts deviendront complexe. Le risque de faire des erreurs est alors accru, particulièrement lorsque vous manipuler des variables. Il y a peu de possibilités pour vous aider à débugger votre code. Pour afficher le contenu des variables vous devrez utilisez les MessageBoxes ou DetailPrint. Pour avoir un bref aperçu de toutes les variables vous devrez utiliser le plug-in Dumpstate. Par défaut, toutes les actions de l'Installation sont affichées sur la fenêtre de journalisation. Vous pouvez accéder au log si vous cliquez-droit sur la fenêtre de journalisation et sélectionner "Copier les détails dans le presse papier". Il y a aussi la possibilité d'écrire directement dans un fichier. Voir ici. Très utile si vous forcez l'installation à se fermer tout seul utilisant SetAutoClose.

2.3.6 Exécution du script

Quand un utilisateur lance un installateur ou un désinstallateur, les pages sont affichées dans l'ordre défini dans le script. Si la page instfiles est atteinte, les sections, correspondant aux composants sélectionnés, sont exécutés dans l'ordre défini dans le script. Si la page des composants n'est pas affichée, toutes les sections sont exécutées, en assumant qu'elle n'ont pas été désélectionnées ou d'une certaine façon désactivées dans le script.

A côté du code dans les sections, il y a aussi du code dans les fontions d'interaction. Si définies, elles peuvent être exécutées avant le code des sections. Par exemple, la fonction d'interaction .onInit est exécutée avant tout autre chose du script. Il y a aussi les fonctions d'interaction de page qui sont exécutées à certains points du processu d'affichage des la page.

2.3.7 Commandes de Compilation

Les commandes de compilation seront exécutées au moment de la compilation sur votre ordinateur. Elles peuvent utilisées pour faire de la compilation conditionnelle, pour inclure des fichiers, pour exécuter des applications, pour changer de répertoire en cours de travail et plus. L'usage le plus commun est le define. Les Defines sont des constantes de compilation à la volée. Vous pouvez définir le numéro de version de votre produit et l'utiliser dans le script. Par exemple:

!define VERSION "1.0.3"
Name "Mon Programme ${VERSION}"
OutFile "Mon Programme d'Installation - ${VERSION}.exe"

Pour plus d'information sur les defines voir Compilation Conditionnelle.

Une autre utilisation commune est les macros. Les macros sont utilisées pour rajouter du code au moment de la compilation, dépendant des defines et utilisant donc les valeurs de ces defines. Les commandes de macros sont insérées au moment de la compilation. Cela vous permet d'écrire du code une seule fois et de les utiliser de nombreuses fois avec des changements mineurs. Par exemple:

!macro MyFunc UN
Function ${UN}MyFunc
  Call ${UN}DoRegStuff
  ReadRegStr $0 HKLM Software\MyProgram key
  DetailPrint $0
FunctionEnd

!insertmacro MyFunc ""
!insertmacro MyFunc "un."

Cette macro vous évite d'écrire le même code pour l'installation et la désinstallation. Les deux !insertmacros insèrent deux fonctions, une pour l'installation appelé MyFunc et une pour la désinstallation appelé un.MyFunc et les deux font exactement la même chose.

Pour plus d'information voir les commandes de compilation à la volée.

Précédent | Sommaire | Suivant