Thursday 11 August 2011

Brief NSIS reference

NSIS compiler compiles setup.nsi script into two executables: Installer and Uninstaller. Script contains global statements, and statements within sections and functions. Compiler uses section/function names in order to determine which one belong to Installer and which to Uninstaller.

This is a short (and uncomplete) list of some commands and script features. For detailed reference please look at links at the bottom of the article.

OutFile inst_name - defines the name of the output (installer executable).
Example: OutFile "MyApp Setup.exe"

Name app_name - defines the name of the application (product) this installer installs. This name appears in a title bar of the installer's dialog.
Example: Name "My App"

ComponentText text_above text_inst_types text_inst_sect - defines text that appears in the installer dialog. text_above appears above other controls in the dialog, text_inst_types next to installation types select control and text_inst_sect appears next to components sections selection control. This command can be omitted as default text is provided: "Check the components you want to install and uncheck the components you don't want to install. Click Install to start the installation." for  text_above and "Select components to install:" for text_inst_sect.

!define symb_name value - defines symbol (its name and value). Like in C/C++ it can be used in conditional compilation and symbol replacement. ${symb_name} refers to the value of the symbol. Symbol is  replaced with value both in installer and uninstaller sections. Symbol can contain previously defined symbol - in a form of ${symbol}.
Examples:
!define COMPANY "MyCompany"

!define REGKEY "SOFTWARE\${COMPANY}\$(^Name)"
!define PRODUCT_VERSION 1.0.0.0
!define STR_COMPONENT1_DIR "Component1"
!define STR_MAIN_APP_DIR "MyApp"

$INSTDIR - predefined variable, contains path to installation directory; can be set by InstallDir,  ReadRegStr etc...
$PROGRAMFILES - predefined variable, contains path to "Program Files" directory
$STARTMENU - contains path to Start menu directory
$SMPROGRAMS - $STARTMENU\Programs
$SYSDIR - path to Windows system directory (C:\Windows\System32)

InstallDir dir_path - defines directory where the application will be installed. Predeclared variable (we don't need to declare it) $INSTDIR gets initialized with the value of the InstallDir argument.
Example:
InstallDir "$PROGRAMFILES\${STR_MAIN_APP_DIR }"


Var name - declares variable (all variables are global!)
Example:
Var UserName

Variable used in Installer and Uninstaller must be set in both sections! Value set in Installer is not available in Uninstaller - variable is uninitialized. It is therefore better to use symbols for const values (e.g. paths or path roots that do not change) that are used both in Installer and Uninstaller.

StrCpy dest_var src_str - copies src_str string to the destination variable dest_var. Can be used ONLY inside Section or Function!
Example:
StrCpy $UserName "admin"


SetOutPath out_path - sets destination path for copy/move operations. Sets $OUTDIR (output directory) value.
Example:
SetOutPath $INSTDIR
SetOutPath $TempDir
SetOutPath ${SOME_CUSTOM_DIR}

Section [options] section_name [index] - declares beginning of the section section_name, with index
   ...                                                            - here are placed section commands
SectionEnd                                               - declares section end

Sections appear in section selection control in the order they are listed in the script.
If section_name is omitted, empty string or begins with "-", that section is hidden - it will always be executed!

section_name of Uninstaller section must be "Uninstall" or to begin with "un.".

Option /o makes section unselected by default.

Function func_name - declares beginning of the function
...                                  - here are placed function commands
FunctionEnd                - declares the end of the function

func_name must start with "un." for function used in Uninstaller. This can be a bit annoying if you want to use the same function both in Installer and Uninstaller sections. With a help of a macro it is possible to map a single piece of code into two functions: Sharing functions between Installer and Uninstaller.

Call func_name - function call

Special type of (predefined) functions are callback functions.

Installer callback functions:
  • .onInit
  • .onInstSuccess
  • .onInstFailed
  • .onVerifyInstDir
  • .onNextPage
  • .onPrevPage
  • .onSelChange
Uninstaller callback functions:
  • un.onInit
  • un.onUserAbort
  • un.onUninstSuccess
  • un.onUninstFailed
  • un.onNextPage
MessageBox - displays message box
Example:
MessageBox  MB_OK "Hello!"
MessageBox  MB_OK Name is $name


File/directory functions:

SetOverwrite [on|off|try|ifnewer|ifdiff|lastused] - defines whether copy operation will overwrite existing file. on is default value.

File file_path - copies file from file_path path into current output directory. file_path can be either file's absolute path or path relative to the directory which contains this script.
Example:
File "3rdParty\abc-bin-1.0.0.2.zip"

Delete [/REBOOTOK] file_path - deletes file.
Example:
Delete /REBOOTOK $file_customers

CreateDirectory dir_path - creates directory
Example:
CreateDirectory ${WEB_DIR}


RMDir [options] dir_path - removes directory
/r - recursively delete its contents, directories and files. Without this, directory will be removed only if empty!
/REBOOTOK - if directory could not be removed on first attempt, it will be removed after rebootExample:
RMDir ${WEB_DIR}


Registry functions:

ReadRegStr var root_key subkey value_name - reads string from a registry into a variable
Example:
ReadRegStr $INSTDIR HKLM "${REGKEY}" Path - Reads value Path into $INSTDIR

DeleteRegKey [options] root_key subkey - deletes registry key
Example:
DeleteRegKey /IfEmpty HKLM "${REGKEY}\Components"

DeleteRegValue root_key subkey value_name - deletes value in registry
Example:
DeleteRegValue HKLM "${REGKEY}\Components" Main



DetailPrint text - prints text in edit control in main dialog.
Example:
DetailPrint "log_dir = $log_dir" - if log_dir was declared as Var
DetailPrint "web_dir = ${web_dir}" - if web_dir was defined as symbol

CreateShortCut shcut_name.lnk file.ext [options] - creates shortcut
References and useful links:

Nullsoft Scriptable Install System

No comments: