Professional Documents
Culture Documents
"An installer is the first experience of a user with your application. Slow or unsuccessful software installations are the most irritating computer problems. [http://nsis.sourceforge.net/home/]
Agenda
Introduction Scripting Structure
Installer Attributes Pages Sections Functions Compiler Commands
Debugging Scripts
Agenda
Development Tools NSIS Framework Installer Example Appendix A: Detailed features
Introduction
NSIS creates installers that are capable of
installing, uninstalling, setting system settings, extracting files, etc.
Introduction
The script language supports
variables, functions, string manipulation
Introduction
Setting up NSIS Environment
Introduction
Setting up NSIS Environment
Introduction
Setting up NSIS Environment
Press on Test Installer -> Congratulations you have successfully compiled your first NSIS Installer
Introduction
Script Files
Introduction
Script Files
In a NSIS script every line is treated as a command. If your command is too long for one line
you can use a back-slash - '\' - at the end of the line..
For example:
Messagebox MB_OK|MB_ICONINFORMATION \ "This is a sample that shows how to use line breaks for larger commands in NSIS scripts"
Introduction
Script Files
Introduction
Script File Format
Commands Commands lines are in the format 'command [parameters]' File "myfile" Comments Lines beginning with ; or # are comments. You can put comments after commands. You can also use C-style comments to comment one or more lines
Introduction
Script File Format
Example:
; Comment # Comment
/* Comment Comment */
Introduction
Script File Format
Numbers
For parameters that are treated as numbers, use
decimal (the number) or hexadecimal (with 0x prepended to it, i.e. 0x12345AB), or Octal (numbers beginning with a 0 and no x).
IntCmp 1 0x1 lbl_equal
Introduction
Script File Format
Variables
Variables start with $. User variables should be declared.
Var MYVAR
Plug-ins
To call a plug-in, use 'plugin::command [parameters]'. nsExec::Exec "myfile"
Introduction
Script File Format
Strings
Introduction
Script File Format
Examples:
MessageBox MB_OK "I'll be happy" ; this one puts a ' inside a string MessageBox MB_OK 'And he said to me "Hi there!"' ; this one puts a " inside a string MessageBox MB_OK `And he said to me "I'll be happy again!"` ; this one puts both ' and "s inside a string MessageBox MB_OK "$\"A quote from a wise man$\" said the wise man" ; this one shows escaping of quotes
It is also possible to put newlines, tabs etc. in a string using $\r, $\n, $\t etc.
Introduction
Script File Format
Long commands
To extend a command over multiple lines,
use a backslash (\) at the end of the line. For example:
CreateShortCut "$SMPROGRAMS\NSIS\ZIP2EXE project workspace.lnk" \ "$INSTDIR\source\zip2exe\zip2exe.dsw"
MessageBox MB_YESNO|MB_ICONQUESTION \ "Do you want to remove all files in the folder? \ (If you have anything you created that you want \ to keep, click No)" \ IDNO NoRemoveLabel
Introduction
Script Files
The default extension for a script file is .nsi Header files have the .nsh extension
Header files are useful in case of
reuseability of the functions to split one huge script file into smaller pieces
Scripting Structure
General Overview
;Defines !define PRODUCT_NAME "ocs - Outlook Collaboration Sync" !define PRODUCT_VERSION "1.0" !define PRODUCT_PUBLISHER "mausz.net ;Includes !include "MUI.nsh ;Pages !insertmacro MUI_PAGE_DIRECTORY Page custom DatabaseConfig ;Defintions of Installer Attributes OutFile "ocsSetup.exe" InstallDir "$PROGRAMFILES\ocs" InstallDirRegKey HKLM "${PRODUCT_DIR_REGKEY}" "" ShowInstDetails show ;Definition of variables VAR /global type VAR /global databaseserver
NSIS Script
Scripting Structure
General Overview
;Functions
Function .onInit !insertmacro MUI_INSTALLOPTIONS_EXTRACT_AS \ "databaseconfig.ini" "DatabaseConfig" !insertmacro MUI_INSTALLOPTIONS_EXTRACT_AS \ "licenceconfig.ini" "LicenceConfig" FunctionEnd
;Sections
Section "Application" SEC01 SetOutPath "$INSTDIR" SetOverwrite ifnewer File "syncApp.exe" CreateDirectory \ "$SMPROGRAMS\ocs - Outlook Collaboration Sync" File "App.ico" SectionEnd
NSIS Script
Scripting Structure
Installer Attributes
Determine the behavior and the look and feel of the 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.
Name OCS v.1.0" OutFile syncApp.exe" InstallDir "$PROGRAMFILES\ocs"
Scripting Structure
Variables
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 TEST ;Declare the variable
Section testsec StrCpy $TEST "123" ;Now you can use the variable $BLA SectionEnd
Scripting Structure
Variables
In addition there is a Stack, which can also be used for temporary storage. To access the stack use the commands:
Push adds a value to the stack, Pop removes one and sets the variable.
Scripting Structure
Variables
the variables contain the same value as before. Note the order when using multiple variables (last-in first-out): Function testfunc Push $R0 Push $R1
...code...
Pop $R1 Pop $R0 FunctionEnd
Scripting Structure
Pages
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):
Example: Page license Page components Page directory Page instfiles UninstPage instfiles
Scripting Structure
Sections
In a common installer there are several things the user can install.
(e.g.: Application, Database, Additional Features, etc.)
Scripting Structure
Sections
For each component operations must be implemented. In the script, that code is in sections Each visible section is a component for the user to choose from. Uninstallers can also have multiple sections.
are prefixed with 'un.'.
Scripting Structure
Sections
Example:
Section "Application" SEC01 SetOutPath "$INSTDIR" SetOverwrite ifnewer File "syncApp.exe" CreateShortCut "$SMPROGRAMS\ocs\ocs.lnk "$INSTDIR\syncApp.exe" CreateShortCut "$DESKTOP\ocs.lnk \ "$INSTDIR\syncApp.exe" File "App.ico" CreateDirectory "xsl" SetOutPath "$INSTDIR\xsl" File "xsl\ACrmToExchange.xsl" SectionEnd Section "Database" SEC02 ... ExecWait '"$R1\Binn\osql.exe" -E -s \ "$R2" -i "$INSTDIR\db\restoreDatabase.sql" -o "$R0" -b' ... ClearErrors SectionEnd Section "Configuration" SEC03 SetOutPath "$APPDATA" CreateDirectory "ocs" SetOutPath "$APPDATA\ocs" File "config\licence.xml" SectionEnd
Scripting Structure
Functions
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.
Scripting Structure
Functions - User
User Functions
Are called by the user from within sections or other functions using the Call instruction.
Scripting Structure
Functions - Callback
Callback Functions
Are called by the installer upon certain defined events such as when the installer starts.
Scripting Structure
Functions - Callback
Example:
Function .onInit MessageBox MB_YESNO "This will install My Program. Do you wish to continue?" IDYES gogogo Abort gogogo: FunctionEnd
Scripting Structure
Compiler Commands
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.
Scripting Structure
Compiler Commands
Example:
!define VERSION "1.0.3" Name "My Program ${VERSION}" OutFile "My Program Installer - ${VERSION}.exe
Scripting Structure
Compiler Commands - Macros
are used to insert code on compile time, depending on defines and using the values of the defines.
Scripting Structure
Compiler Commands - Macros
Example:
!macro MyFunc UN Function ${UN}MyFunc Call ${UN}DoRegStuff ReadRegStr $0 HKLM Software\MyProgram key DetailPrint $0 FunctionEnd !macroend !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.
Debugging Scripts
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 plug-in DumpState.
Debugging Scripts
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".
Documentation
NSIS User Manual FAQ NSIS Wiki
Utilities
MakeNSISW
Utilities
Zip2Exe
Zip2Exe is able to convert a zip File into a simple installer Customizations can be done by changing the header files (Contrib\zip2exe folder)
Utitities
Zip2Exe
After pressing generate, the installer script will be compiled and is ready for use!
Utilities
_
Documentation
NSIS User Manual
Includes:
Introduction to NSIS
Tutorial: The Basis Reference book
Documentation
FAQ
http://nsis.sourceforge.net/wiki/Category:FAQ
Documentation
Wiki
Development Tools
HM NIS
http://hmne.sourceforge.net/
Venis VIX
http://www.spaceblue.com/venis/
EclipsePlugin
http://eclipsensis.sourceforge.net/
Development Tools
HM NIS - Functionality
Multiple scripts edition and compilation interface (MDI). Translatable interface to any language
(available in English, Spanish, Polish, French, Czech, Italian, Russian, Greek, German, Chinese, Ukrainian, Portuguese (Brazil), Korean).
Syntax highlighting with customizable colors and text attributes. InstallOptions Designer. Plugins support.
Development Tools
HM NIS - Functionality
Wizard (special for beginner) that will guide for all steps to create a standard Windows Setup program. Script creation from template files. Code templates with most common commands. Basic NSIS command help with only move the mouse cursor over a command in the editor. Advanced NSIS command help pressing F1 key. Execution of the generate Setup program after script compilation (to try the setup program). No need bulky OCX or run time libraries.
Installer Example
Requirements for the installer
Ordinary file copy Creation of links Creation of a config file (xml)
using an external shell programm
Installer Example
Approach
Approach
Creating a simple installer using the wizard of HM NIS Including a batch job
Creation of a XML Config File
Installer Example
HM NIS - Wizard
Installer Example
HM NIS - Wizard
Installer Example
HM NIS - Wizard
GUI Type
Modern Classic None
Compression
Installer Example
HM NIS - Wizard
Licence File
Is shown as before the installer starts
Installer Example
HM NIS - Wizard
Application Files
Installer Example
HM NIS - Wizard
Shortcut settings
Application Start Menu folder name Allow user to change the Start Menu folder name Create an Internet shortcut in the Start Menu folder Create an Uninstall icon in the Start Menu folder Additional shortcuts can be added via the listbox on the bottom
Installer Example
HM NIS - Wizard
Post-Installation settings
Executeable program file
Parameter
Readme - File
Installer Example
HM NIS - Wizard
Uninstaller Settings
Uninstall prompt
Installer Example
HM NIS - Wizard
Last Wizardpage
Installer Example
HM NIS - Wizard
The simple installer is ready for testing! Press Shift+F9 for compile and run
Installer Example
HM NIS - Wizard
Installer Example
HM NSI Wizard - Background
Installer Example
HM NSI Wizard - Script Definitions
!define PRODUCT_NAME "ocs - Outlook Collaboration Sync" !define PRODUCT_VERSION "1.0" !define PRODUCT_PUBLISHER "mausz.net" !define PRODUCT_WEB_SITE "http://www.mausz.net" !define PRODUCT_DIR_REGKEY "Software\Microsoft\Windows\CurrentVersion\App Paths\syncApp.exe" !define PRODUCT_UNINST_KEY "Software\Microsoft\Windows\CurrentVersion\Uninstall\${PRODUCT_NAME}" !define PRODUCT_UNINST_ROOT_KEY "HKLM
Pages
; Welcome page !insertmacro MUI_PAGE_WELCOME ; License page !insertmacro MUI_PAGE_LICENSE "..\..\sync\installer\lizenz.rtf" ; Components page !insertmacro MUI_PAGE_COMPONENTS ; Directory page !insertmacro MUI_PAGE_DIRECTORY ; Instfiles page !insertmacro MUI_PAGE_INSTFILES ; Finish page !define MUI_FINISHPAGE_RUN "$INSTDIR\config\XmlConfigWriter.exe" !define MUI_FINISHPAGE_SHOWREADME "$INSTDIR\config\.svn\README.txt" !insertmacro MUI_PAGE_FINISH
Installer Example
HM NSI Wizard - Script Languages
; Language files !insertmacro MUI_LANGUAGE "English"
Installer Sections
Section "Application" SEC01 SetOutPath "$INSTDIR" SetOverwrite try File "App.ico SectionEnd Section -Post WriteUninstaller "$INSTDIR\uninst.exe" WriteRegStr HKLM "${PRODUCT_DIR_REGKEY}" "" "$INSTDIR\config\XmlConfigWriter.exe SectionEnd
Installer Example
HM NSI Wizard - Script Uninstaller Functions
Function un.onUninstSuccess HideWindow MessageBox MB_ICONINFORMATION|MB_OK "$(^Name) was successfully removed from your computer." FunctionEnd Function un.onInit MessageBox MB_ICONQUESTION|MB_YESNO|MB_DEFBUTTON2 "Are you sure you want to completely remove $(^Name) and all of its components?" IDYES +2 Abort FunctionEnd
Uninstaller Section
Section Uninstall Delete "$INSTDIR\${PRODUCT_NAME}.url" Delete "$INSTDIR\uninst.exe" Delete "$INSTDIR\xsl\CExchangeToCrm.xsl RMDir "$INSTDIR\config\.svn" RMDir "$INSTDIR\config" RMDir "$INSTDIR" .. DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" DeleteRegKey HKLM "${PRODUCT_DIR_REGKEY}" SetAutoClose true SectionEnd
Installer Example
Defintions !define PRODUCT_NAME "ocs - Outlook Collaboration Sync" !define PRODUCT_VERSION "1.0"
Installer Example
Pages
The used Pages are predefined pages which are part of the NSIS2 Framework
; Welcome page !insertmacro MUI_PAGE_WELCOME ; License page !insertmacro MUI_PAGE_LICENSE "..\..\sync\installer\lizenz.rtf" ; Components page !insertmacro MUI_PAGE_COMPONENTS
Installer Example
Pages
Example:
Page custom DatabaseConfig Page custom LicenceConfig
Installer Example
Languages
Installer Example
Installer Attributes
Applicationname
Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
Installation Directory
InstallDir "$PROGRAMFILES\ocs
Registry Key
InstallDirRegKey HKLM "${PRODUCT_DIR_REGKEY}" "
Installer Example
Installer Section
As defined = Application
Section "Application" SEC01
The File commando copies the given File into the defined Output Path
File "App.ico"
Creation of a directory
CreateDirectory "$SMPROGRAMS\ocs"
Installer Example
Uninstaller Functions
Installer Example
Uninstaller Section
Uninstaller Section
Section Uninstall
Deletes the given file Delete "$INSTDIR\xsl\CExchangeToCrm.xsl Deletes the given directory RMDir "$INSTDIR\xsl" Deletes the given registry key DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" DeleteRegKey HKLM "${PRODUCT_DIR_REGKEY}"
SectionEnd
Installer Example
Creation of a XML config file
Approach
Creation of a custom page
input option for username, password and url
Installer Example
Creating the custom page
Installer Example
Creating the custom page
A control toolbar can be found on the right side of the HM NSI Window A control can be moved to the window by one click on the required control and another click on the desired position within the custom page
Installer Example
Creating the custom page
On the right side a property bar is located which can be used to configure the controls The FieldNum property is very important, because this is used within the script to access the control
After every control is configured the custom page must be safed (etc. licenceconfig.ini)
Installer Example
Include a custom page into the Script
Installer Example
Include a custom page into the Script
The custom page must be placed into the right page order
; Welcome page !insertmacro MUI_PAGE_WELCOME ; License page !insertmacro MUI_PAGE_LICENSE "lizenz.rtf" ; Components page !insertmacro MUI_PAGE_COMPONENTS ; Directory page !insertmacro MUI_PAGE_DIRECTORY
Installer Example
Include a custom page into the Script
Installer Example
Include a custom page into the Script
Macro description
Header text configuration
!insertmacro MUI_HEADER_TEXT "LicenceConfig" "subtitle
Installer Example
Include a custom page into the Script
!insertmacro MUI_HEADER_TEXT "LicenceConfig" "subtitle !insertmacro MUI_INSTALLOPTIONS_DISPLAY "LicenceConfig !insertmacro MUI_INSTALLOPTIONS_READ $6 "LicenceConfig" "Field 6" "State !insertmacro MUI_INSTALLOPTIONS_READ $7 "LicenceConfig" "Field 7" "State !insertmacro MUI_INSTALLOPTIONS_READ $8 "LicenceConfig" "Field 8" "State"
FunctionEnd
Header_Text
Installer Example
Include a custom page into the Script
Installer Example
Check procedure
To check if the .Net Framwork is available the following function must be included
Function GetDotNETVersion Push $0 Push $1 System::Call "mscoree::GetCORVersion(w .r0, i ${NSIS_MAX_STRLEN}, *i) i .r1" StrCmp $1 "error" 0 +2 StrCpy $0 "not found" Pop $1 Exch $0 FunctionEnd
http://nsis.sourceforge.net/wiki/Get_.NET_Version
Installer Example
Check procedure
FunctionEnd
http://nsis.sourceforge.net/wiki/Get_.NET_Version
Appendix A
Features
Generates self contained executable installers Support for ZLib, BZip2 and LZMA data compression
files can be compressed individually or together)
Uninstall support
Appendix A
Features
Fully multilingual, support for multiple languages (including RTL languages) in one installer.
More than 40 translations are already available, but you can also create your own.
Page system:
User selection of installation components, tree for component selection Multiple install configurations
(usually Minimal, Typical, Full), and custom configuration
[http://nsis.sourceforge.net/features/]
Appendix A
Features
Installer self-verification using a CRC32 checksum Small overhead over compressed data size
(34 KB with default options)
Ability to display a license agreement in text or RTF format Ability to detect destination directory from the registry
[http://nsis.sourceforge.net/features/]
Appendix A
Features
Installers can be as large as 2GB Optional silent mode for automated installations A preprocessor with support for defined symbols, macro's, conditional compilation, standard predefines A lovely coding experience with elements of PHP and assembly
(includes user variables, a stack, real flow control, etc.)
[http://nsis.sourceforge.net/features/]
Appendix A
Features
Installers have their own VMs that let you write code that can support:
File extraction (with configurable overwrite parameters) File/directory copying, renaming, deletion, searching Plug-in DLL calling DLL/ActiveX control registration/deregistration Executable execution (shell execute and wait options) Shortcut creation
[http://nsis.sourceforge.net/features/]
Appendix A
Features
Registry key reading/setting/enumerating/deleting INI file reading/writing Generic text file reading/writing Powerful string and integer manipulation Window finding based on class name or title User interface manipulation (font/text setting) Window message sending User interaction with message boxes or custom pages
[http://nsis.sourceforge.net/features/]
Appendix A
Features
Branching, comparisons, etc. Error checking Reboot support, including delete or rename on reboot Installer behaviour commands (such as show/hide/wait/etc) User functions in script Callback functions for user actions
[http://nsis.sourceforge.net/features/]
Appendix A
Features
[http://nsis.sourceforge.net/features/]