CSC375 Postimplementation issues

NSIS example

Here we'll look at some sample code and issues for creating installers and uninstallers - in this case targeting Windows systems and using the NSIS (Nullsoft Scriptable Install System) installer software. This is an open source system, and details are available at nsis.sourceforge.net

Here we assume the user downloads the installer executable, and then runs that installer to set up the rest of the system and files.

Some of the things we will look at include:

Setting a default installation path, but giving the user the option to install elsewhere.
Backing up old versions of files that the installer would otherwise overwrite.
Establishing a typical uninstaller, that removes the files we have added, and restores the older files that we backed up.

NSIS, like many other tools, requires the developer to write a script that lists the files to be included, the settings to be changed, the messages and options to be presented to the user, the compression technique to be used, etc.

The NSIS software is then run, using the developer's script to build the installer that can then be downloaded by the user.

Note that this version is pretty simplistic. Some of the things it fails to do are noted below:

This does not uninstall completely. Due to the way backup/restores of old files are performed here, the uninstaller can potentially leave two empty directories after an uninstall: the installation directory itself, and a bin subdirectory.
This does not account for other programs sharing the files, we simply assume restoring the original versions after and uninstall is "good enough".


; MyInstaller.nsi 
; 
; This script installs the MySoftWarePackage and uninstaller. 
; It will install into a directory that the user selects. 
 
;-------------------------------- 
 
; The name of the installer 
Name "MyInstaller" 
 
; The file to write 
OutFile "MyInstaller.exe" 
 
; The default installation directory 
InstallDir "C:\Program Files\MySoftWarePackage"
 
; Registry key to check for directory (so if you install again, it will  
; overwrite the old one automatically) 
InstallDirRegKey HKLM "Software\MySoftWarePackage" "Install_Dir" 
 
;-------------------------------- 
 
; Pages 
;
; This lists the pages that will be shown to the user when
;    they run the install/uninstall wizards
;
; In this example, install the wizard offers the user the following:
;    a components page (select which components to install)
;    a directory page  (select the installation directory)
;    an install page (shown while the installation runs)
Page components 
Page directory 
Page instfiles 
 
; The uninstall wizard shows the user a confirmation page
;     (checking if they really want to uninstall)
;     then an install page (shown while the uninstaller runs)
UninstPage uninstConfirm 
UninstPage instfiles 
 
;-------------------------------- 
 
; The stuff to install 
;
;     the Section and SectionEnd commands are used as delimiters
;     to subdivide an installer/uninstaller into discrete segments
Section "MySoftWarePackage (required)" 
 
  SectionIn RO 
   
  ; Set output path to the user's target installation directory. 
  SetOutPath $INSTDIR 
   
  ; Write the installation path into the registry 
  WriteRegStr HKLM SOFTWARE\MySoftWarePackage "Install_Dir" "$INSTDIR" 
 
  ; Create any needed backup directories within the installation directory
  CreateDirectory $INSTDIR\Backup_MySoftwarePackage
  CreateDirectory $INSTDIR\Backup_MySoftwarePackage\bin

  ; Move existing files (that will get overwritten)
  ;    to the backup directory
  Rename $INSTDIR\whatever.cfg $INSTDIR\Backup_MySoftwarePackage\whatever.cfg
  Rename $INSTDIR\whatever.ini $INSTDIR\Backup_MySoftwarePackage\whatever.ini
  Rename $INSTDIR\Readme.txt $INSTDIR\Backup_MySoftwarePackage\Readme.txt
  Rename $INSTDIR\bin\MySoftware.exe $INSTDIR\Backup_MySoftwarePackage\bin\MySoftware.exe
  Rename $INSTDIR\bin\MySoftwareConfig.exe $INSTDIR\Backup_MySoftwarePackage\bin\MySoftwareConfig.exe
  
  ; List the files to include in that install directory,
  ; specifying their location on the developer's machine so the
  ;     NSIS software can find them when creating the installer
  File "C:\Projects\MySoftWarePackage\whatever.cfg" 
  File "C:\Projects\MySoftWarePackage\whatever.ini" 
  File "C:\Projects\MySoftWarePackage\Readme.txt"

  ; you can specify new target subdirectories within the
  ;     user's chosen install directory
  SetOutPath $INSTDIR\bin 
  File "C:\Projects\MySoftWarePackage\MySoftWare.exe"
  File "C:\Projects\MySoftWarePackage\MySoftWareConfig.exe"
   
  ; Write the uninstall keys for Windows 
  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MySoftWarePackage" "DisplayName" "MySoftWarePackage" 
  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MySoftWarePackage" "UninstallString" '"$INSTDIR\uninstall_MySoftWarePackage.exe"' 
  WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MySoftWarePackage" "NoModify" 1 
  WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MySoftWarePackage" "NoRepair" 1 
  WriteUninstaller "uninstall_MySoftWarePackage.exe" 
   
