NSIS - Tutorial Nullsoft Scriptable Install System "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/] David Schwingenschuh (BSc)
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
NSIS - TutorialNullsoft Scriptable Install System
"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/]
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
Script File Format
Introduction
• 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
– Headers files can be included by using the follwing command:
;Defintions of Installer AttributesOutFile "ocsSetup.exe"InstallDir "$PROGRAMFILES\ocs"InstallDirRegKey HKLM "${PRODUCT_DIR_REGKEY}" ""ShowInstDetails show
;Definition of variablesVAR /global typeVAR /global databaseserver
• 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.
Functions
Scripting Structure
• 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.
Functions - User
Scripting Structure
• Callback Functions– Are called by the installer upon certain defined
events such as when the installer starts.
• Callbacks are optional.
• Example:– 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.
Functions - Callback
Scripting Structure
• Example: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. – Abort tells the installer to stop initializing the
installer and quit immediately
Functions - Callback
Scripting Structure
• 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.
Compiler Commands
Scripting Structure
• Example:!define VERSION "1.0.3"
Name "My Program ${VERSION}"
OutFile "My Program Installer - ${VERSION}.exe“
Compiler Commands
Scripting Structure
• Another common use is macros.– are used to insert code on compile time, – depending on defines – and using the values of the defines.
• 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.
• 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.
Compiler Commands - Macros
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".
• Write everything into a file
NSIS Framework
• Utilities– MakeNSISW (compiler interface)– Zip2Exe (convert ZIP to SFX)– Language Files
• Documentation– NSIS User Manual– FAQ– NSIS Wiki
Utilities
• NSIS Installers are generated with MakeNSISW
• How?
– Simply right click on a .nsi file and selecting compile
– Commandlineusage:
makensis [option | script.nsi | - [...]]
MakeNSISW
Utilities
• Zip2Exe is able to convert a zip File into a simple installer
• Customizations can be done by changing the header files (Contrib\zip2exe folder)
Zip2Exe
Utitities
• After pressing generate, the installer script will be compiled and is ready for use!
Zip2Exe
Utilities
• NSIS supports multiple languages
• 49 Language Packs come out of the box (contrib\language folder)
_
Documentation
• Includes:– Introduction to NSIS
– Tutorial: The Basis
– Reference book
• Comes out of the box
NSIS User Manual
Documentation
• Answers on the most common questions on NSIS can be found here
Uninstaller FunctionsFunction 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 AbortFunctionEnd
!define PRODUCT_NAME "ocs - Outlook Collaboration Sync"
!define PRODUCT_VERSION "1.0"
• These constants can be used within the entire script
Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
Defintions
Installer Example
• 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…
• Predefined are called with!insertmacro pagename [parameters]
• The order of the entries decides about the point of execution
Pages
Installer Example
• Custompages are called withPage custom pagename [Parameters]
• Example:
Page custom DatabaseConfig
Page custom LicenceConfig
Pages
Installer Example
• Languagepacks can be included with!insertmacro MUI_LANGUAGE “Language"
• Available languages are listed in the following folder:
• Now, the installer is ready for use with enhanced functionality
Include a custom page into the Script
Installer Example
• 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 $0FunctionEnd
Check procedure
http://nsis.sourceforge.net/wiki/Get_.NET_Version
Installer Example
• This functions is called during the .onInit Function
Function .onInit
Call GetDotNETVersion
Pop $0
StrCmp $0 "not found" finish
Finish:MessageBox MB_OK|MB_ICONSTOP ".NET runtime library is not installed. Please download the runtime envirnoment from http://www.microsoft.com/download and install it!"
Abort
FunctionEnd
Check procedure
http://nsis.sourceforge.net/wiki/Get_.NET_Version
Appendix A
• Generates self contained executable installers
• Support for ZLib, BZip2 and LZMA data compression – files can be compressed individually or together)
• Uninstall support – installer can generate an uninstaller)
• Classic and Modern wizard interface[http://nsis.sourceforge.net/features/]
Features
Appendix A
• 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: – You can add standard wizard pages or custom pages
• User selection of installation components, tree for component selection
– 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/]
Features
Appendix A
– 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