Development.NSIS

NSIS (Nullsoft Scriptable Install System, http://nsis.sourceforge.net/) is a tool that allows programmers to create installers for Windows. This library provides an alternative syntax for NSIS scripts, as an embedded Haskell language, removing much of the hard work in developing an install script. Simple NSIS installers should look mostly the same, complex ones should be significantly more maintainable.

As a simple example of using this library:

import Development.NSIS

main = writeFile "example1.nsi" $ nsis $ do
     name "Example1"                  -- The name of the installer
     outFile "example1.exe"           -- Where to produce the installer
     installDir "$DESKTOP/Example1"   -- The default installation directory
     requestExecutionLevel User       -- Request application privileges for Windows Vista
     -- Pages to display
     page Directory                   -- Pick where to install
     page InstFiles                   -- Give a progress bar while installing
     -- Groups fo files to install
     section "" [] $ do
         setOutPath "$INSTDIR"        -- Where to install files in this section
         file [] "Example1.hs"        -- File to put into this section

The file example1.nsi can now be processed with makensis to produce the installer example1.exe. For more examples, see the Examples source directory.

Much of the documentation from the Installer section is taken from the NSIS documentation.

Core types

nsis :: Action () -> String

Create the contents of an NSIS script from an installer specification.

nsisNoOptimise :: Action () -> String

Like nsis, but don't try and optimise the resulting NSIS script. Useful to figure out how the underlying installer works, or if you believe the optimisations are introducing bugs (but please do report any such bugs!).

data Action a

Monad in which installers are defined. A useful command to start with is section.

Instances

Monad Action

Functor Action

Applicative Action

Enum (Exp Int)

Eq (Exp a)

Fractional (Exp Int)

Integral (Exp Int)

Num (Exp Int)

Ord (Exp Int)

Real (Exp Int)

Show (Exp a)

Typeable a => IsString (Exp a)

Monoid (Exp String)

type Exp ty = Action (Value ty)

The type of expressions - namely an Action producing a Value. There are instances for Num and IsString, and turning on {-# LANGUAGE OverloadedStrings #-} is strongly recommended.

The fromString function converts any embedded $VAR into a variable lookup, which may refer to one of the builtin NSIS variables (e.g. $SMPROGRAMS, $TEMP, $PROGRAMFILES), or a named variable created with constant or mutable. The string $$ is used to escape $ values. Bracket the variables to put text characters afterwards (e.g. $(SMPROGRAMS)XXX). In contrast to standard strings, / is treated as \ and // is treated as /. Remember to escape any slashes occuring in URLs.

If the string is Exp String then any Int variables used will be automatically shown (see strShow). If the string is Exp ty then it must be of the form "$VAR" where $VAR is a variable of type ty.

The Eq and Ord instances for Exp throw errors for all comparisons (use %==, %<= etc), but min and max are defined. The Num (arithmetic) and Monoid (string concatenation) instances are both fully implemented. From Integral and Fractional, only /, mod and div are implemented, and all as integer arithmetic. No functions from Enum or Real are implemented.

When using a single expression multiple times, to ensure it is not evaluated repeatedly, use share.

data Value ty

A Value, only used by Exp, which can be produced using return. The ty argument should be one of String, Int or Bool.

Instances

Enum (Exp Int)

Eq (Exp a)

Fractional (Exp Int)

Integral (Exp Int)

Num (Exp Int)

Ord (Exp Int)

Real (Exp Int)

Show (Exp a)

Typeable a => IsString (Exp a)

Monoid (Exp String)

Scripting

Variables

share :: Exp t -> (Exp t -> Action a) -> Action a

The Exp language is call-by-name, meaning you must use share to avoid evaluating an exression multiple times. Using share, if the expression has any side effects they will be run immediately, but not on subsequent uses. When defining functions operating on Exp, if you use the same input expression twice, you should share it. For example:

 strPalindrom x = share x $ \x -> x %== strReverse x

If the expression was not shared, and x read from a file, then the file would be read twice.

scope :: Action a -> Action a

Introduce a variable scope. Scopes are automatically introduced by operations such as iff, loop, while etc. Inside a scope you may define new variables whose names may clash with variables outside the scope, but the local versions will be used.

If you have any non-evaluated expressions, before introducing any potentially clashing variables in the scope you should share them or use constant_ on them. For example:

 operate x = do
     x <- constant_ x
     scope $ do
         constant "TEST" 0

It is important to turn x into a constant_ before defining a new constant $TEST, since if x refers to $TEST after the new definition, it will pick up the wrong variable.

constant :: Typeable t => String -> Exp t -> Action (Exp t)

Create a constant with a name, ensuring the expression is shared. After defining the expression, you can refer to it with $NAME in a String. To introduce a new scope, see scope.

 constant HELLO Hello World
 alert $HELLO!

constant_ :: Exp t -> Action (Exp t)

Create a constant with no name, ensuring the expression is shared. Equivalent to share return.

mutable :: Typeable t => String -> Exp t -> Action (Exp t)

Create a mutable variable a name, which can be modified with @=. After defining the expression, you can refer to it with $NAME in a String. To introduce a new scope, see scope.

 h <- mutable "HELLO" "Hello World"
 "$HELLO" @= "$HELLO!"
 h        @= "$HELLO!" -- equivalent to the above
 alert "$HELLO"        -- with 2 exclamation marks

mutable_ :: Exp t -> Action (Exp t)

Create an unnamed mutable variable, which can be modified with @=.

 h <- mutable "Hello World"
 h @= h & "!"
 alert h

(@=) :: Exp t -> Exp t -> Action ()

Assign a value to a mutable variable. The variable must have been originally created with mutable or mutable_, or there will be an error when generating the install file.

Typed variables

mutableInt :: String -> Exp Int -> Action (Exp Int)

Versions of mutable and constant restricted to Exp Int, used to avoid ambiguous type errors.

constantInt :: String -> Exp Int -> Action (Exp Int)

Versions of mutable and constant restricted to Exp Int, used to avoid ambiguous type errors.

mutableInt_ :: Exp Int -> Action (Exp Int)

Versions of mutable_ and constant_ restricted to Exp Int, used to avoid ambiguous type errors.

constantInt_ :: Exp Int -> Action (Exp Int)

Versions of mutable_ and constant_ restricted to Exp Int, used to avoid ambiguous type errors.

mutableStr :: String -> Exp String -> Action (Exp String)

Versions of mutable and constant restricted to Exp String, used to avoid ambiguous type errors.

constantStr :: String -> Exp String -> Action (Exp String)

Versions of mutable and constant restricted to Exp String, used to avoid ambiguous type errors.

mutableStr_ :: Exp String -> Action (Exp String)

Versions of mutable_ and constant_ restricted to Exp String, used to avoid ambiguous type errors.

constantStr_ :: Exp String -> Action (Exp String)

Versions of mutable_ and constant_ restricted to Exp String, used to avoid ambiguous type errors.

Control Flow

iff :: Exp Bool -> Action () -> Action () -> Action ()

Test a boolean expression, reunning the first action if it is true and the second if it is false. The appropriate branch action will be run within a scope. See ? for an expression orientated version.

 iff (x %== 12) (alert "is 12") (alert "is not 12")

iff_ :: Exp Bool -> Action () -> Action ()

A version of iff where there is no else action.

while :: Exp Bool -> Action () -> Action ()

A while loop, run the second argument while the first argument is true. The action is run in a scope. See also loop.

 x <- mutable_ x
 while (x %< 10) $ do
    x @= x + 1

loop :: (Action () -> Action ()) -> Action ()

A loop with a break command. Run the action repeatedly until the breaking action is called. The action is run in a scope. See also while.

 x <- mutable_ x
 loop $ \break -> do
     iff_ (x %>= 10) break
     x @= x + 1

onError :: Action () -> Action () -> Action ()

Run an intitial action, and if that action causes an error, run the second action. Unlike other programming languages, any uncaught errors are silently ignored. All actions are run in scope.

 onError (exec "\"$WINDIR/notepad.exe\"") (alert "Failed to run notepad")

(?) :: Exp Bool -> (Exp t, Exp t) -> Exp t

An expression orientated version of iff, returns the first component if the first argument is true or the second if it is false.

 x %== 12 ? (x, x + 5)

(%&&) :: Exp Bool -> Exp Bool -> Exp Bool

Short circuiting boolean operators, equivalent to && and || but on Exp.

(%||) :: Exp Bool -> Exp Bool -> Exp Bool

Short circuiting boolean operators, equivalent to && and || but on Exp.

data Label

A code label, used for goto programming, see newLabel.

Instances

Eq Label

Data Label

Show Label

Typeable Label

newLabel :: Action Label

Create a new label, used with goto and label to write line jump based programming. Where possible you should use structured alternatives, such as iff, while and loop. Each created label must be used with one call to label, and any number of calls to goto. As an example:

 abort <- newLabel
 while var $ do
     iff_ cond1 $ goto abort
     iff_ cond2 $ goto abort
     var @= strDrop 1 var 
 label abort

Note that the above example could have been written in a simpler manner with loop.

label :: Label -> Action ()

Define the location of a label, see newLabel for details. This function will fail if the same Label is passed to label more than once.

goto :: Label -> Action ()

Jump to a label, see newLabel for details. This function will fail if label is not used on the Label.

Expressions

str :: String -> Exp String

Lift a String into an Exp

int :: Int -> Exp Int

Lift an Int into an Exp

bool :: Bool -> Exp Bool

Lift a Bool into an Exp

(%==) :: Exp a -> Exp a -> Exp Bool

The standard equality operators, lifted to Exp.

(%/=) :: Exp a -> Exp a -> Exp Bool

The standard equality operators, lifted to Exp.

(%<=) :: Exp Int -> Exp Int -> Exp Bool

The standard comparison operators, lifted to Exp.

(%<) :: Exp Int -> Exp Int -> Exp Bool

The standard comparison operators, lifted to Exp.

(%>=) :: Exp Int -> Exp Int -> Exp Bool

The standard comparison operators, lifted to Exp.

(%>) :: Exp Int -> Exp Int -> Exp Bool

The standard comparison operators, lifted to Exp.

true :: Exp Bool

Boolean constants corresponding to True and False

false :: Exp Bool

Boolean constants corresponding to True and False

not_ :: Exp Bool -> Exp Bool

Boolean negation.

strRead :: Exp String -> Exp Int

Convert a String to an Int, any errors are silently ignored.

strShow :: Exp Int -> Exp String

Convert an Int to a String by showing it.

(&) :: Exp String -> Exp String -> Exp String

Concatenate two strings, for example "$FOO" & "$BAR" is equivalent to "$FOO$BAR".

strConcat :: [Exp String] -> Exp String

Perform string concatenation on a list of expressions.

strLength :: Exp String -> Exp Int

Return the length of a string, strLength "test" %== 4.

strTake :: Exp Int -> Exp String -> Exp String

Take the first n characters from a string, strTake 2 "test" %== "te".

strDrop :: Exp Int -> Exp String -> Exp String

Drop the first n characters from a string, strDrop 2 "test" %== "st".

strReplace :: Exp String -> Exp String -> Exp String -> Exp String

Replace one string with another string, in a target string. As some examples:

 strReplace "t" "XX" "test" %== "XXesXX"
 strReplace "ell" "" "hello world" %== "ho world"

strIsPrefixOf :: Exp String -> Exp String -> Exp Bool

Is the first string a prefix of the second.

strUnlines :: [Exp String] -> Exp String

Join together a list of strings with \r\n after each line. Note that unlike standard unlines, we use the Windows convention line separator.

File system manipulation

data FileHandle

The type of a file handle, created by fileOpen.

Instances

Typeable FileHandle

fileOpen :: FileMode -> Exp FilePath -> Action (Exp FileHandle)

Open a file, which must be closed explicitly with fileClose. Often it is better to use writeFile' or withFile instead.

 h <- fileOpen ModeWrite "C:/log.txt"
 fileWrite h "Hello world!"
 fileClose h

fileWrite :: Exp FileHandle -> Exp String -> Action ()

Write a string to a file openned with fileOpen.

fileClose :: Exp FileHandle -> Action ()

Close a file file openned with fileOpen.

withFile' :: FileMode -> Exp FilePath -> (Exp FileHandle -> Action ()) -> Action ()

With a fileOpen perform some action, then automatically call fileClose. If the action argument jumps out of the section then the fileClose call will be missed.

writeFile' :: Exp FilePath -> Exp String -> Action ()

Write a file, like writeFile.

writeFileLines :: Exp FilePath -> [Exp String] -> Action ()

Write a file comprising of a set of lines.

rmdir :: [Attrib] -> Exp FilePath -> Action ()

Remove the specified directory (fully qualified path with no wildcards). Without Recursive, the directory will only be removed if it is completely empty. If Recursive is specified, the directory will be removed recursively, so all directories and files in the specified directory will be removed. If RebootOK is specified, any file or directory which could not have been removed during the process will be removed on reboot -- if any file or directory will be removed on a reboot, the reboot flag will be set. The error flag is set if any file or directory cannot be removed.

 rmdir [] "$INSTDIR"
 rmdir [] "$INSTDIR/data"
 rmdir [Recursive, RebootOK] "$INSTDIR"
 rmdir [RebootOK] "$INSTDIR/DLLs"

Note that the current working directory can not be deleted. The current working directory is set by setOutPath. For example, the following example will not delete the directory.

 setOutPath "$TEMP/dir"
 rmdir [] "$TEMP/dir"

The next example will succeed in deleting the directory.

 setOutPath "$TEMP/dir"
 setOutPath "$TEMP"
 rmdir [] "$TEMP/dir"

Warning: using rmdir [Recursive] $INSTDIR in uninstall is not safe. Though it is unlikely, the user might select to install to the Program Files folder and so this command will wipe out the entire Program Files folder, including other programs that has nothing to do with the uninstaller. The user can also put other files but the program's files and would expect them to get deleted with the program. Solutions are available for easily uninstalling only files which were installed by the installer.

delete :: [Attrib] -> Exp FilePath -> Action ()

Delete file (which can be a file or wildcard, but should be specified with a full path) from the target system. If RebootOK is specified and the file cannot be deleted then the file is deleted when the system reboots -- if the file will be deleted on a reboot, the reboot flag will be set. The error flag is set if files are found and cannot be deleted. The error flag is not set from trying to delete a file that does not exist.

 delete [] "$INSTDIR/somefile.dat"

getFileTime :: Exp FilePath -> Exp String

Gets the last write time of the file, you should only use the result to compare for equality with other results from getFileTime. On failure the error flag is set.

fileExists :: Exp FilePath -> Exp Bool

Checks for existence of file(s) (which can be a wildcard, or a directory). If you want to check to see if a file is a directory, use fileExists DIRECTORY/*.*.

 iff_ (fileExists "$WINDIR/notepad.exe") $
     messageBox [MB_OK] "notepad is installed"

findEach :: Exp FilePath -> (Exp FilePath -> Action ()) -> Action ()

Performs a search for filespec, running the action with each file found. If no files are found the error flag is set. Note that the filename output is without path.

 findEach "$INSTDIR/*.txt" $ \x ->
     detailPrint x

If you jump from inside the loop to after the loop then you may leak a search handle.

createDirectory :: Exp FilePath -> Action ()

Creates (recursively if necessary) the specified directory. Errors can be caught using onError. You should always specify an absolute path.

 createDirectory "$INSTDIR/some/directory"

createShortcut :: Exp FilePath -> [Attrib] -> Action ()

Creates a shortcut file that links to a Traget file, with optional Parameters. The icon used for the shortcut is IconFile,IconIndex. StartOptions should be one of: SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED. KeyboardShortcut should be in the form of 'flag|c' where flag can be a combination (using |) of: ALT, CONTROL, EXT, or SHIFT. c is the character to use (a-z, A-Z, 0-9, F1-F24, etc). Note that no spaces are allowed in this string. A good example is "ALT|CONTROL|F8". $OUTDIR is used for the working directory. You can change it by using setOutPath before creating the Shortcut. Description should be the description of the shortcut, or comment as it is called under XP. The error flag is set if the shortcut cannot be created (i.e. either of the paths (link or target) does not exist, or some other error).

 createDirectory "$SMPROGRAMS/My Company"
 createShortcut "$SMPROGRAMS/My Company/My Program.lnk"
    [Target "$INSTDIR/My Program.exe"
    ,Parameter "some command line parameters"
    ,IconFile "$INSTDIR/My Program.exe", IconIndex 2
    ,StartOptions "SW_SHOWNORMAL"
    ,KeyboardShortcut "ALT|CONTROL|SHIFT|F5"
    ,Description "a description"]

Registry manipulation

readRegStr :: HKEY -> Exp String -> Exp String -> Exp String

deleteRegKey :: HKEY -> Exp String -> Action ()

writeRegStr :: HKEY -> Exp String -> Exp String -> Exp String -> Action ()

writeRegDWORD :: HKEY -> Exp String -> Exp String -> Exp Int -> Action ()

Process execution

exec :: Exp String -> Action ()

Execute the specified program and continue immediately. Note that the file specified must exist on the target system, not the compiling system. $OUTDIR is used for the working directory. Errors can be caught using onError. Note, if the command could have spaces, you should put it in quotes to delimit it from parameters. e.g.: exec "\"$INSTDIR/command.exe\" parameters". If you don't put it in quotes it will not work on Windows 9x with or without parameters.

 exec "\"$INSTDIR/someprogram.exe\""
 exec "\"$INSTDIR/someprogram.exe\" some parameters"

Installer

Global installer options

name :: Exp String -> Action ()

Sets the name of the installer. The name is usually simply the product name such as 'MyApp' or 'Company MyApp'.

 name "MyApp"

outFile :: Exp FilePath -> Action ()

Specifies the output file that MakeNSIS should write the installer to. This is just the file that MakeNSIS writes, it doesn't affect the contents of the installer. Usually should end with .exe.

 outFile "installer.exe"

installDir :: Exp FilePath -> Action ()

Sets the default installation directory. Note that the part of this string following the last \ will be used if the user selects browse, and may be appended back on to the string at install time (to disable this, end the directory with a \). If this doesn't make any sense, play around with the browse button a bit.

 installDir "$PROGRAMFILES/MyApp"

setCompressor :: Compressor -> [Attrib] -> Action ()

installIcon :: Exp FilePath -> Action ()

Set the icon used for the installer/uninstaller.

 installIcon "$NSISDIR/Contrib/Graphics/Icons/modern-install.ico"

uninstallIcon :: Exp FilePath -> Action ()

Set the icon used for the installer/uninstaller.

 installIcon "$NSISDIR/Contrib/Graphics/Icons/modern-install.ico"

headerImage :: Maybe (Exp FilePath) -> Action ()

Set the image used for the header splash. Pass Nothing to use the default header image.

 headerImage $ Just "$NSISDIR/Contrib/Graphics/Header/win.bmp"

installDirRegKey :: HKEY -> Exp String -> Exp String -> Action ()

This attribute tells the installer to check a string in the registry, and use it for the install dir if that string is valid. If this attribute is present, it will override the installDir attribute if the registry key is valid, otherwise it will fall back to the installDir default. When querying the registry, this command will automatically remove any quotes. If the string ends in ".exe", it will automatically remove the filename component of the string (i.e. if the string is "C:program filesfoo/foo.exe", it will know to use "C:program filesfoo").

 installDirRegKey HKLM "Software/NSIS" ""
 installDirRegKey HKLM "Software/ACME/Thingy" "InstallLocation"

allowRootDirInstall :: Bool -> Action ()

caption :: Exp String -> Action ()

showInstDetails :: Visibility -> Action ()

showUninstDetails :: Visibility -> Action ()

Sections

data SectionId

Instances

Data SectionId

Show SectionId

Typeable SectionId

section :: Exp String -> [Attrib] -> Action () -> Action ()

sectionGroup :: Exp String -> [Attrib] -> Action () -> Action ()

newSectionId :: Action SectionId

sectionSetText :: SectionId -> Exp String -> Action ()

sectionGetText :: SectionId -> Exp String

uninstall :: Action () -> Action ()

page :: Page -> Action ()

unpage :: Page -> Action ()

Section commands

file :: [Attrib] -> Exp FilePath -> Action ()

alwaysNonFatal :: Action () -> Action ()

Set all file actions to automatically take NonFatal.

writeUninstaller :: Exp FilePath -> Action ()

Writes the uninstaller to the filename (and optionally path) specified. Only valid from within an install section, and requires that you have an uninstall section in your script. You can call this one or more times to write out one or more copies of the uninstaller.

 writeUninstaller "$INSTDIR/uninstaller.exe"

alert :: Exp String -> Action ()

Show an alert, equivalent to messageBox [MB_ICONEXCLAMATION].

setOutPath :: Exp FilePath -> Action ()

Sets the output path ($OUTDIR) and creates it (recursively if necessary), if it does not exist. Must be a full pathname, usually is just $INSTDIR.

 setOutPath "$INSTDIR"

messageBox :: [MessageBoxType] -> Exp String -> Action (Exp String)

requestExecutionLevel :: Level -> Action ()

hideProgress :: Action a -> Action a

While the action is executing, do not update the progress bar. Useful for functions which do a large amount of computation, or have loops.

detailPrint :: Exp String -> Action ()

Settings

data Compressor

Constructors

LZMA

ZLIB

BZIP2

Instances

Data Compressor

Show Compressor

Typeable Compressor

data HKEY

Constructors

HKCR

HKEY_CLASSES_ROOT

HKLM

HKEY_LOCAL_MACHINE

HKCU

HKEY_CURRENT_USER

HKU

HKEY_USERS

HKCC

HKEY_CURRENT_CONFIG

HKDD

HKEY_DYN_DATA

HKPD

HKEY_PERFORMANCE_DATA

SHCTX

SHELL_CONTEXT

Instances

Bounded HKEY

Enum HKEY

Eq HKEY

Data HKEY

Ord HKEY

Read HKEY

Show HKEY

Typeable HKEY

data MessageBoxType

Constructors

MB_OK

Display with an OK button

MB_OKCANCEL

Display with an OK and a cancel button

MB_ABORTRETRYIGNORE

Display with abort, retry, ignore buttons

MB_RETRYCANCEL

Display with retry and cancel buttons

MB_YESNO

Display with yes and no buttons

MB_YESNOCANCEL

Display with yes, no, cancel buttons

MB_ICONEXCLAMATION

Display with exclamation icon

MB_ICONINFORMATION

Display with information icon

MB_ICONQUESTION

Display with question mark icon

MB_ICONSTOP

Display with stop icon

MB_USERICON

Display with installer's icon

MB_TOPMOST

Make messagebox topmost

MB_SETFOREGROUND

Set foreground

MB_RIGHT

Right align text

MB_RTLREADING

RTL reading order

MB_DEFBUTTON1

Button 1 is default

MB_DEFBUTTON2

Button 2 is default

MB_DEFBUTTON3

Button 3 is default

MB_DEFBUTTON4

Button 4 is default

Instances

Bounded MessageBoxType

Enum MessageBoxType

Eq MessageBoxType

Data MessageBoxType

Ord MessageBoxType

Read MessageBoxType

Show MessageBoxType

Typeable MessageBoxType

data Attrib

Constructors

Solid

Final

RebootOK

NonFatal

Recursive

Unselected

Expanded

Description (Exp String)

Required

Target (Exp String)

Parameters (Exp String)

IconFile (Exp String)

IconIndex (Exp Int)

StartOptions String

KeyboardShortcut String

Id SectionId

Instances

Show Attrib

data Page

Constructors

License FilePath

Components

Directory

InstFiles

Confirm

Instances

Eq Page

Data Page

Ord Page

Read Page

Show Page

Typeable Page

data Level

Constructors

None

User

Highest

Admin

Instances

Bounded Level

Enum Level

Eq Level

Data Level

Ord Level

Read Level

Show Level

Typeable Level

data Visibility

Constructors

Hide

Show

NeverShow

Instances

Bounded Visibility

Enum Visibility

Eq Visibility

Data Visibility

Ord Visibility

Read Visibility

Show Visibility

Typeable Visibility

data FileMode

Mode to use with 'Development.

Constructors

ModeRead

Read a file.

ModeWrite

ModeAppend

Opened for both read and write, contents preserved.

Instances

Bounded FileMode

Enum FileMode

Eq FileMode

Data FileMode

Ord FileMode

Show FileMode

Typeable FileMode