NSIS - Tutorial

1. NSIS - Tutorial Nullsoft Scriptable Install System David Schwingenschuh (BSc) "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/]

2. Agenda • Introduction • Scripting Structure • Installer Attributes • Pages • Sections • Functions • Compiler Commands • Debugging Scripts

3. Agenda • Development Tools • NSIS Framework • Installer Example • Appendix A: Detailed features

4. Introduction • NSIS creates installers that are capable of • installing, • uninstalling, • setting system settings, • extracting files, etc. • you can fully control every part of your installers. • based on script files

5. Introduction • The script language supports • variables, • functions, • string manipulation • NSIS is still the smallest installer system available. • (With the default options, it has an overhead of only 34 KB.) A detailed overview about the functions can be found at Appendix A

6. Introduction Setting up NSIS Environment • Download NSIS from: • http://nsis.sourceforge.net/download/ • Installation of nsis-version.exe • NSIS Welcome Screen

7. Introduction Setting up NSIS Environment • NSIS Quick start Installer • Go to the examples folder under the nsis installation directory • Choose one .nsi file with a right mouse click and press compile NSIS Script • The choosen script will be automatically compiled • Press on Test Installer -> Congratulations you have successfully compiled your first NSIS Installer

8. Introduction Setting up NSIS Environment • The choosen script will be automatically compiled • Press on Test Installer -> Congratulations you have successfully compiled your first NSIS Installer

9. Introduction Script Files • A Script file is the basis for NSIS • It is recommended to use editor that shows line numbers • Editors which supports syntax highlighting for NSIS scripts can be found at http://nsis.sourceforge.net/wiki/

10. 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"

11. Introduction Script Files • If you want to use a double-quote in a string • you can either use $\" to escape the quote • or quote the string with a different type of quote such as ` or '.

12. 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

13. Introduction Script File Format • Example: ; Comment # Comment /* Comment Comment */ File "myfile" ; Comment • If you want a parameter to start with ; or # • put it in quotes.

14. 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 • Colors should be set in hexadecimal RGB format, • like HTML but without the #. SetCtlColors $HWND CCCCCC

15. 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"

16. Introduction Script File Format • Strings • To represent strings that have spaces, use quotes: MessageBox MB_OK "Hi there!" • Quotes only have the property of containing a parameter if they begin the parameter. • They can be either • single quotes, • double quotes, • or the backward single quote. • You can escape quotes using $\:

17. 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.

18. 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

19. 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 • Headers files can be included by using the follwing command: • !include <name>.nsh

20. 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

21. 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

22. 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"

23. 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

24. 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. • For shared code, there are 20 registers (like $0 and $R0). • These static variables don't have to be declared and you won't get any name conflicts.

25. Scripting Structure Variables • 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 testfunc   Push $R0   Push $R1     ...code...   Pop $R1   Pop $R0 FunctionEnd

26. 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

27. Scripting Structure Sections • In a common installer there are several things the user can install. • (e.g.: Application, Database, Additional Features, etc.)

28. 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.'.

29. 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

30. 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.

31. Scripting Structure Functions - User • 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.

32. Scripting Structure Functions - Callback • 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.

33. 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 • Abort has a special meaning in callback functions. • Abort tells the installer to stop initializing the installer and quit immediately

34. 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.

35. Scripting Structure Compiler Commands • Example: !define VERSION "1.0.3" Name "My Program ${VERSION}" OutFile "My Program Installer - ${VERSION}.exe“

36. Scripting Structure Compiler Commands - Macros • 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.

37. 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.

38. 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.

39. 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

40. NSIS Framework • Utilities • MakeNSISW (compiler interface) • Zip2Exe (convert ZIP to SFX) • Language Files • Documentation • NSIS User Manual • FAQ • NSIS Wiki

41. Utilities MakeNSISW • NSIS Installers are generated with MakeNSISW • How? • Simply right click on a .nsi file and selecting compile • Commandlineusage: makensis [option | script.nsi | - [...]]

42. 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)

43. Utitities Zip2Exe • After pressing generate, the installer script will be compiled and is ready for use!

44. Utilities _ • NSIS supports multiple languages • 49 Language Packs come out of the box (contrib\language folder)

45. Documentation NSIS User Manual • Includes: • Introduction to NSIS • Tutorial: The Basis • Reference book • Comes out of the box

46. Documentation FAQ • Answers on the most common questions on NSIS can be found here http://nsis.sourceforge.net/wiki/Category:FAQ

47. Documentation Wiki • NSIS Community Portal – NSIS WIKI • Sharing of • Examples • Plug-Ins • Tutorials • Knowledge around NSIS • Etc. http://nsis.sourceforge.net/wiki

48. Development Tools • HM NIS • http://hmne.sourceforge.net/ • Venis VIX • http://www.spaceblue.com/venis/ • EclipsePlugin • http://eclipsensis.sourceforge.net/

49. 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.

50. 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.