NSIS Quick Start

• Download Blank.zip - 1.2 KB

Introduction

In this article I will cover core essentials of the Nullsoft Scriptable Install System (NSIS) with focus on deploying applications programmed for the Microsoft .NET Framework. I will cover deploying common objects that will immediately give you the power to use this opensource installer today!

Background

As a Rapid Application Development (RAD) .NET programmer I have spent many months looking at different installation systems trying to find one that compliments my application. While my requirements could not be any simpler, it seemed that each installer system I looked at created a new hurdle while solving a defficiency in a previous rival installer. At first look, NSIS reminded me of the C programming language. As a programmer who has strong focus on eye candy within applications I write, I never imagined NSIS being able to offer it all for free. As it turns out NSIS slices and dices .NET deployments.

Contents

• Introduction
• Background
• (Contents)
• Required Software
• Taking advantage of HM wizard
• Compiling from windows
• Editing from windows
• Introducing sections
• Installing MSI 3.1
• Installing NET Framework
• Un\Installing 3rd party .MSI
• Un\Installing 3rd party .DLL
• Un\Installing 3rd party .MSM
• Global Variables & Macros
• Getting help for NSIS
• Debugging
• History

Required Software

Software deployment with NSIS is really broken up into 3 phases as follows:

1. Compiling
2. Creating
3. Editing

As a result, the following applications should be installed.

• Nullsoft Scriptable Install System: http://nsis.sourceforge.net/Main_Page
  NSIS is a professional open source system to create Windows installers.
• HM NIS EDIT: http://hmne.sourceforge.net/
  HM NIS Edit is the best Editor/IDE available for Nullsoft Scriptable Install System (NSIS).
• Notepad++: http://sourceforge.net/projects/notepad-plus/
  Notepad++ is a generic source code editor (it tries to be anyway). It is an excellent editor because it has collapsible code sections, excellent syntax highlighting and lots of quirky gremlins ;). Ultimately the idea will be to uninstall HM NIS EDIT once you have written the bulk of your script.

Taking advantage of HM wizard

What better way to get started than having a visual wizard create all the script code for you. You will need to have both NSIS and HM NIS EDIT installed at this point. Once HM NIS EDIT is loaded just click on the magic wand and it will automatically generate following blank script:

; Script generated by the HM NIS Edit Script Wizard.
 
; HM NIS Edit Wizard helper defines
!define PRODUCT_NAME "My application"
!define PRODUCT_VERSION "1.0"
!define PRODUCT_PUBLISHER "My company, Inc."
!define PRODUCT_WEB_SITE "//www.mycompany.com/%22">http://www.mycompany.com"
!define PRODUCT_DIR_REGKEY "Software\Microsoft\Windows\CurrentVersion\App Paths\AppMainExe.exe"
!define PRODUCT_UNINST_KEY "Software\Microsoft\Windows\CurrentVersion\Uninstall\${PRODUCT_NAME}"
!define PRODUCT_UNINST_ROOT_KEY "HKLM"
 
; MUI 1.67 compatible ------
!include "MUI.nsh"
 
; MUI Settings
!define MUI_ABORTWARNING
!define MUI_ICON "${NSISDIR}\Contrib\Graphics\Icons\modern-install.ico"
!define MUI_UNICON "${NSISDIR}\Contrib\Graphics\Icons\modern-uninstall.ico"
 
; Welcome page
!insertmacro MUI_PAGE_WELCOME
; License page
!insertmacro MUI_PAGE_LICENSE "c:\path\to\licence\YourSoftwareLicence.txt"
; Directory page
!insertmacro MUI_PAGE_DIRECTORY
; Instfiles page
!insertmacro MUI_PAGE_INSTFILES
; Finish page
!define MUI_FINISHPAGE_RUN "$INSTDIR\AppMainExe.exe"
!insertmacro MUI_PAGE_FINISH
 
; Uninstaller pages
!insertmacro MUI_UNPAGE_INSTFILES
 
; Language files
!insertmacro MUI_LANGUAGE "English"
 
; MUI end ------
 
Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
OutFile "Setup.exe"
InstallDir "$PROGRAMFILES\My application"
InstallDirRegKey HKLM "${PRODUCT_DIR_REGKEY}" ""
ShowInstDetails show
ShowUnInstDetails show
 
Section "MainSection" SEC01
  SetOutPath "$INSTDIR"
  SetOverwrite ifnewer
  File "c:\path\to\file\AppMainExe.exe"
  CreateDirectory "$SMPROGRAMS\My application"
  CreateShortCut "$SMPROGRAMS\My application\My application.lnk" "$INSTDIR\AppMainExe.exe"
  CreateShortCut "$DESKTOP\My application.lnk" "$INSTDIR\AppMainExe.exe"
SectionEnd
 
Section -AdditionalIcons
  CreateShortCut "$SMPROGRAMS\My application\Uninstall.lnk" "$INSTDIR\uninst.exe"
SectionEnd
 
