Safe Haskell | Safe-Infered |
---|
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.
For examples, see the Examples source directory.
Much of the documentation from the Installer section is taken straight from the NSIS documentation.
- nsis :: Action () -> String
- nsisNoOptimise :: Action () -> String
- data Action a
- type Exp ty = Action (Value ty)
- data Value ty
- share :: Exp t -> (Exp t -> Action a) -> Action a
- scope :: Action a -> Action a
- constant :: Typeable t => String -> Exp t -> Action (Exp t)
- constant_ :: Exp t -> Action (Exp t)
- mutable :: Typeable t => String -> Exp t -> Action (Exp t)
- mutable_ :: Exp t -> Action (Exp t)
- (@=) :: Exp t -> Exp t -> Action ()
- mutableInt, constantInt :: String -> Exp Int -> Action (Exp Int)
- mutableInt_, constantInt_ :: Exp Int -> Action (Exp Int)
- mutableStr, constantStr :: String -> Exp String -> Action (Exp String)
- mutableStr_, constantStr_ :: Exp String -> Action (Exp String)
- iff :: Exp Bool -> Action () -> Action () -> Action ()
- iff_ :: Exp Bool -> Action () -> Action ()
- while :: Exp Bool -> Action () -> Action ()
- loop :: (Action () -> Action ()) -> Action ()
- onError :: Action () -> Action () -> Action ()
- (?) :: Exp Bool -> (Exp t, Exp t) -> Exp t
- (%&&), (%||) :: Exp Bool -> Exp Bool -> Exp Bool
- data Label
- newLabel :: Action Label
- label :: Label -> Action ()
- goto :: Label -> Action ()
- (%==), (%/=) :: Exp a -> Exp a -> Exp Bool
- (%<=), (%>), (%>=), (%<) :: Exp Int -> Exp Int -> Exp Bool
- true, false :: Exp Bool
- not_ :: Exp Bool -> Exp Bool
- strRead :: Exp String -> Exp Int
- strShow :: Exp Int -> Exp String
- (&) :: Exp String -> Exp String -> Exp String
- strConcat :: [Exp String] -> Exp String
- strLength :: Exp String -> Exp Int
- strTake :: Exp Int -> Exp String -> Exp String
- strDrop :: Exp Int -> Exp String -> Exp String
- strReplace :: Exp String -> Exp String -> Exp String -> Exp String
- strIsPrefixOf :: Exp String -> Exp String -> Exp Bool
- strUnlines :: [Exp String] -> Exp String
- data FileHandle
- fileOpen :: FileMode -> Exp FilePath -> Action (Exp FileHandle)
- fileWrite :: Exp FileHandle -> Exp String -> Action ()
- fileClose :: Exp FileHandle -> Action ()
- withFile' :: FileMode -> Exp FilePath -> (Exp FileHandle -> Action ()) -> Action ()
- writeFile' :: Exp FilePath -> Exp String -> Action ()
- writeFileLines :: Exp FilePath -> [Exp String] -> Action ()
- rmdir :: [Attrib] -> Exp FilePath -> Action ()
- delete :: [Attrib] -> Exp FilePath -> Action ()
- getFileTime :: Exp FilePath -> Exp String
- fileExists :: Exp FilePath -> Exp Bool
- findEach :: Exp FilePath -> (Exp FilePath -> Action ()) -> Action ()
- findOnce :: Exp FilePath -> Exp String
- createDirectory :: Exp FilePath -> Action ()
- createShortcut :: Exp FilePath -> [Attrib] -> Action ()
- 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 ()
- exec :: Exp String -> Action ()
- name :: Exp String -> Action ()
- outFile :: Exp FilePath -> Action ()
- installDir :: Exp FilePath -> Action ()
- setCompressor :: Compressor -> [Attrib] -> Action ()
- installIcon, uninstallIcon :: Exp FilePath -> Action ()
- headerImage :: Maybe (Exp FilePath) -> Action ()
- installDirRegKey :: HKEY -> Exp String -> Exp String -> Action ()
- allowRootDirInstall :: Bool -> Action ()
- caption :: Exp String -> Action ()
- showInstDetails :: Visibility -> Action ()
- showUninstDetails :: Visibility -> Action ()
- data 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 ()
- file :: [Attrib] -> Exp FilePath -> Action ()
- alwaysNonFatal :: Action () -> Action ()
- writeUninstaller :: Exp FilePath -> Action ()
- alert :: Exp String -> Action ()
- setOutPath :: Exp FilePath -> Action ()
- messageBox :: [MessageBoxType] -> Exp String -> Action (Exp String)
- requestExecutionLevel :: Level -> Action ()
- hideProgress :: Action a -> Action a
- detailPrint :: Exp String -> Action ()
- data Compressor
- data HKEY
- = 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
- data MessageBoxType
- data Attrib
- data Page
- = License
- | Components
- | Directory
- | InstFiles
- | Confirm
- data Level
- data Visibility
- data FileMode
- = ModeRead
- | ModeWrite
- | ModeAppend
Core types
nsis :: Action () -> StringSource
Create the contents of an NSIS script from an installer specification.
nsisNoOptimise :: Action () -> StringSource
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!).
Monad in which installers are defined. A useful command to start with is section
.
type Exp ty = Action (Value ty)Source
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
then any Exp
String
Int
variables used will be automatically shown (see strShow
).
If the string is
then it must be of the form Exp
ty"$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
.
Scripting
Variables
share :: Exp t -> (Exp t -> Action a) -> Action aSource
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 aSource
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_
xscope
$ doconstant
"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.
mutable :: Typeable t => String -> Exp t -> Action (Exp t)Source
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 abovealert
"$HELLO" -- with 2 exclamation marks
Typed variables
mutableInt, constantInt :: String -> Exp Int -> Action (Exp Int)Source
mutableInt_, constantInt_ :: Exp Int -> Action (Exp Int)Source
mutableStr, constantStr :: String -> Exp String -> Action (Exp String)Source
mutableStr_, constantStr_ :: Exp String -> Action (Exp String)Source
Control Flow
A code label, used for goto
programming, see newLabel
.
newLabel :: Action LabelSource
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 $ doiff_
cond1 $goto
abortiff_
cond2 $goto
abort var@=
strDrop
1 varlabel
abort
Note that the above example could have been written in a simpler manner with loop
.
Expressions
(%<=), (%>), (%>=), (%<) :: Exp Int -> Exp Int -> Exp BoolSource
The standard comparison operators, lifted to Exp
.
(&) :: Exp String -> Exp String -> Exp StringSource
Concatenate two strings, for example "$FOO" & "$BAR"
is equivalent
to "$FOO$BAR"
.
strTake :: Exp Int -> Exp String -> Exp StringSource
Take the first n
characters from a string, strTake 2 "test"
.
%==
"te"
strDrop :: Exp Int -> Exp String -> Exp StringSource
Drop the first n
characters from a string, strDrop 2 "test"
.
%==
"st"
strReplace :: Exp String -> Exp String -> Exp String -> Exp StringSource
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 BoolSource
Is the first string a prefix of the second.
strUnlines :: [Exp String] -> Exp StringSource
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
fileWrite :: Exp FileHandle -> Exp String -> Action ()Source
Write a string to a file openned with fileOpen
.
writeFileLines :: Exp FilePath -> [Exp String] -> Action ()Source
Write a file comprising of a set of lines.
createDirectory :: Exp FilePath -> Action ()Source
Creates (recursively if necessary) the specified directory. Errors can be caught
using onError
. You should always specify an absolute path.
createDirectory "$INSTDIR/some/directory"
Registry manipulation
Process execution
exec :: Exp String -> Action ()Source
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 ()Source
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 ()Source
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 ()Source
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 ()Source
installIcon, uninstallIcon :: Exp FilePath -> Action ()Source
Set the icon used for the installer/uninstaller.
installIcon "NSISDIR/Contrib/Graphics/Icons/modern-install.ico"
headerImage :: Maybe (Exp FilePath) -> Action ()Source
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 ()Source
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"
Sections
Section commands
writeUninstaller :: Exp FilePath -> Action ()Source
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"
setOutPath :: Exp FilePath -> Action ()Source
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)Source
hideProgress :: Action a -> Action aSource
Settings
data Compressor Source
Data Compressor | |
Show Compressor | |
Typeable Compressor | |
Default Compressor |
data MessageBoxType Source
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 |
data Visibility Source