SectionEnd 
 
;-------------------------------- 
 
; Uninstaller 
 
Section "Uninstall MySoftWarePackage" 
   
  ; Remove registry keys 
  DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MySoftWarePackage" 
  DeleteRegKey HKLM SOFTWARE\MySoftWarePackage 
 
  ; Remove the newly installed files and the uninstaller executable
  Delete "$INSTDIR\whatever.cfg" 
  Delete "$INSTDIR\whatever.ini" 
  Delete "$INSTDIR\Readme.txt"
  Delete "$INSTDIR\bin\MySoftWare.exe"
  Delete "$INSTDIR\bin\MySoftWareConfig.exe"
  Delete "$INSTDIR\uninstall_MySoftWarePackage.exe" 
 
  ; Restore the backed up versions of the files
  Rename $INSTDIR\Backup_MySoftwarePackage\whatever.cfg $INSTDIR\whatever.cfg
  Rename $INSTDIR\Backup_MySoftwarePackage\whatever.ini $INSTDIR\whatever.ini
  Rename $INSTDIR\Backup_MySoftwarePackage\Readme.txt $INSTDIR\Readme.txt
  Rename $INSTDIR\Backup_MySoftwarePackage\bin\MySoftware.exe $INSTDIR\bin\MySoftware.exe
  Rename $INSTDIR\Backup_MySoftwarePackage\bin\MySoftwareConfig.exe $INSTDIR\bin\MySoftwareConfig.exe

  ; Remove the backup directory
  RMDir "$INSTDIR\Backups_MySoftwarePackage" 
 
SectionEnd

More about scripting with NSIS

The example above is a very basic one, and it is possible to script much more detailed installations.

See the NSIS documentation for more details, but some of the supported options include:

You can generate an informational message box (a pop up with some text and an ok button), e.g.
```
   MessageBox MB_OK 'Some message'
```

You can generate a yes/no message box, e.g.

   MessageBox MB_YESNO "Do you wish to continue?" IDYES somelabel
       ...here are the commands if they said no...
       Goto restofstuff
   somelabel:
       ...here are the commands if they said yes...
   restofstuff:

There are twenty pre-defined registers available for use as variables, named $0 - $9 and $R0 - $R9

There is a pre-defined stack you can save values to and pop values off of, e.g.

    Push $0  ; push the contents of register 0 onto the stack
    Pop  $0  ; pop the top stack value into register 0

You can declare your own variables and assign values (variables are global and use string values), e.g.:
```
Var BLAH

   StrCpy $BLAH "somevalue"
```

You can use simple if/else statements, e.g.:

$(If) $0 == 'somevalue'
      ...perform some action...
$(ElseIf) $0 == 'anothervalue'
      ...do something else...
$(Else)
      ...default action...

You can use Callback functions: these are functions with predefined names that are automatically executed by the installer under certain circumstances. For instance, the onInit function (if one has been defined) is automatically run when the installer begins. The callback functions include things like onInit, onGUIInit, onInstFailed, onInstSuccess, onGUIEnd, onUserAbort, etc. The example below gives the user a chance to quit the installer immediately:
```
Function .onInit
   MessageBox MB_YESNO "Do you wish to continue?" IDYES gogogo
      Abort
   gogogo:
FunctionEnd
```
You can write your own functions and call them using the Call command. Note that parameter passing isn't supported, so use the registers or your variables to pass data around. An example function declaration and call is shown below.
```
Function myfunctionname
    ...whatever commands...
FunctionEnd

... someplace else...
   Call myfunctionname
```
You can jump from point-to-point in the scripts using labels and goto statements, e.g.:
```
    ...
    Goto done
    ...
done:  
    ...
```