Section -Post
  WriteUninstaller "$INSTDIR\uninst.exe"
  WriteRegStr HKLM "${PRODUCT_DIR_REGKEY}" "" "$INSTDIR\AppMainExe.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayName" "$(^Name)"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "UninstallString" "$INSTDIR\uninst.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayIcon" "$INSTDIR\AppMainExe.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayVersion" "${PRODUCT_VERSION}"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "URLInfoAbout" "${PRODUCT_WEB_SITE}"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "Publisher" "${PRODUCT_PUBLISHER}"
SectionEnd
 
 
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
 
Section Uninstall
  Delete "$INSTDIR\uninst.exe"
  Delete "$INSTDIR\AppMainExe.exe"
 
  Delete "$SMPROGRAMS\My application\Uninstall.lnk"
  Delete "$DESKTOP\My application.lnk"
  Delete "$SMPROGRAMS\My application\My application.lnk"
 
  RMDir "$SMPROGRAMS\My application"
  RMDir "$INSTDIR"
 
  DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}"
  DeleteRegKey HKLM "${PRODUCT_DIR_REGKEY}"
  SetAutoClose true
SectionEnd

Compiling from Windows

The fastest way to compile a .nsi file is from Windows Explorer using the right click context menu. Providing you have NSIS installed, you will have a fully functional, self contained Setup.EXE in same folder in few seconds, depending on dependencies.

Editing from Windows

The fastest way to edit a .nsi file is from Windows Explorer using the right click context menu. Providing you have Notepad++ installed, you will be looking at the editable script with full syntax highlighting in a fraction of a second.

Introducing sections

At the heart of NSIS are sections that perform specific installation tasks. These not only make it easier to manage your script, but also make the installer more powerful by allowing the end user to control which aspects of the software are to be installed. Sections may be optional, hidden, bold, read only and unchecked.

Installing MSI 3.1

It seems that there is always one desktop in every business that is running Windows XP SP0. This is a major problem because it will crash the .NET Framework installer. Here is the code to check the MSI version and install MSI 3.1 if required:

Section 'MSI 3.1' SEC02 #NOTE should be installed before NET and stuff

  GetDLLVersion '$SYSDIR\msi.dll' $R0 $R1
  IntOp $R2 $R0 / 0x00010000 ; $R2 now contains major version
  IntOp $R3 $R0 & 0x0000FFFF ; $R3 now contains minor version
  IntOp $R4 $R1 / 0x00010000 ; $R4 now contains release
  IntOp $R5 $R1 & 0x0000FFFF ; $R5 now contains build
  StrCpy $0 '$R2.$R3' ;.$R4.$R5' ; $0 now contains string like '1.2.0.192'
    ${if} $R2 < '4'
        ${if} $0 != '3.1'
     ;options
     SetOutPath '$TEMP'
     SetOverwrite on
     ;file work
     File 'd:\mmm.runtimes\WindowsInstaller-KB893803-v2-x86.exe'
     ExecWait '$TEMP\WindowsInstaller-KB893803-v2-x86.exe /quiet /norestart' $0
     DetailPrint '..MSI 3.1 exit code = $0'
     Delete '$TEMP\WindowsInstaller-KB893803-v2-x86.exe'
     ${Else}
     DetailPrint '..MSI $0 already installed !!'
     ${EndIf}
    ${Else}
    DetailPrint '..MSI $0 already installed !!'
    ${EndIf}
 
SectionEnd

Installing .NET Framework

NSIS has about 100 code articles on their site that you may want to check out at the following URL http://nsis.sourceforge.net/Category:Code_Examples. However lets take a detailed look at the current and future releases of the .NET Framework:

First, it is not a good idea to uninstall the .NET Framework considering it is part of Windows Vista. Second, I strongly recommend that you stick to deploying .NET 2.0, because it is the simplest in terms of dependencies, the fastest, and has the smallest footprint. Since .NET 3.0 contains .NET 2.0, this seems to be the best option at present, but it will be very interesting to see how many changes will be in .NET 3.5 (codename "Orcas"). I have noticed that ListView may be included in Windows.Forms 3.5, although Microsoft seems to be holding back on the majority of fixes for compatibility reasons.

Section 'NET Framework 2.0 SP1' SEC03
  
  ;registry
  ReadRegDWORD $0 HKLM 'SOFTWARE\Microsoft\NET Framework Setup\NDP\v2.0.50727' Version
  
    ${If} $0 == '2.1.21022'
    DetailPrint '..NET Framework 2.0 SP1 already installed !!'
    ${Else}
    ;options
    SetOutPath '$TEMP'
    SetOverwrite on
    ;file work
    File 'c:\path.to.file\netfx20sp1_x86.exe'
    ExecWait '$TEMP\netfx20sp1_x86.exe /quiet /norestart' $0
    DetailPrint '..NET Framework 2.0 SP1 exit code = $0'
    Delete '$TEMP\netfx20sp1_x86.exe'
    ${EndIf}
  
SectionEnd

Installing and Uninstalling 3rd party .MSI

