A NSIS script can contain Installer Attributes and Sections/Functions. You can also use Compiler Commands for compile-time operations. Required is the OutFile instruction, which tells NSIS where to write the installer, and one section.
Installer Attributes determine the behavior and the look and feel of your installer. With these attributes you can change texts that will be shown during the installation, the number of installation types etc. Most of these commands can only be set and are not changeable during runtime.
Other basic instructions are Name and InstallDir.
For more information about installer attributes, have a look at Installer Attributes.
An non-silent installer has a set of wizard pages to let the user configure the installer. You can set which pages to display using the Page command (or PageEx for more advanced settings). A typical set of pages looks like this:
Page license Page components Page directory Page instfiles UninstPage uninstConfirm UninstPage instfiles
In a common installer there are several things the user can install. For example in the NSIS distribution installer you can choose to install the source code, additional plug-ins, examples and more. Each of these components has its own piece of code. If the user selects to install this component, then the installer will execute that code. In the script, that code is in sections. Each visible section is a component for the user to choose from. We will not discuss invisible sections in this tutorial. It is possible to build your installer with only one section, but if you want to use the components page and let the user choose what to install you'll have to use more than one section.
Uninstallers can also have multiple sections. Uninstaller section names are prefixed with 'un.'. For example:
Section "Installer Section" SectionEnd Section "un.Uninstaller Section" SectionEnd
The instructions that can be used in sections are very different from the installer attributes instructions, they are executed at runtime on the user's computer. Those instructions can extract files, read from and write to the registry, INI files or normal files, create directories, create shortcuts and a lot more. You can find out more in Instructions.
The most basic instructions are SetOutPath which tells the installer where to extract files and File which extracts files.
Example:
Section "My Program" SetOutPath $INSTDIR File "My Program.exe" File "Readme.txt" SectionEnd
For more information about sections see Sections.
Functions can contain script code, just like sections. The difference between sections and functions is the way they are called. There are two types of functions, user functions and callback functions.
User functions are called by the user from within sections or other functions using the Call instruction. User functions will not execute unless you call them. After the code of the function will be executed the installer will continue executing the instructions that came after the Call instruction, unless you have aborted the installation inside the function. User functions are very useful if you have a set of instructions that need to be executed at several locations in the installers. If you put the code into a function you can save the copying time and you can maintain the code more easily.
Callback functions are called by the installer upon certain defined events such as when the installer starts. Callbacks are optional. If for example you want to welcome the user to your installer you will define a function called .onInit. The NSIS compiler will recognize this function as a callback function by the name and will call it when the installer starts.
Function .onInit
MessageBox MB_YESNO "This will install My Program. Do you wish to continue?" IDYES gogogo
Abort
gogogo:
FunctionEnd
Abort has a special meaning in callback functions. Each callback function has its own meaning for it, have a look at Callback Functions for more information. In the above example Abort tells the installer to stop initializing the installer and quit immediately.
For more information about functions see Functions.
You can declare your own variables ($VARNAME) with the Var command. Variables are global and can be used in any Section or Function.
Declaring and using a user variable:
Var BLA ;Declare the variable Section bla StrCpy $BLA "123" ;Now you can use the variable $BLA SectionEnd
In addition there is a Stack, which can also be used for temporary storage. To access the stack use the commands Push and Pop. Push adds a value to the stack, Pop removes one and sets the variable.
For shared code, there are 20 registers avaibable (like $0 and $R0). These static variables don't have to be declared and you won't get any name conflicts. If you want to use these variables in shared code, store the original values on the stack and restore the original values afterwards.
After calling the function, the variables contain the same value as before. Note the order when using multiple variables (last-in first-out):
Function bla
Push $R0
Push $R1
...code...
Pop $R1
Pop $R0
FunctionEnd
The more you work with NSIS the more complex the scripts will become. This will increase the potential of mistakes, especially when dealing with lots of variables. There are a few possibilities to help you debugging the code. To display the contents of variables you should use MessageBoxes or DetailPrint. To get a brief overview about all variables you should use the plugin Dumpstate. By default all actions of the Installer are printed out in the Log Window. You can access the log if you right-click in the Log Window and select "Copy Details To Clipboard". There is also a way to write it directly to a file, see here.
Compiler commands will be executed on compile time on your computer. They can be used for conditional compilation, to include header files, to execute applications, to change the working directory and more. The most common usage is defines. Defines are compile time constants. You can define your product's version number and use it in your script. For example:
!define VERSION "1.0.3"
Name "My Program ${VERSION}"
OutFile "My Program Installer - ${VERSION}.exe"
For more information about defines see Conditional Compilation.
Another common use is macros. Macros are used to insert code on compile time, depending on defines and using the values of the defines. An example of a macro is UpgradeDLL, which you can use to upgrade a DLL file. The macro's commands are inserts at compile time. This allows you to write a general code only once and use it a lot of times but with a few changes. For example:
!macro MyFunc UN
Function ${UN}MyFunc
Call ${UN}DoRegStuff
ReadRegStr $0 HKLM Software\MyProgram key
DetailPrint $0
FunctionEnd
!insertmacro MyFunc ""
!insertmacro MyFunc "un."
This macro helps you avoid writing the same code for both the installer and the uninstaller. The two !insertmacros insert two functions, one for the installer called MyFunc and one for the uninstaller called un.MyFunc and both do exactly the same thing.
For more information see Compile Time Commands.