NSIS

Table of Contents

Features

MakeNSIS usage

NSIS installers are generated by using the 'MakeNSIS' program to compile a NSIS script (.NSI) into an installer executable. The syntax of the makensis command is: Note that the NSIS development kit installer may have set up your computer so that you can compile a .nsi file by simply right-clicking on it in explorer, and selecting 'compile'.

.NSI script format

A NSIS Script File (.nsi) is just a text file with a series of commands.

Installer attributes:

The commands below all adjust attributes of the installer. These attributes control how the installer looks and functions, including which pages are present in the installer, as what text is displayed in each part of each page, how the installer is named, what icon the installer uses, the default installation directory, what file it writes out, and more. Note that these attributes can be set anywhere in the file except in a Section or Function.
With the exception of InstallDir, none of these attributes allow use of Variables other than $\r and $\n in their strings.

Compiler flags:

The following commands change how the compiler generates code and compresses data.
These commands are valid anywhere in the script, and effect every line below where each one is placed (until overriden by another command).

Sections:

Each NSIS installer contains one or more Sections. Each These sections are created, modified, and ended with the following commands.

Functions:

Functions are like similar to Sections in that they contain zero or more instructions. Functions are not called by the installer directly, instead they are called from Sections using the Call instruction (Note: there are some special Callback Functions that can be called by the installer directly).
See also: Utility Functions (functions.htm).

Labels:

Labels are the targets of Goto instructions, or of the various branching instructions (such as IfErrors, MessageBox, IfFileExists, and StrCmp). Labels must be within a Section or a Function. Labels are local in scope, meaning they are only accessable from within the Section or Function that they reside in.
To declare a label, simply do:
MyLabel:
Labels cannot begin with a -, +, !, $, or 0-9. When specifying labels for the various instructions that require them, remember that both an empty string ("") and 0 both represent the next instruction (meaning no Goto will occur). Labels beginning with a period (.) are global, meaning you can jump to them from any function or section (though you cannot jump to an uninstall global label from the installer, and vice versa).

Instructions:

The instructions that NSIS uses for scripting are sort of a cross between PHP and assembly. There are no real high level language constructs, but the instructions themselves are (for the most part) high level, and you have handy string capability (i.e. you don't have to worry about concatenating strings, etc). You essentially have 22 registers (20 general purpose, 2 special purpose), and a stack.

Variables:

Uninstall section:

A special Section named 'Uninstall' must be created in order to generate an uninstaller. This section should remove all files, registry keys, etc that were installed by the installer, from the system. Here is an example of a simple uninstall section:
        Section "Uninstall"
          Delete $INSTDIR\Uninst.exe ; delete self (see explanation below why this works)
          Delete $INSTDIR\myApp.exe
          RMDir $INSTDIR
          DeleteRegKey HKLM SOFTWARE\myApp
        SectionEnd
The first Delete instruction works (deleting the uninstaller), because the uninstaller is transparently copied to the system temporary directory for the uninstall.

Callback functions:

You can create callback functions which have special names, that will be called by the installer at certain points in the install. Below is a list of currently available callbacks:

Compiler utility commands

These commands are similar to the C preprocessor in terms of purpose and functionality. They allow file inclusion, conditional compilation, executable header packing, and processes execution during the build process. Note: none of these commands allow use of variables.

Compiler defines/conditional compilation:

The compiler maintains a list of defined symbols, which can be defined using !define or the /D command line switch. These defined symbols can be used for conditional compilation (using !ifdef) or for symbol replacement (a simple form of macros). To replace a symbol with its value, use ${SYMBOL} (if SYMBOL is not defined, no translation will occur). The translation is first-come-first-served, meaning if you do:
        !define symbol1 ${symbol2}
if symbol2 is defined when that line occurs, it will be replaced. Otherwise, any replacing will occur when ${symbol1} is referenced.

Define/conditional compilation related commands:

Version history:

License:

 Copyright (C) 1999-2002 Nullsoft, Inc.

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
eof (that's end of file for all you people who don't get it).