Tutorial: Create a NSIS install script

Public Peace Section 9
The meat of the NSIS script is the section. Sections allow not only neat organisation of code, but cool things like user defined installable components. Sections are executed in order, unless their name begins with ‘un.’ or is ‘Uninstall’, in which case they are reserved for uninstall functions. Other special functions include prefixing the ‘-‘ symbol to the name (it will not appear in the component install screen and will be force installed), prefixing a ‘!’ (item is displayed in bold) and adding a /o immediately after Section (that section will be disabled by default in the component install screen).

Let’s take a look at our first section, MainSection. SetOutPath determines where the files within that section will be installed. This means rather than being restricted to the installation directory you entered earlier, you may deliver files within a section to custom directories – such as installing DLL files to the Windows System directory, or the desktop.

Files are added to the installation package by using the File instruction, followed by the location of the file on the local drive – as you can see, the Morris family is already here, as set up by our wizard. This is followed by the installation of shortcuts, and most importantly, the end of the section, funnily enough called SectionEnd.
So let’s give the user more options and move ‘MorrisJnr’ out of MainSection and into a new section, disable him by default and place him on the desktop.

Section /o “Extra”
  SetOutPath “$DESKTOP”
  SetOverwrite ifnewer
  File “C:\nsis\MorrisJnr.hint”
SectionEnd

Easy! Now if we compile and run (Shift+F9 – if you wish to just compile and not execute hit CTRL+F9), you’ll be able to see the installer in its current state, and that the user now has the option of installing ‘MorrisJnr’ or leaving well alone.

Often the user likes to know exactly what they’re installing, so lets add descriptions to our sections that will be displayed in the components page whenever the user mouses over the available options. Scroll down until you find the comment ; Section descriptions. Contained in this area are all the descriptions for our sections, formatted as so:

!insertmacro MUI_DESCRIPTION_TEXT ${Section Index} “Description goes here”

You’ll notice something similar already in the script. Scroll back up to MainSection – notice the SEC01 at the end? This is our Section Index and allows us to reference sections in order to add descriptions, among other things. So our final line for the MainSection description would look something like this:

!insertmacro MUI_DESCRIPTION_TEXT ${SEC01} “Installs Morris’ Main Package”

For completeness, add a SEC02 to the end of our Extra section and insert a description for it as well.

External Commands
So let’s say we compress Morris.txt into a 7z file. We don’t want to include the 7z file in the installer, but we do want to be able to extract it as part of the install process. How do we do this?
First, and most obviously, we either need the executable that performs the extraction in the same directory as the installer, or available somewhere on the local machine. In this case we need to include 7za.exe from the 7-zip compressor, and then to call it externally from the script. To do this, we use the exec command.

exec ‘”$EXEDIR\7za.exe” x “$EXEDIR\Morris.7z” -y -o”$DESKTOP”’

Note that the argument is contained within single quotes, and that NSIS symbols can be used. If we want the install progress to halt until the external process has terminated, we can use execwait instead of exec. Argh! But wait! Now we’ve got an ugly Command Prompt window that’s popping up, ruining our lovely install! Is there anyway to hide, or internalise it? Why yes, yes there is.

NSIS supports a plugin structure, much like WinAmp. One such plugin is NSEXEC – which will happily capture and display any command line output to the details box within the installer, hiding away all those ugly Command Prompt windows. To use, simply replace exec with nsexec::exectolog (which is in the format plugin::function, and how plugins are called from the script). If you don’t wish the output to be displayed, simply use the exec or exectostack functions instead of exectolog.

Message in a Box
Instead of force extracting Morris.7z, let’s give the user the option of inflating him through a message box.

Section -MorrisExtract
  MessageBox MB_YESNO “Do you wish to inflate Morris?” IDYES Extract IDNO End
  Extract: nsexec::exectolog ‘”$EXEDIR\7za.exe” x “$EXEDIR\Morris.7z” -y -o”$DESKTOP”’
  End:
SectionEnd

Here we’ve told NSIS not to display the section as an installable component by prefixing it with a ‘-‘, and then executed the MessageBox instruction with the function MB_YESNO, which will create a message box with Yes and No buttons. We have then included the question to appear in the box, and said that if the user clicks YES, go to subsection ‘Extract’ (and consequently, inflate Morris), but if the user clicks NO go to subsection ‘End’ (which has no commands, and then continues to SectionEnd). A subsection is simply defined by using the previously implemented name and following with a semicolon, as above.

That’ll Be the Reg, Reg
You can also add or delete registry keys straight from NSIS, using WriteRegStr, WriteRegEXPANDSTR, WriteRegDWORD, or WriteRegBin in the format:

WriteRegXXX Root_Key Sub_Key Key_Name Value

Let’s leave some evidence behind of our install. To write a string called ‘Morris’ to the ‘HKEY_LOCAL_MACHINE\Software\Morris’ key with the value ‘Is Really Moz’, it would be written as such:

WriteRegStr HKLM “Software\Morris” “Morris” “Is Really Moz”

You can also remove entire keys by using the DeleteRegKey instruction, or individual values by using DeleteRegValue, using the same format as above. For cleanliness, make sure to add a remove instruction to the uninstall section for any registry keys that you may have added along the way.

Customising
You can also customise the look of the installer. Since we’ve called macros for the modern UI here rather than coded our own calls, we’ll have to edit the Contrib\Modern UI\System.nsh (called by the script MUI.nsh) file rather than entering the arguments directly into the script, which would cause clashes. Browse down to line 100 to find the interface settings. Here you can change everything from the interface colours down to the image used for the sidebar (MUI_WELCOMEFINISHPAGE_BITMAP) – see the ModernUI Readme installed with the program for the complete details.

Uninstall!
There it is, an introduction to the magic of NSIS. The program is far deeper than the size of this article will allow, so now that you’ve got a feel for it, have a browse through the manual to see what you can do. Through its extensible plugin architecture you can do nifty things like display splash screens, download files from the internet through http and even binary patch existing files – all so your creation can be delivered in the best possible way. NullSoft. We love ‘em.

========EXTRA========
COMMON SYMBOLS

$PROGRAMFILES
Your Program Files directory. Usually C:\Program Files.
$COMMONFILES
The Common Files directory. Usually C:\Program Files\Common Files.
$TEMP
Your temp directory. Usually C:\Documents and Settings\Profile Name\Local Settings\Temp.
$DESKTOP
The current profile’s Desktop.
$SYSDIR
The system directory, usually C:\Windows\System32.
$EXEDIR
The directory that your installer executable is in.
$WINDIR
The Windows directory, usually C:\Windows.
$STARTMENU
The current profile’s Start menu directory. Used to add shortcuts to the top of the Start Menu.
$SMPROGRAMS
The current profile’s Programs menu directory, found under their Start Menu. Used to add shortcuts.
$SMSTARTUP
The current profile’s Startup directory, found under Start Menu>Programs. Add a shortcut here to launch programs when Windows starts.
$QUICKLAUNCH
The current profile’s Quick Launch Bar. Used to add shortcuts.
$INSTDIR
The install directory you’ve set.
${NSISDIR}
The NSIS directory. Usually used to include resources such as icons.
============================