Make installation files in Nullsoft NSIS

Create scripts for compilation in Nullsoft NSIS, a versatile installer creation tool.

Have you used freeware or open source installers before? Then we have good news: NSIS is nothing like any of them. You're not tied to a fixed order of doing things; there's complete flexibility over the interface, and you get support for advanced commands and installation options. And a tiny overhead of 34KB makes this the most compact installation builder anywhere. The downside? You build installers by writing scripts in a separate text editor.

NSIS is just a scripting engine and compiler (the website is here), so I would recommend you start by launching HM NIS Edit instead (the website is here). Initially, it'll seem like a fancier Notepad, but you'll see the difference by clicking File | New Script From Wizard.

First, you'll need to fill in a few application details (Name, Version and so on). Clicking 'Next' will prompt you to choose your setup language (there are nearly 50 available), but we recommend you accept the defaults for now.

The next screen is more problematic. It points NSIS to a licence file that your users will be asked to accept, but the default path and name is just for show: it doesn't exist. We'll make use of that, though, so leave the faulty setting in place and click 'Next'.

You'll need to decide which files this installer will actually install. Delete the examples – which also don't exist – then use the directory tree icon to point the wizard at the main folder containing your files. Don't worry if your application needs files installing elsewhere, we'll deal with that later.

The remaining screens deal with the creation of shortcuts, programs to run after installation is complete, and the use of an uninstaller. The default options here are well chosen, so feel free to accept them. Check the 'Save', 'Convert' and 'Compile' options on the 'Wizard finished' screen, then click 'Finish', and give your script a name to save it.

Script debugging

HM NIS Edit would normally pass your script off to NSIS for compilation, but this won't work, as I've left an invalid file reference. The compilation screen will show you which one it is by highlighting the Software Licence page line in red. The compiler message window also contains a tell-tale "Error in macro MUI_PAGE_LICENSE' error message."

Look above this error message for more detailed information: "LicenseData: open failed "......\path\to\licence\YourSoftwareLicence.txt'. Couldn't open that file." If you don't need this feature, then the time-honoured principle of 'remming it out' should be enough to get your script working: add a semicolon to the beginning of the line "!insertmacro MUI_PAGE_LICENSE...", and it will be greyed out. HM NIS Edit (and NSIS) will now treat the line as a comment and avoid processing it.

If you do have a software licence file you want to use, then change the default path. It's best to ensure that this should be relative to the installation folder, so use Licence.txt, if it's in the same folder, 'Licence\Licence.txt' if it's in an immediate subfolder, and so on. Click NSIS | Compile Script to see if you've cleared the error, or NSIS | Compile Script and ‘Run' to test the completed installer itself. This will also handle uninstall duties, for later.

Handling support files

This is a good start, but the installer may still be a little too simple for your needs. As we mentioned earlier, for instance, the program only installs a single directory tree. What if you need to copy support files elsewhere?

To see how this works, scroll down the script until you find the Section command. This command is used to group files together, so you could have a Basic section with core files and a Full section with the rest with the user allowed to choose between them.

Our change is even simpler. To save more files elsewhere, first point NSIS to that folder using a SetOutPath command. This can use a hard-coded path, but NSIS also provides useful constants: $PROGRAMFILES points at the program files folder, for instance, while $WINDIR points at the Windows folder. After this, tell NSIS which files you are going to copy, and it will install them for you. Add an EXEC command if there's a DLL file that needs to be registered, place the lines immediately before the SectionEnd command, and you'll have something like this:

SetOutPath "$SYSDIR" 
File "MyComponent.DLL"
Exec 'regsvr32.exe /s "$SYSDIR\MyComponent.DLL"'

The DLL will be copied to the Windows System folder, then registered through regsvr32.exe. The EXEC command is just one way of launching programs. You can also use ExecWait to run something instead and wait until it's finished – handy for displaying ReadMe files – or ExecShell to open the tools associated with the file type you're using. For instance, the default browser to display an HTML file.

System check

Being able to add runtime support files is useful, but what if you don't have to bundle them in every installer? It may be more efficient to have the set-up program check whether they are present on your user's system, and only download them if they are necessary. This is one possible method of doing this:

Section "-Install my runtime"
IfFileExists "$INSTDIR\MyApp.exe" 0 new_installation
StrCpy $ALREADY_INSTALLED 1
new_installation:
NSISdl::download http://mysite.com/myfile.dll $SYSDIR/myfile.dll 
SectionEnd

This custom section checks to see if our software is already installed by looking for a particular file and then jumps to the 'new_installation' label if it's true.

The installer will use the NSISdl plug-in to download the file we specify, and save it to the chosen location. Again, you could now register that file, or launch if it's an executable. This works just fine, but NSIS has a rich scripting language with many options.

If you need FTP download and better proxy support, for instance, then try the InetLoad plug-in (http://nsis.sourceforge.net/InetLoad). There's also a single InstallLib macro that will handle DLL installation and registration in one command (see the documentation that comes with the plug-in for more information).

Or if you prefer an easy life, check the NSIS website for help and other information. It already contains sample scripts to install the VB runtimes (http://nsis.sourceforge.net/Category:Tutorials), the .NET Framework as well as useful Data Access Components (http://nsis.sourceforge.net/Category:Code_Examples), giving you a great beginning for when you decide to build your own advanced installer utilities.

Subclass your installer

An NSIS installer fires particular events as it progresses. By adding callback functions to events you can alter how it works. For example, there's an .onGUIInit event, which is called before the first installer page appears: add a function here and you can customise the installer font, foreground and background colour, and much more. NSIS also provides an .onInstFailed event, which is called if the installer hasn't worked for some reason (always a good time to display a troubleshooting page). The dynamic events are most interesting, though, letting you directly modify the installer's logic through your own code. Here's an example:

Function .onVerifyInstDir 
IfFileExists $INSTDIR\ThisFile.exe PathBad
PathBad: 
Abort
FunctionEnd

The .onVerifyInstDir event is called whenever your user changes the installation folder. In this case, if we find a particular file there we jump to the PathBad label, and issue an Abort command, which tells NSIS to disallow this folder. There's even an onMouseOverSection event, called when the mouse moves over the installer sections tree. You could use this to display a custom description for sections. We don't have the space to explain everything you could do with these events (that would fill an entire feature on its own), but there's plenty of documentation on the NSIS site. Browse the Callback Functions section at http://nsis.sourceforge.net/Docs/Chapter4.html to find out more and see other examples.

---

Posted on Utopian.io - Rewarding Open Source Contributors

---