\H{instr} Instructions

\S1{basicinstructions} Basic Instructions

The instructions that NSIS uses for scripting are sort of a cross between PHP and assembly. There are no real high level language constructs but the instructions themselves are (for the most part) high level, and you have handy string capability (i.e. you don't have to worry about concatenating strings, etc). You essentially have 25 registers (20 general purpose, 5 special purpose), and a stack.

\S2{delete} Delete

\c [/REBOOTOK] file

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 when trying to delete a file that does not exist.

\c Delete $INSTDIR\somefile.dat

\NsisWarnBlockContainerBegin
\\<b\\>Warning:\\</b\\> The /REBOOTOK switch requires administrator rights on Windows NT and later.
\NsisWarnBlockContainerEnd

\S2{exec} Exec

\c command

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 as the working directory. The error flag is set if the process could not be launched. 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 \e{not} work on Windows 9x with or without parameters.

\c Exec '"$INSTDIR\someprogram.exe"'
\c Exec '"$INSTDIR\someprogram.exe" some parameters'

\S2{execshell} ExecShell

\c [/INVOKEIDLIST] action file [parameters] [SW_SHOWDEFAULT | SW_SHOWNORMAL | SW_SHOWMAXIMIZED | SW_SHOWMINIMIZED | SW_HIDE]

Execute the specified file using ShellExecuteEx. Note that action is usually "open", "print", etc, but can be an empty string to use the default action. Parameters and the show type are optional. $OUTDIR is used as the working directory. The error flag is set if the process could not be launched.

\c ExecShell "open" "http://nsis.sf.net/"
\c ExecShell "" "$SysDir\Notepad.exe" "" SW_SHOWMAXIMIZED
\c ExecShell "print" "$INSTDIR\readme.txt"
\c ExecShell /INVOKEIDLIST "properties" "$TEMP"

\S2{execshellwait} ExecShellWait

\c [/INVOKEIDLIST] action file [parameters] [SW_SHOWDEFAULT | SW_SHOWNORMAL | SW_SHOWMAXIMIZED | SW_SHOWMINIMIZED | SW_HIDE]

Execute the specified file using ExecShell and wait for executed process to quit. It will only wait for executable files, not other file types nor URLs.

\S2{execwait} ExecWait

\c command [user_var(exit code)]

Execute the specified program and wait for the executed process to quit. See \R{exec}{Exec} for more information. If no output variable is specified \R{execwait}{ExecWait} sets the error flag if the program executed returns a nonzero error code, or if there is an error. If an output variable is specified, \R{execwait}{ExecWait} sets the variable with the exit code (and only sets the error flag if an error occurs; if an error occurs the contents of the user variable are undefined). Note, if the command could have spaces, you should put it in quotes to delimit it from parameters. e.g.: ExecWait '"$INSTDIR\\command.exe" parameters'. If you don't put it in quotes it will \e{not} work on Windows 9x with or without parameters.

\c ExecWait '"$INSTDIR\someprogram.exe"'
\c ExecWait '"$INSTDIR\someprogram.exe"' $0
\c DetailPrint "some program returned $0"

\S2{file} File

\c [/nonfatal] [/a] ([/r] [/x file|wildcard [...]] (file|wildcard) [...] | /oname=file.dat infile.dat)

Adds file(s) to be extracted to the current output path ($OUTDIR).

\b Note that the output file name is $OUTDIR\\filename_portion_of_file.

\b Use /oname=X switch to change the output name. X may contain variables and can be a fully qualified path or a relative path in which case it will be appended to $OUTDIR set by \R{setoutpath}{SetOutPath}. When using this switch, only one file can be specified. If the output name contains spaces, quote the entire parameter, including /oname, as shown in the examples below.

\b Wildcards are supported.

\b If the /r switch is used, matching files and directories are recursively searched for in subdirectories. If just one path segment is specified (e.g. \c{File /r something}), the current directory will be recursively searched. If more than one segment is specified (e.g. \c{File /r something\\*.*}), the last path segment will be used as the matching condition and anything before it specifies which directory to search recursively. If a directory name matches, all of its contents is added recursively. Directory structure is preserved.

\b Use the /x switch to exclude files and directories.

\b If the /a switch is used, the attributes of the file(s) added will be preserved.

\b The \R{file}{File} command sets the error flag if overwrite mode is set to 'try' and the file could not be overwritten, or if the overwrite mode is set to 'on' and the file could not be overwritten and the user selects ignore.

\b If the /nonfatal switch is used and no files are found, a warning will be issued instead of an error.

\c File something.exe
\c File /a something.exe
\c File *.exe
\c File /r *.dat
\c File /r data
\c File /oname=temp.dat somefile.ext
\c File /oname=$TEMP\temp.dat somefile.ext
\c File "/oname=$TEMP\name with spaces.dat" somefile.ext
\c File /nonfatal "a file that might not exist"
\c File /r /x CVS myproject\*.*
\c File /r /x *.res /x *.obj /x *.pch source\*.*

\\<b\\>Note:\\</b\\> when using the \e{/r} switch, both matching directories and files will be searched. This is always done with or without the use of wildcards, even if the given path perfectly matches one directory. That means, the following directory structure:

\c <DIR> something
\c   file.dat
\c   another.dat
\c <DIR> dir
\c   something
\c   <DIR> dir2
\c     file2.dat
\c <DIR> another
\c   <DIR> something
\c     readme.txt

with the following \e{File} usage:

\c File /r something

will match the directory named \e{something} in the root directory, the file named \e{something} in the directory named \e{dir} and the directory named \e{something} in the directory named \e{another}. To match only the directory named \e{something} in the root directory, use the following:

\c File /r something\*.*

When adding \e{\\*.*}, it will be used as the matching condition and \e{something} will be used as the directory to search. When only \e{something} is specified, the current directory will be recursively searched for every file and directory named \e{something} and \e{another\\something} will be matched.

\S2{rename} Rename

\c [/REBOOTOK] source_file dest_file

Rename source_file to dest_file. You can use it to move a file from anywhere on the system to anywhere else and you can move a directory to somewhere else on the same drive. The destination file must not exist or the move will fail (unless you are using /REBOOTOK). If /REBOOTOK is specified, and the file cannot be moved (if, for example, the destination exists), then the file is moved when the system reboots. If the file will be moved on a reboot, the reboot flag will be set. The error flag is set if the file cannot be renamed (and /REBOOTOK is not used) or if the source file does not exist.

If no absolute path is specified the current folder will be used. The current folder is the folder set using the last \R{setoutpath}{SetOutPath} instruction. If you have not used \R{setoutpath}{SetOutPath} the current folder is \R{varother}{$EXEDIR}.

\c Rename $INSTDIR\file.ext $INSTDIR\file.dat

\NsisWarnBlockContainerBegin
\\<b\\>Warning:\\</b\\> The /REBOOTOK switch requires administrator rights on Windows NT and later.
\NsisWarnBlockContainerEnd

\S2{reservefile} ReserveFile

\c [/nonfatal] [/r] [/x file|wildcard [...]] file [file...] | [/nonfatal] /plugin file.dll

Reserves a file in the data block for later use. Files are added to the compressed data block in the order they appear in the script. Functions, however, are not necessarily called in the order they appear in the script. Therefore, if you add a file in a function called early but put the function at the end of the script, all of the files added earlier will have to be decompressed to get to the required file. This process can take a long time if there a lot of files. \R{oninit}{.onInit} is one such function. It is called at the very beginning, before anything else appears. If you put it at the very end of the script, extract some files in it and have lots of files added before it, the installer might take a very long time to load. This is where this command comes useful, allowing you to speed up the loading process by including the file at the top of the data block instead of letting NSIS seek all the way down to the bottom of the \e{compressed} data block.

Use /plugin to reserve a plugin in $\{NSISDIR\}\\Plugins\\*.

See \R{file}{File} for more information about the parameters.

\S2{rmdir} RMDir

\c [/r] [/REBOOTOK] directory_name

Remove the specified directory (fully qualified path with no wildcards). Without /r, the directory will only be removed if it is completely empty. If /r 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 be 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.

\c RMDir $INSTDIR
\c RMDir $INSTDIR\data
\c RMDir /r /REBOOTOK $INSTDIR
\c RMDir /REBOOTOK $INSTDIR\DLLs

Note that the current working directory can not be deleted. The current working directory is set by \R{setoutpath}{SetOutPath}. For example, the following example will not delete the directory.

\c SetOutPath $TEMP\dir
\c RMDir $TEMP\dir

The next example will succeed in deleting the directory.

\c SetOutPath $TEMP\dir
\c SetOutPath $TEMP
\c RMDir $TEMP\dir

\NsisWarnBlockContainerBegin
\\<b\\>Warning:\\</b\\> Using \e{RMDir /r $INSTDIR} in the uninstaller is not safe. Though it is unlikely, the user might select to install to the root of the Program Files folder and this command would wipe out the entire Program Files folder, including all other installed programs! The user can also put other files in the installation folder and wouldn't expect them to get deleted along with the program. Solutions are \W{https://nsis.sourceforge.io/Uninstall_only_installed_files}{available} for easily uninstalling only files which were installed by the installer.
\NsisWarnBlockContainerEnd

\NsisWarnBlockContainerBegin
\\<b\\>Warning:\\</b\\> The /REBOOTOK switch requires administrator rights on Windows NT and later.
\NsisWarnBlockContainerEnd

\S2{setoutpath} SetOutPath

\c outpath

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 (you can specify $INSTDIR with a single "-" if you are lazy).

\c SetOutPath $INSTDIR
\c File program.exe