Documentation

License

Original Work

NSIS - Copyright (C) 1999-2000 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.

Justin Frankel
justin@nullsoft.com

This source distribution includes portions of zlib. see source/makenssi/zlib/zlib.h for 
its license and so forth. Note that this license is also borrowed from zlib.

Derived Work

NNsis - Copyright (C) 2000-2024 Neal Horman

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.

This software is a modification of the original nsis101h.

Source code notes

The code for the executable header is in source/exehead
The code for the compiler is in source/makenssi (even though it's makensis in the distribution, the projects still generate makenssi.exe. oh well).
The compiler is written in obfuscated C++ (no, really.)
The executable header is written in C and one file of C++ (for some COM crap).
To compile, On windows, use use VC++ 6.
The executable header uses its own mini-libc for small size.

Documentation

Nullsoft Scriptable Installation System (NSIS) v1.0h Features

SuperPiMP[tm] technology.
Generates win32 executable installer.
Uninstall support (installer can automagically generate an uninstaller)
Optional installer self-verification (using adler32)
Robust, efficient zlib compression (with automatic disabling for efficiency)
Approximately 50k overhead over compressed data size
Ability to display a license agreement.
Customizable icon and checkmark bitmaps.
Up to 4 install configurations (usually Minimal, Typical, Full), and custom configuration
No practical limits on number of files, size of files, etc.
No practical limit on number of install sections.
Low memory/resource requirements.
Very fast and efficient.
Easily generated from a script using included compiler
Script is easily editable, easily auto-generated
Optional Silent mode for automated installations
Optional installation logging for debug purposes
Many scriptable install functions including:
- File extraction (with configurable overwrite parameters)
- File/directory deletion
- Executable execution
- Registry key setting/deleting
- INI file writing
- Shortcut creation
- Window finding based on class name (for is-application-running detection)
- User notification using MessageBox().
Completely free for any use. Source included. See license above.

Version history

NNsis - 1.13 (8/30/2022)

add - PathAppend [System | Local] [Environment Variable Name] [Directory Path]
add - PathDelete [System | Local] [Environment Variable Name]

NNsis - 1.12

add - DelTree
add - InstallDirSkip
add - IWSOutFile
add - IWSGetVer

NNsis - 1.11

add - RegPathFile
add - GetBuildNum
add - ServiceAddDep
add - ServiceControl

NNsis - 1.10

add - InstallDirRegKey
add - NeedReboot
add - MkDir
add - UnInstallDir
add - FileDll
add - PromptRegStr
add - PromptRegDWord
add - WWOutFile

NNsis (Neal's Nullsoft Scriptable Installation System ) - 1.0 (10/30/00)

add - MKDir
add - FileDll (untested) - copy file from distribution if "DllGetVersion" of distribution version is greater then existing
add - NeedReboot - show the reboot wizard step
add - $DESKTOPALLUSERS
add - $STARTMENUALLUSERS
add - wizard step to support NeedReboot
add - visible required component sections
add - install types 5-9
add - install/uninstall wizard button key accelerators
add - finish button to final wizard step
fix - RegDll "-" (uninstall), also make it more verbose
change - first component selection is no longer unselectable/required
change - add ability to show a component selection and still require it durring installation
change - FindWindow to search window titles if <windowclass> was not found in window classes
change - use standard inherited windows colors (ie. don't spec out the window colors)
change - InstallDirRegKey - if found, then the directory selection wizard step will be skipped
change - CreateShortCut will now add a "Start In" directory path using the path of the specified exe

NSIS - v1.0h (8/23/00)

improvements to compression (larger blocks) - faster compression (configurable in fileform.h)
nifty status display for compressing in makensis

NSIS - v1.0g (8/1/00)

uninstall bug fix

NSIS - v1.0f (7/31/00)

first public release

Invocation

nnsis <script[.nsi]>

Execute <script> where .nsi extension is used if not specified
nnsis [+|-]<wwpkg | iws>

This form names an embeded template type for use in generating a new script.
```
wwpkg = Wonderware package generator
iws = Indusoft package generator
```
The proceeding action specifier determines if the script should then be executed after it is generated.
```
- = do not execute the generated script
+ = execute the generated script
```
- Example
  
  In the case where a new Wonderware packaging script needs to be created, typical usage would be to open a command window, CD to the directory where the project is located, and then envoke
```
nnsis +wwpkg
```
  To generate a script named wwpkg.nsi, and then execute it, or
```
nnsis -wwpkg
```
  To generate a packaging script, but not execute it.
  
  After generating a packging script, you could rename wwpkg.nsi as desired.

NNSIS .nsi script format

Simple notes:

Lines beginning with ; or # are comments.
Non-comment lines are in the form of
```
<command> <parameter> ...
```
The number of parameters for a given command must match exactly.
The parser is very pedantic.
Some commands may have optional parameters.
To represent strings that have spaces, use quotes.

Unquoted Quoted

this is a test "this is a test" or 'this is a test' or `this is a test`

they're bad "they're bad" or `they're bad`

I said "yo, I'm crazy" `I said "yo, I'm crazy"`
Quotes only have the property of containing a parameter if they begin the parameter. i.e.
```
yo"this is a test"
```
will be multiple parameters. ie.

Param 1 Param 2 Param 3 Param 4

yo"this is a test "

It's a little weird... The quoting character must have white space preceeding it to properly delineate it as a single parameter.

Note that, to help debug your installer, you may enable logging at runtime by holding down shift during the install process, until the directory selection portion comes up, and the option 'log install' shows up. Check the checkbox and resume installation, and a file install.log will be created in the installation directory.

Installer configuration setting commands

Header setting commands

Name <name>

This setting sets the name of the installer.

The name is usually simply the product name.

Note that this value effects how the install directory is formed if the user selects their own (see InstallDir, below).
Icon <path to icon.ico>

This setting changes the icon of the installer.

The icon MUST be a 32x32x16 icon only, and must be exactly 766 bytes long.
OutFile

This setting specifies the output file that the MakeNSIS should write to.
SilentInstall <enableflag>

This setting lets you specify whether or not the installer should be silent.

Enableflag should be either 'normal', 'silent', or 'silentlog'.

If it is 'silent' or 'silentlog', the default configuration is installed and nothing more.

MessageBoxes are still displayed on error.

The compiler will optimize the installer for this type of install (i.e. remove sections, remove license text, etc).
CRCCheck <crcheckflag>

This settings lets you specify whether or not the installerwill perform a CRC check on itself before allowing an install. valid options are 'on' and 'off'.
UninstallIcon <path to icon.ico>

This setting changes the icon of the uninstaller. Again, the icon MUST be a 32x32x16 icon only, and must be exactly 766 bytes long.
UninstallText <text>

This setting lets you specify the text on the first page of the uninstaller.
UninstallExeName <exename.exe>

This setting lets you change the executable name of the uninstaller. It will be dropped in $INSTDIR.

License page setting commands

LicenseText <text>

This setting lets you specify a string that is above the license text. Omit this if you do not wish to have a license displayed.
LicenseData <full path to license data file>

This setting will let you specify a text file to use for the license that the user can read.

Omit this if you do not wish to have a license displayed.

Note that the file must be in the evil DOS text format (\r\n, yeah!)

Component page setting commands

ComponentText <text goes here>

This setting lets you specify a string that is above the component list. This can be something that specifies what it is you are actually installing.
InstType <install type name>

This command lets you add install types. You can use it up to 4 types, each one specifying the name of the install. The first type is the default (so make it 'Typical'). Each type is numbered, starting at 1. See SectionIn for information on how those numbers are used.
EnabledBitmap <path to bitmap.bmp>

This command replaces the enabled state of the listbox for the component page. It MUST be a 20x20x16, 358 byte BMP.
DisabledBitmap <path to bitmap.bmp>

This command replaces the disabled state of the listbox for the component page. It MUST be a 20x20x16, 358 byte BMP.

Directory selection page setting commands

DirText <text>

This setting lets you specify a string that is above the directory selection area
InstallDir <default install directory>

This setting changes what the default installation directory is. See the variables section for variables you can use to make this string (especially $PROGRAMFILES).
InstallDirRegKey <root key> <subkey> <key name>

This command checks to see if a string is in the registry, then uses it for the install dir if that key is there. Use this so your programs can detect if they are upgrading and install to the same path.

If this command is present, it will override the InstallDir command if the registry key is present and non-empty, otherwise it will fall back to the InstallDir default. Note: if the <key name> is found, then the Directory selection wizard step will be skipped.

Installation execution commands

Following the header commands, are the installation execution commands. These commands are executed in order by the installer. They are grouped into sections, each of which can be independently installed. Sections are begun with the Section command, but you don't need to create the first (default) section, it is created implicitly.

Section <section name>

This command creates a new section.

If <section name> begins with a '-' then the section will be installed without being shown to the user in the compoment selection window.

If <section name> begins with a '+' then the section will be installed while being shown to the user in the component selection window.

If <section name> is 'Uninstall', then the installer will generate $INSTALLDIR\nsuninst.exe (or something different if the UninstallExeName command is used), which, when executed will prompt the user whether or not an uninstall is desired, then execute the commands in the uninstall section.

Upon uninstall, $INSTALLDIR is determined by the location of the nsuninst.exe.
SectionIn <section index list>

This command specifies which Install Types (see InstallType) this section defaults to the enabled state in.

Install section numbers can range from 1 to 9. The list can be comma delimited, or just a plain list of numbers (1234 or 1,2,3,4 are both fine)
SetOutPath <output path>

This command sets the output path for files following that use the File command. Must be full pathname, usually is just $INSTDIR.
SetOverwrite <overwriteflag>

This command sets the overwrite flag which is used by the File command to determine whether or not the file should overwrite any existing files that are present.

If overwriteflag is 'on', files are overwritten (this is the default).

If overwriteflag is 'off', files that are already present are not overwritten.

If overwriteflag is 'try', files are overwritten if possible (meaning that if the file is not able to be written to, it is skipped).

Note that this isn't actually an installer command, but just a state modifier in the script compiler.

Hence this instruction takes effect even if the section it is in isn't installed.
SetCompress <compressflag>

This command sets the compress flag which is used by the File and InstNSPlug commands to determine whether or not the file should be compressed.

If compressflag is 'auto', then files are compressed if the compressed size is smaller than the uncompressed size (usually the case).

If compressflag is set to 'force', then compression is always used, and if compressflag is 'off' then compression is not used.

Note that this isn't actually an installer command, but just a state modifier in the script compiler.

Hence this instruction takes effect even if the section it is in isn't installed.
File [OPTIONAL]<full path to file>

This command adds a file to be extracted to the current output path specified with SetOutPath.

Note that the file name is <output path>\<filename portion of full path to file>. Wildcards are supported.

The [OPTIONAL] argument is used to allow the file to not be present at the time of script execution.
FileDll [OPTIONAL] <full path to file>

This command adds a file to be extracted to the current output path specified with SetOutPath.

Upon adding the file to the install package the Dll is loaded, and a query to the exported "DllGetVersion" function is made, and then unloaded. The query results are stored in the install package for comparison against the existing Dll version at install time.

If the packaged Dll version is greater than the existing, then the file is unpackaged.

Note: If the existing or new dll doesn't export "DllGetVersion" then the comparison will fail, and the file will not be unpackaged.

The [OPTIONAL] argument is used to allow the file to not be present at the time of script execution.
Exec [wait | prompt | promptwait] <full path of file to execute> <parameters>

This command will execute the specfied program.

If wait is specified, it will also wait for the completion of that process.

Note that the file specified must exist on the target system, not the compiling system.

The [ wait, prompt or promptwait ] argument is optional
Delete <path to file(s) .. wildcards are allowed>

This command will delete the parameter from the target system.

Useful for if you want to drop something off in the temp directory using File, then Exec it with the wait flag, then Delete it.
RMDir <full path to directory>

Attempt to remove a directory. For safety reasons, the directory must be empty.
MKDir <full path of directory>

Attempt to recursivley create the directory path specified.
CreateShortCut <link.lnk> <target> <parameters> <icon file> <icon index>

This command will create a shortcut.

Note that the quotes are REQUIRED.

Parameters and icon file are optional, but you must use "" to specify an empty string. Icon index should be 0 if not used.
RegDLL [-]<full path to ActiveX control DLL file>

Loads the specified DLL and calls either DllRegisterServer or DllUnregisterServer based on whether or not the first parameter is a dash (-).
InstNSPlug <full path to netscape plug-in DLL on the source system> This command is depricated and will be silently ignored

This command installs into all instances of Netscape 3+ the plug-in pointed to by the parameter. The name for the plug-in is retrieved from the file portion of the parameter.
DeleteNSPlug <netscape plug-in name (i.e. npplug.dll)> This command is depricated and will be silently ignored

This command removes from all instances of Netscape 3+ the plug-in pointed to by the parameter. Netscape must not be running.
WriteRegStr [CREATEONLY | CREATEONLY_W_REBOOT_REQUIRED] [EXPANDING] <root key> <subkey> <key name> <value>

This command writes a string to the registry. <root key> needs to be one of the following:
```
HKEY_CLASSES_ROOT, HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_USERS, or HKEY_CURRENT_CONFIG
```
You may use variable names in <value> and <key name> but not in <subkey>.

The leading [CREATE..] and [EXPANDING] parameters are optional
WriteRegDword [CREATEONLY | CREATEONLY_W_REBOOT_REQUIRED] <root key> <subkey> <key name> <value>

This command writes a string to the registry. <root key> needs to be one of the following:
```
HKEY_CLASSES_ROOT, HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_USERS, or HKEY_CURRENT_CONFIG
```
You may use variable names in and <key name> but not in <subkey>.

The leading [CREATE..] parameter is optional
WriteRegBin [CREATEONLY | CREATEONLY_W_REBOOT_REQUIRED] <root key> <subkey> <key name> <valuedata>

This command writes a string to the registry. <root key> needs to be one of the following:
```
HKEY_CLASSES_ROOT, HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_USERS, or HKEY_CURRENT_CONFIG
```
<valuedata> is in hexadecimal (i.e. DEADBEEF01223211151). You may use variable names in <key name> but not in <subkey>.

The leading [CREATE..] parameter is optional
DeleteRegValue <root key> <subkey> <key name>

Deletes a registry Value
DeleteRegKey <root key> <subkey>

Deletes a registry key
WriteINIStr <ini filename> <section name> <entry name> <value>

Writes <entry name>=<value> into <ini filename> in [<section name>]. All of the parameters can contain variables.
FindWindow <mode> <windowclass> <messageboxtext>

This command checks for a window named <windowclass> and does an action based on what <mode> is set to.

If the window class as not found, then a check for window titles will be performed using <windowclass>

If <mode> is 'close', this command will attempt to close the window using WM_CLOSE for up to 8 seconds.

If <mode> is 'closeinstant', this command will send a WM_CLOSE message to the window and continue

If <mode> is 'prompt', this command will prompt the user with <messageboxtext> until the window is closed manually.

Note that <messageboxtext> is required even if <mode> is not 'prompt' (it can be empty, but two quotes must be there).

MessageBox <mb options> <messagebox text>

This command will display a messagebox containing <messagebox text>. <mb options> must be one or more of the following (when more, they must be delimited with | and no spaces).

MB_OK                   Display with an OK button
MB_OKCANCEL             Display with an OK and a cancel button
MB_ABORTRETRYIGNORE     Display with abort, retry, ignore buttons.
MB_RETRYCANCEL          Display with retry and cancel buttons
MB_YESNO                Display with yes and no buttons
MB_YESNOCANCEL          Display with yes, no, cancel buttons
MB_ICONEXCLAMATION      Display with exclamation icon
MB_ICONINFORMATION      Display with information icon
MB_ICONQUESTION         Display with question mark icon
MB_ICONSTOP             Display with stop icon
MB_TOPMOST              Make messagebox topmost
MB_SETFOREGROUND        Set foreground
MB_RIGHT                Right align text

NeedReboot <state>

If <state> is "yes", then after the install step, the user will be asked to reboot "Now", or "Later"

If <state> is "no", then the user will not be asked to reboot after the install step. (This is the default)
PromptRegStr [CREATEONLY | CREATEONLY_W_REBOOT_REQUIRED] [EXPANDING] <root key> <subkey> <key name> <value>

This command work exactly like WriteRegStr, but prompts for <value>
PromptRegDword [CREATEONLY | CREATEONLY_W_REBOOT_REQUIRED] <root key> <subkey> <key name> <value>

This command work exactly like WriteRegDword, but prompts for <value>
WWOutFile

Read the app.ver file and set the $WWAPPVER variable, and set OutFile to "..\wwpkg_$WWAPPVER_install.exe"
RegPathFile [OPTIONAL] <root key> <subkey> <key name> <value>

Add a file... like the FILE command, but use the registry entry string as the source file pathname.
GetBuildNum

Extract the valued from and set $BUILDMAJ, $BUILDMIN, $BUILDNUM variables
ServiceAddDep <service name> <service dependency name>

Add <service dependency name> as a required service to be running for <service name> to be started
ServiceControl <start | stop | pause | continue | enable | disable | uninstall> <service name>

Change the state of an installed services
InstallDirSkip

Skip the dialog that asks for an installation directory name.
IWSOutFile

Same as IWSGetInfo, but additionally, Set the OutFile name to ..\iwspkg_$IWSVER_install.exe, using the application version number located in the "ProjectTimeStamp.txt" file.
IWSGetInfo

Set the $IWSVER variable to the application version number located in the "ProjectTimeStamp.txt" file.
DelTree <directory name>

Delete a directory tree located at <directory name>
PathAppend [System | User] [Environment Variable Name] [Directory Path]

Append to the [Environment Variable Name] in the [System or User] section of the enivronment variables.
PathDelete [System | User] [Environment Variable Name]

Remove the [Environment Variable Name] from the [System or User] section of the enivronment variables.

Variables

The following are variables you can use in most items:

$PROGRAMFILES           The program files directory (usually C:\Program Files).
$DESKTOP                The windows desktop directory (usually C:\windows\desktop for win9x, or c:\winnt\profiles\user\desktop for NT).
$DESKTOPALLUSERS        The windows desktop directory (usually C:\windows\desktop for win9x or c:\winnt\profiles\all users\desktop for NT).
$INSTDIR                The installation directory, as chosen by the user (or defaulted to).
$WINDIR                 The windows directory (usually C:\windows)
$SYSDIR                 The windows system directory (usually C:\windows\system or C:\winnt\system32)
$TEMP                   The system temporary directory (usually C:\windows\temp)
$STARTMENU              The start menu folder (usually c:\windows\start menu for win9x or c:\winnt\profiles\user\start menu for NT)
$STARTMENUALLUSERS      The start menu folder (usually C:\windows\start menu for win9x or c:\winnt\profiles\all users\start menu for NT)
$QUICKLAUNCH            The quick launch folder for IE4 active desktop and above. If quick launch is not available, simply returns $TEMP.
$$                      Use to represent $.
$APPDATA                The system user's application data directory (usually C:\Users\{Your User Name}\AppData\Roaming)
$BUILDMAJ               Expanded from the GetBuildNum command
$BUILDMIN               Expanded from the GetBuildNum command
$BUILDNUM               Expanded from the GetBuildNum command
$IWSVER                 Expanded from the IWSGetInfo or IWSOutFile command
$WWAPPVER               Expanded from the WWOutFile command
$REG[HKEY_x \a\b\... keyname]   Expanded from the REG_SZ registry entry

These variables are expanded on the system where the resulting installer is run.

The following variables are expanded on the system where the script is being compiled:

$$PROGRAMFILES
$$WINDIR
$$SYSDIR

$$REG[HKEY_x \a\b\... keyname]  Expanded from the REG_SZ registry entry

where HKEY_x is one of:

HKEY_CLASSES_ROOT   or HKCR
HKEY_LOCAL_MACHINE  or HKLM
HKEY_CURRENT_USER   or HKCU
HKEY_USERS          or HKU
HKEY_CURRENT_CONFIG or HKCC

Variables not defined above will be searched for in the Enivronment Variables of the system where the script is being compiled, and replaced if found, otherwise, passed through unexpanded to be expanded from the Environment Variables of the system where the resulting installer is run.

Templates

WWpkg

Name "Wonderware Package"
WWOutFile
CRCCheck on
InstallDir "$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath '$PROGRAMFILES\Wonderware\Intouch']"
SetOverwrite on
InstType Complete
SilentInstall Silent
SectionIn 1
FindWindow wait "WindowViewer" ""
MkDir c:\temp
Exec wait "$SYSDIR\cmd.exe /c copy $INSTDIR\password.bin c:\temp"
Delete "$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\wonderware\*.*"
Delete "$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\help_files\*.*"
SetOutPath "$INSTDIR"
File "$$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\mcsitfunc.dll"
File "$$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\mcsitfunc.wdf"
File "$$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\mcsitfunc.hlp"
File Optional "$$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\mcsitwiz.dll"
File Optional "$$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\mcsitwiz.ini"
File Optional "$$REG[HKLM SOFTWARE\MCS\OneMessage InstallPath]\onevoip.dll"
SetOutPath "$INSTDIR\sounds"
File "$$REG[HKLM Software\Wonderware\InTouch\Installation InstallPath]\sounds\*.*"
SetOutPath "$INSTDIR"
File Optional mcsitfuncaw.cfg
SetOutPath "$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\Wonderware"
File *.*
SetOutPath "$REG[HKLM SOFTWARE\Wonderware\InTouch\Installation InstallPath]\Wonderware\help_files"
File help_files\*.*
Exec wait "$SYSDIR\cmd.exe /c copy c:\temp $INSTDIR\password.bin"
Delete "$$REG[HKLM Software\WANLink\NNSis wwpkgdir 'c:\isimcs\pkgupdate']\$$REG[HKLM Software\WANLink\NNSis wwdatfile wwpkg_install.dat]"
Exec $INSTDIR\view.exe

IWS

# *** DO NOT MESS WITH ANYTHING BELOW HERE *** 
Name "Indusoft Web Studio Package"
IWSGetVer
OutFile "..\update\iwspkg_$IWSVER_install.exe"
CRCCheck on
InstallDirSkip
SetOverwrite on
InstType Complete
SilentInstall Silent
SectionIn 1

# *** Ok to change things below here *** 
FindWindow closewait "StudioManagerClass" ""
exec wait 'cmd /c for %i in (1,2,3,4,5,6,7,9,10) do taskkill /t /im "Studio Manager.exe" & timeout 1'

DelTree "$$REG[HKLM Software\WANLink\NNSis iwsdirdst 'c:\cml\iws\current']"

SetOutPath "$$REG[HKLM Software\WANLink\NNSis iwsdirdst 'c:\cml\iws\current']"
#File "$$REG[HKLM Software\WANLink\NNSis iwsdirsrc 'c:\cml\###\iws\current']\*.*"
#File "$ENV_VAR\*.*"
File *.*

Delete "$$REG[HKLM Software\WANLink\NNSis iwspkgdir 'c:\cml\iws\update']\$$REG[HKLM Software\WANLink\NNSis iwsdatfile iwspkg_install.dat]"
Exec "RunStartup.exe"

Unquoted	Quoted
this is a test	"this is a test" or 'this is a test' or `this is a test`
they're bad	"they're bad" or `they're bad`
I said "yo, I'm crazy"	`I said "yo, I'm crazy"`