Let's assume that your software needs to install an ODBC driver, and this needs to be installed with the \quiet option. Your NSIS section should look like this:

Section 'MySQL ODBC 003.051.XXX' SEC02
  DetailPrint '..Installing MySQL ODBC'
  ;options
  SetOutPath '$TEMP'
  SetOverwrite on
  ;file work
  File "c:\path.to.file\mysql-connector-odbc-3.51.22-win32.msi" 
    # NOTE Dont forget to change to uninstall GUID
  ExecWait 'MsiExec.exe /q /i $TEMP\mysql-connector-odbc-3.51.22-win32.msi' $0
  DetailPrint '..MySQL ODBC Connector exit code = $0'
  Delete '$TEMP\mysql-connector-odbc-3.51.22-win32.msi'
SectionEnd

And for uninstalling as follows:

Section Uninstall
  .
  .
  ExecWait 'MsiExec.exe /q /X{88164D59-4FFD-4874-93BC-5E001A7938F3}' $0
  DetailPrint '..MyODBC exit code = $0'
SectionEnd

You can get the GUID from the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\.

Installing and Uninstalling 3rd party .DLL

Now that we have installed the .NET Framework, you may want to also install 3rd party Assemblies. The best way to do this is with gacutil.exe provided by Microsoft in .NET 2.0:

Section 'MySQL NET 005.000.XXX' SEC03
  DetailPrint '..Installing NET connector'
  ;options
  SetOutPath '$INSTDIR'
  SetOverwrite ifnewer
  ;uninstall #if required, code added for cp user Jonathan [Darka]
  ;ExecWait '"$INSTDIR\gacutil.exe" /uf
             "$INSTDIR\MySql.Data"' $0
  ;file work
  File 'c:\path.to.file\gacutil.exe'
  File 'c:\path.to.file\MySql.Data.dll'
  ;install
  ExecWait '"$INSTDIR\gacutil.exe" /silent /i 
     "$INSTDIR\MySql.Data.dll"' $0 
     #FIX wasn't working without double quotes
  DetailPrint '..MySQL NET Connector exit code = $0'
SectionEnd

NOTE ABOUT UNINSTALLING PREVIOUS ASSEMBLIES

1. ExecWait '"$INSTDIR\gacutil.exe" /uf "$INSTDIR\MySql.Data"' $0
2. /UF = Uninstall + Force
3. The above command will not work if you pass gacutil.exe the file extension ".DLL"
4. I have positive feedback about the FCT plugin which closes apps by their window title. sam6nz says it is "reliable and flexible"

And to uninstall:

Section Uninstall
 .
 .
 ;SEC05 – NET
 ;options
 SetOutPath '$TEMP'
 SetOverwrite on
 ;file work
 File 'c:\path.to.file\gacutil.exe'
 File 'c:\path.to.file\MySql.Data.dll'
 DetailPrint '..Uninstalling MySql.Data.dll'
 ExecWait '$TEMP\gacutil.exe /silent /u MySql.Data' $0
 DetailPrint '..MySql.Data exit code = $0'
SectionEnd

Installing and Uninstalling 3rd party .MSM

This is actually the same as Installing and Uninstalling 3rd Party .MSI except we have to convert the .MSM to a .MSI file. For example, assume you want to convert Crystal Reports 2005 .MSM to a standard .MSI file. Once the conversion is completed, you can use any standard install option flags, such as /q, with the .MSI file and it works as expected. The easiest way to convert a .MSM file to a .MSI file is with a VS2005 Setup Project. See the following figures for instructions.

Adding MSM file to Setup Project:

Some or most .MSM files have various dependencies. For example the .MSM file you want to convert may require another .MSM file such as C:\Program Files\Common Files\Merge Modules\Microsoft_VC80_ATL_x86.msm which is installed with VS2005 if you check Install Redistributables during setup. If you don't have this file, run VS setup again and check the box.

Global Variables and Macros

The following are some of the installer attributes (flags) that I normally use and strongly recommend:

You may also want to include the following macro:

!insertmacro MUI_PAGE_LICENSE "..\Folder\YourLicense.rtf"

Getting help for NSIS

For a rapid response, try the NSIS forums at http://forums.winamp.com/forumdisplay.php?s=315447ba88ebb577ca060ea8dcffa07d&forumid=65, although they may point you toward the code examples link I gave early.

Debugging

If you need to debug your script, the best thing to do is write debug info using DetailPrint and then use a MessageBox MB_ICONINFORMATION|MB_OK as a break point. This will pause the installer until you can verify the point of failure.

History

• 24-June-2007 – First version submitted.
• 25-June-2007 - Revamped HTML, added MSI 3.1 Support for XP SP0 platforms, /UF flag for uninstalling previous version of assemblies.
• 07-July-2007 - Missing line to MSI 3.1 section added.
• 19-July-2007 - Fixed and simplified version comparison.
• 17-Oct-2007 - Improved MSI logic, changed double quotes to single.
• 16-Dec-2007 - Upgraded NET20 to NET20 SP1