dragonleo/NSIS
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Documentation fixes and clarifications

Browse source 
git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@6728 212acab6-be3b-0410-9dea-997c60f758d6
This commit is contained in:
anders_k 2016-03-27 23:24:43 +00:00
parent 2b5baa3639
commit e7ac6581e4
39 changed files with 315 additions and 429 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Contrib/Makensisw/makensisw.cpp
View file

@ -50,8 +50,8 @@ NSIS_ENTRYPOINT_SIMPLEGUI
int WINAPI _tWinMain(HINSTANCE hInst,HINSTANCE hOldInst,LPTSTR CmdLineParams,int ShowCmd) {
HMODULE hK32 = LoadLibraryA("KERNEL32");
// We can be associated with .nsi and .nsh files and when launched from the shell we inherit the current directory
// so we need to prevent LoadLibrary from searching the current directory because it can contain untrusted DLLs!
// We can be associated with .nsi files and when launched from the shell we inherit the current directory so
// we need to prevent LoadLibrary from searching the current directory because it can contain untrusted DLLs!
FARPROC SDDA = GetProcAddress(hK32, "SetDllDirectoryA"); // WinXP.SP1+
if (SDDA) ((BOOL(WINAPI*)(LPCSTR))SDDA)(""); // Remove the current directory from the default DLL search order

56
Docs/src/attributes.but
View file

@ -2,7 +2,7 @@
\S1{attribgen} General Attributes
The commands below all adjust attributes of the installer. These attributes control how the installer looks and functions, including which pages are present in the installer, as what text is displayed in each part of each page, how the installer is named, what icon the installer uses, the default installation directory, what file it writes out, and more. Note that these attributes can be set anywhere in the file except in a \R{ssection}{Section} or \R{ffunction}{Function}.
The commands below all adjust attributes of the installer. These attributes control how the installer looks and functions, including which pages are present in the installer, which text is displayed in each part of each page, the name of the installer, the icon the installer uses, the default installation directory and more. Note that these attributes can be set anywhere in the file except in a \R{ssection}{Section} or \R{ffunction}{Function}.
\\<b\\>\\<u\\>Defaults are bold and underlined\\</u\\>\\</b\\>
@ -10,9 +10,9 @@ The commands below all adjust attributes of the installer. These attributes cont
\c (left|right|top|bottom) (width|height) [padding]
Adds a branding image on the top, bottom, left, or right of the installer. Its size will be set according to the width/height specified, the installer width/height and the installer font. The final size will not always be what you requested; have a look at the output of the command for the actual size. Because this depends on the installer font, you should use \R{asetfont}{SetFont} before \R{aaddbrandingimage}{AddBrandingImage}. The default padding value is 2.
Adds a branding image on the top, bottom, left, or right of the installer. Its size will be set according to the width/height specified, the installer width/height and the installers font. The final size will not always be what you requested; have a look at the output of the command for the actual size. Because this depends on the installers font, you should use \R{asetfont}{SetFont} before \R{aaddbrandingimage}{AddBrandingImage}. The default padding value is 2.
\R{aaddbrandingimage}{AddBrandingImage} only adds a placeholder for an image. To set the image itself on runtime, use \R{setbrandingimage}{SetBrandingImage}.
\R{aaddbrandingimage}{AddBrandingImage} only adds a placeholder for an image. To set the image itself at runtime, use \R{setbrandingimage}{SetBrandingImage}.
\c AddBrandingImage left 100
\c AddBrandingImage right 50
@ -24,7 +24,7 @@ Adds a branding image on the top, bottom, left, or right of the installer. Its s
\c true|\\<b\\>false\\</b\\>
Controls whether or not installs are enabled to the root directory of a drive, or directly into a network share. Set to 'true' to change the safe behavior, which prevents users from selecting C:\\ or \\\\Server\\Share as an install (and later on, uninstall) directory. For additional directory selection page customizability, see \R{onverifyinstdir}{.onVerifyInstDir}.
Controls whether or not installs are allowed in the root directory of a drive, or directly into a network share. Set to 'true' to change the safe behavior, which prevents users from selecting C:\\ or \\\\Server\\Share as an install (and later on, uninstall) directory. For additional directory selection page customizability, see \R{onverifyinstdir}{.onVerifyInstDir}.
\S2{aautoclosewindow} AutoCloseWindow
@ -36,7 +36,7 @@ Sets whether or not the install window automatically closes when completed. This
\c [font_face [height [weight] [/ITALIC] [/UNDERLINE] [/STRIKE]]]
Specifies the font used to show the text on the background gradient. To set the color use \R{abggradient}{BGGradient}. If no parameters are specified, the default font will be used. The default font is bold and italic Times New Roman.
Specifies the font used to show the text on the background gradient. To set the color use \R{abggradient}{BGGradient}. The default font will be used if no parameters are specified. The default font is bold and italic Times New Roman.
\S2{abggradient} BGGradient
@ -48,7 +48,7 @@ Specifies whether or not to use a gradient background window. If 'off', the inst
\c /TRIM(LEFT|RIGHT|CENTER) text
Sets the text that is shown (by default it is 'Nullsoft Install System vX.XX') at the bottom of the install window. Setting this to an empty string ("") uses the default; to set the string to blank, use " " (a space). If it doesn't matter to you, leave it the default so that everybody can know why the installer didn't suck. heh. Use /TRIMLEFT, /TRIMRIGHT or /TRIMCENTER to trim down the size of the control to the size of the string.
Sets the text that is shown at the bottom of the install window (by default it is 'Nullsoft Install System vX.XX'). Setting this to an empty string ("") uses the default; to set the string to blank, use " " (a space). If it doesn't matter to you, leave it the default so that everybody can know why the installer didn't suck :). Use /TRIMLEFT, /TRIMRIGHT or /TRIMCENTER to trim down the size of the control to the size of the string.
Accepts variables. If variables are used, they must be initialized on \R{oninit}{.onInit}.
@ -56,7 +56,7 @@ Accepts variables. If variables are used, they must be initialized on \R{oninit}
\c caption
When used outside a \R{pageex}{PageEx} block: Sets the text for the titlebar of the installer. the By default, it is 'Name Setup', where Name is specified with the \R{aname}{Name} instruction. You can, however, override it with 'MyApp Installer' or whatever. If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string).
When used outside a \R{pageex}{PageEx} block: Sets the text for the titlebar of the installer. By default it is '$(^Name) Setup', where Name is specified by the \R{aname}{Name} instruction. You can however override it with 'MyApp Installer' or whatever. If you specify an empty string (""), the default will be used (you can specify " " to simulate a empty string).
When used inside a \R{pageex}{PageEx} block: Sets the subcaption of the current page.
@ -66,7 +66,7 @@ Accepts variables. If variables are used, they must be initialized on \R{oninit}
\c dialog ui_file.exe
Replaces dialog (\e{IDD_LICENSE}, \e{IDD_DIR}, \e{IDD_SELCOM}, \e{IDD_INST}, \e{IDD_INSTFILES}, \e{IDD_UNINST} or \e{IDD_VERIFY}) by a dialog with the same resource ID in ui_file.exe. You can also specify 'all' as the dialog if you wish to replace all 7 of the dialogs at once from the same UI file. For some example UIs look at Contrib\\UIs under your NSIS directory.
Replaces dialog (\e{IDD_LICENSE}, \e{IDD_DIR}, \e{IDD_SELCOM}, \e{IDD_INST}, \e{IDD_INSTFILES}, \e{IDD_UNINST} or \e{IDD_VERIFY}) with a dialog from ui_file.exe with the same resource ID. You can also specify 'all' as the dialog if you wish to replace all 7 of the dialogs at once from the same UI file. For some example UIs look at Contrib\\UIs under your NSIS directory.
\b \e{IDD_LICENSE} must contain \e{IDC_EDIT1} (RICHEDIT control).
@ -88,7 +88,7 @@ Replaces dialog (\e{IDD_LICENSE}, \e{IDD_DIR}, \e{IDD_SELCOM}, \e{IDD_INST}, \e{
\c bitmap.bmp
Specifies the bitmap with the images used for the checks of the component-selection page treeview.
Specifies the bitmap with the checkbox images used in the component-selection page treeview.
This bitmap should have a size of 96x16 pixels, no more than 8bpp (256 colors) and contain six 16x16 images for the different states (in order: selection mask, not checked, checked, greyed out, unchecked & read-only, checked & read-only). Use magenta as mask color (this area will be transparent).
@ -124,7 +124,7 @@ Specifies whether or not the installer will perform a CRC on itself before allow
\S2{adetailsbuttontext} DetailsButtonText
\c show details text
\c show_details_text
Replaces the default details button text of "Show details", if parameter is specified (otherwise the default is used).
@ -152,7 +152,7 @@ Accepts variables. If variables are used, they must be initialized before the di
\c user_var(dir input/output)
Specifies which variable is to be used to contain the directory selected. This variable should contain the default value too. This allows to easily create two different directory pages that will not require you to move values in and out of $INSTDIR. The default variable is $INSTDIR. This can only be used in \R{pageex}{PageEx} and for directory and uninstConfirm pages.
Specifies which variable is to be used to contain the directory selected. This variable should be initialized with a default value. This allows you to easily create two different directory pages that will not require you to move values in and out of $INSTDIR. The default variable is $INSTDIR. This can only be used in \R{pageex}{PageEx} for directory and uninstConfirm pages.
\c Var ANOTHER_DIR
\c PageEx directory
@ -179,7 +179,7 @@ If `\R{adirverify}{DirVerify} leave' is used, the Next button will not be disabl
\S2{a} FileErrorText
\c file error text
\c file_error_text [noignore_file_error_text]
Replaces the default text that comes up when a file cannot be written to. This string can contain a reference to $0, which is the filename ($0 is temporarily changed to this value). Example: "Can not write to file $\\r$\\n$0$\\r$\\ngood luck.".
@ -189,11 +189,11 @@ Accepts variables. If variables are used, they must be initialized before \R{fil
\c [path\]icon.ico
Sets the icon of the installer. Every icon in the icon file will be included in the installer. Use \R{auninstallicon}{UninstallIcon} to set the uninstaller icon.
Sets the icon of the installer. Every image in the icon file will be included in the installer. Use \R{auninstallicon}{UninstallIcon} to set the uninstaller icon.
\S2{ainstallbuttontext} InstallButtonText
\c install button text
\c install_button_text
If parameter is specified, overrides the default install button text (of "Install") with the specified text.
@ -215,7 +215,7 @@ Sets the default installation directory. See the \R{variables}{variables section
\c root_key subkey key_name
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 \R{ainstalldir}{InstallDir} attribute if the registry key is valid, otherwise it will fall back to the \R{ainstalldir}{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 Files\\Foo\\app.exe", it will know to use "C:\\Program Files\\Foo"). For more advanced install directory configuration, set $INSTDIR in .onInit.
This attribute tells the installer to check a string in the registry and use it as the install dir if that string is valid. If this attribute is present, it will override the \R{ainstalldir}{InstallDir} attribute if the registry key is valid, otherwise it will fall back to the \R{ainstalldir}{InstallDir} value. 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 Files\\Foo\\app.exe", it will know to use "C:\\Program Files\\Foo"). For more advanced install directory configuration, set $INSTDIR in .onInit.
Language strings and variables cannot be used with \R{ainstalldirregkey}{InstallDirRegKey}.
@ -246,9 +246,9 @@ Sets the background color of the license data. Color is specified using the form
\c licdata.(txt|rtf)
Specifies a text file or a RTF file to use for the license that the user can read. Omit this to not have a license displayed. Note that the file must be in the evil DOS text format (\\r\\n, yeah!). To define a multilingual license data use \R{licenselangstring}{LicenseLangString}.
Specifies a text file or a RTF file to use for the license that the user can read. Omit this to not have a license displayed. Note that the file must be in DOS text format (\\r\\n). To define a multilingual license data use \R{licenselangstring}{LicenseLangString}.
If you make your license file a RTF file it is recommended you edit it with WordPad and not MS Word. Using WordPad will result in a much smaller file.
If you are using a RTF file it is recommended that you edit it with WordPad and not MS Word. Using WordPad will result in a much smaller file.
Use \R{licenselangstring}{LicenseLangString} to show a different license for every language.
@ -256,7 +256,7 @@ Use \R{licenselangstring}{LicenseLangString} to show a different license for eve
\c (checkbox [accept_text] | radiobuttons [accept_text] [decline_text] | \\<b\\>off\\</b\\>)
Specifies if the displayed license must be accept explicit or not. This can be done either by a checkbox or by radiobuttons. By default the "next button" is disabled and will only be enabled if the checkbox is enabled or the right radio button is selected. If off is specified the "next button" is enabled by default.
Specifies if the displayed license must be explicitly accepted or not. This can be done either by a checkbox or by radiobuttons. By default the "next button" is disabled and will only be enabled if the checkbox is enabled or the correct radio button is selected. If off is specified the "next button" is enabled by default.
\c LicenseForceSelection checkbox
\c LicenseForceSelection checkbox "i accept"
@ -293,13 +293,13 @@ See \W{http://msdn.microsoft.com/en-us/library/dd464660}{MSDN} for more informat
\c none|all|WinVista|\\<b\\>Win7|Win8|Win8.1|Win10\\</b\\>|{GUID} [...]
Declare that the installer is compatible with the specified Windows version(s). This adds a SupportedOS entry in the compatibility section of the application manifest. The default list of Win7+8+8.1+10 will probably be updated to include newer Windows versions in the future. \e{none} is the default if \R{arequestexecutionlevel}{RequestExecutionLevel} is set to \e{none} for compatibility reasons.
Declare that the installer is compatible with the specified Windows version(s). This adds a SupportedOS entry in the compatibility section of the application manifest. The default is Win7+8+8.1+10. \e{none} is the default if \R{arequestexecutionlevel}{RequestExecutionLevel} is set to \e{none} for compatibility reasons.
Windows 8.1 and later will fake its version number if you don't declare support for that particular version. You can read more about the other changes in behavior on \W{http://msdn.microsoft.com/en-us/library/windows/desktop/hh848036}{MSDN}.
\S2{amiscbuttontext} MiscButtonText
\c [back button text [next button text] [cancel button text] [close button text]]
\c [back_button_text [next_button_text] [cancel_button_text] [close_button_text]]
Replaces the default text strings for the four buttons (< Back, Next >, Cancel and Close). If parameters are omitted, the defaults are used.
@ -329,7 +329,7 @@ Specifies the output file that the MakeNSIS should write the installer to. This
Specifies the requested execution level for Windows Vista and higher. The value is embedded in the installer and uninstaller's XML manifest and tells Windows which privilege level the installer requires. \e{user} requests the user's normal level with no administrative privileges. \e{highest} will request the highest execution level available for the current user and will cause Windows to prompt the user to verify privilege escalation if they are a member of the administrators group. The prompt might request for the user's password. \e{admin}, which is also the default, requests administrator level and will cause Windows to prompt the user as well. Specifying \e{none} will keep the manifest empty and let Windows decide which execution level is required. Windows automatically identifies NSIS installers and decides administrator privileges are required. Because of this, \e{none} and \e{admin} have virtually the same effect.
It's recommended, at least by Microsoft, that every application is marked with a required execution level. Unmarked installers are subject to compatibility mode. Workarounds of this mode include automatically moving any shortcuts created in the user's start menu to all users' start menu. Installers that don't install anything into system folders nor write to the local machine registry (HKLM) should specify \e{user} execution level.
It's recommended that every application is marked with a required execution level. Unmarked installers are subject to compatibility mode. Workarounds of this mode include automatically moving any shortcuts created in the user's start menu to all users' start menu. Installers that don't install anything into system folders nor write to the local machine registry (HKLM) should specify \e{user} execution level.
More information about this topic can be found on \W{http://msdn.microsoft.com/en-us/library/bb756929}{MSDN}.
@ -370,13 +370,13 @@ See \k{silent} for more information.
\c \\<b\\>normal\\</b\\>|silent
Specifies whether or not the uninstaller should be silent. If it is 'silent' or 'silentlog', the uninstall section will run quietly, with no screen output from the uninstaller itself (the script can still display whatever it wants, use \R{messagebox}{MessageBox}'s /SD to specify a default for silent installers). Note that if this is set to 'normal' and the user runs the uninstaller with /S on the command line, it will behave as if \R{asilentuninstall}{SilentUnInstall} 'silent' was used. Note: see also \R{logset}{LogSet}.
Specifies whether or not the uninstaller should be silent. If it is 'silent' the uninstall sections will run quietly, with no screen output from the uninstaller itself (the script can still display whatever it wants, use \R{messagebox}{MessageBox}'s /SD to specify a default for silent uninstallers). Note that if this is set to 'normal' and the user runs the uninstaller with /S on the command line, it will behave as if \R{asilentuninstall}{SilentUnInstall} 'silent' was used.
See \k{silent} for more information.
\S2{aspacetexts} SpaceTexts
\c [req text [avail text]]
\c [req_text [avail_text]]
If parameters are specified, overrides the space required and space available text ("Space required: " and "Space available: " by default). If 'none' is specified as the required text no space texts will be shown.
@ -396,7 +396,7 @@ Accepts variables. If variables are used, they must be initialized before the re
\c text
Changes the text of the button that by default says "Uninstall" in the uninstaller. If no parameter is specified, the default text is used. See also \R{writeuninstaller}{WriteUninstaller} (replaces UninstallEXEName).
Changes the text of the button that by default says "Uninstall" in the uninstaller. If no parameter is specified, the default text is used.
Accepts variables. If variables are used, they must be initialized before the uninstall button shows.
@ -404,7 +404,7 @@ Accepts variables. If variables are used, they must be initialized before the un
\c caption
Sets what the titlebars of the uninstaller will display. By default, it is 'Name Uninstall', where Name is specified with the Name command. You can, however, override it with 'MyApp uninstaller' or whatever. If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string).
Sets what the titlebars of the uninstaller will display. By default it is '$(^Name) Uninstall', where Name is specified with the Name command. You can, however, override it with 'MyApp uninstaller' or whatever. If you specify an empty string (""), the default will be used (you can specify " " to simulate a empty string).
Accepts variables. If variables are used, they must be initialized in \R{unonInit}{un.onInit}.
@ -418,7 +418,7 @@ Sets the icon of the uninstaller.
\c page_number subcaption
Sets the default subcaptions for the uninstaller pages (0=": Confirmation",1=": Uninstalling Files",2=": Completed"). If you specify an empty string (""), the default will be used (you can however specify " " to achieve a blank string).
Sets the default subcaptions for the uninstaller pages (0=": Confirmation",1=": Uninstalling Files",2=": Completed"). If you specify an empty string (""), the default will be used (you can specify " " to simulate a empty string).
You can also set a subcaption (or override the default) using \R{acaption}{Caption} inside a \R{pageex}{PageEx} block.
@ -440,10 +440,10 @@ Accepts variables. If variables are used, they must be initialized before the un
\c \\<b\\>on\\</b\\>|off
Sets whether or not the installer's icon is being displayed.
Sets whether or not the installer's icon is displayed on certain pages.
\S2{axpstyle} XPStyle
\c on|\\<b\\>off\\</b\\>
Sets whether or not an XP manifest will be added to the installer. An XP manifest makes the installer controls use the new XP style when running on Windows XP. This affects the uninstaller too.
Sets whether or not a XP visual style manifest will be added to the installer. This manifest makes the installers controls use the new visual styles when running on Windows XP and later. This affects the uninstaller too.

16
Docs/src/basic.but
View file

@ -2,13 +2,13 @@
\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.
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 from trying to delete a file that does not exist.
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
@ -16,7 +16,7 @@ Delete file (which can be a file or wildcard, but should be specified with a ful
\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 for 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.
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'
@ -25,7 +25,7 @@ Execute the specified program and continue immediately. Note that the file speci
\c action command [parameters] [SW_SHOWDEFAULT | SW_SHOWNORMAL | SW_SHOWMAXIMIZED | SW_SHOWMINIMIZED | SW_HIDE]
Execute the specified program using ShellExecute. 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 for the working directory. The error flag is set if the process could not be launched.
Execute the specified program using ShellExecute. 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 "open" "$INSTDIR\readme.txt"
@ -53,9 +53,9 @@ Adds file(s) to be extracted to the current output path ($OUTDIR).
\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 the rest for the directory to search recursively. If a directory name matches, all of its contents is added recursively. Directory structure is preserved.
\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 or directories.
\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.
@ -92,7 +92,7 @@ with the following \e{File} usage:
\c File /r something
will match the directory named \e{something} on 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} on the root directory, use the following:
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\*.*
@ -122,7 +122,7 @@ See \R{file}{File} for more information about the parameters.
\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 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.
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

10
Docs/src/build.but
View file

@ -1,6 +1,6 @@
\A{build} Building NSIS
NSIS version 2.07 introduced a new build system, based on \W{http://www.scons.org/}{SCons}. The build system can build the entire NSIS package so there is no longer need to build it project by project. It allows building using several simultaneous jobs, installation without an installer on both Windows and POSIX and easy compilation with debugging symbols.
NSIS version 2.07 introduced a new build system, based on \W{http://www.scons.org/}{SCons}. The build system can build the entire NSIS package so you no longer need to build it project by project. It allows building using several simultaneous jobs, installation without an installer on both Windows and POSIX and easy compilation with debugging symbols.
\#{ MSVC6.SP5 direct link: http://web.archive.org/web/20060509123628/http://download.microsoft.com/download/vstudio60ent/SP5/Wideband-Full/WIN98Me/EN-US/vs6sp5.exe }
The official release is built with MSVC6 \W{http://web.archive.org/web/20060509123628/http://msdn2.microsoft.com/en-us/vstudio/aa718363.aspx}{Service Pack 5} \W{http://dl.dropbox.com/u/20029891/vs6sp5.exe}{(Mirror)} with the \W{http://wayback.archive.org/web/20100923113933/http://msdn.microsoft.com/en-us/vstudio/aa718349.aspx}{Processor Pack} and the February 2003 Platform SDK (5.2.3790.0).
@ -9,7 +9,7 @@ The official release is built with MSVC6 \W{http://web.archive.org/web/200605091
Source code is available in \W{http://nsis.svn.sourceforge.net/viewvc/nsis/}{SVN} and as a separate package with every \W{http://sourceforge.net/project/showfiles.php?group_id=22049}{NSIS distribution}.
To build NSIS \W{http://www.python.org/}{Python}, \W{http://www.scons.org/}{SCons} must be installed. Currently, the supported version of SCons is version 1.2.0 and above. Any version of Python above 1.6 is supported.
To build NSIS, \W{http://www.python.org/}{Python} and \W{http://www.scons.org/}{SCons} must be installed. Currently, the supported version of SCons is version 1.2.0 and above. Any version of Python above 1.6 is supported.
NSIS uses the \W{http://zlib.net}{zlib} compression library. As a
consequence the header and library files of zlib must be installed.
@ -19,7 +19,7 @@ installed via a package manager (apt-get, aptitude, rpm, yum) on POSIX
platforms. Another option is to build zlib from scratch and install it.
For Windows it is recommended to download \W{http://zlib.net}{zlib} from
\W{http://nsis.sourceforge.net/Zlib}{http://nsis.sourceforge.net/Zlib}.
\W{http://nsis.sf.net/Zlib}{http://nsis.sf.net/Zlib}.
Extract the contents of this zip archive to a folder of your choice, e.g.
\c{C:\\dev\\zlib-1.2.7} and set an environment variable named \c{ZLIB_W32}
containing this path.
@ -27,7 +27,7 @@ containing this path.
\c C:\>set ZLIB_W32=C:\dev\zlib-1.2.7
Alternatively the command line option ZLIB_W32 specifying the path
could be passed with scons instead of the environment variable.
can be passed to scons instead of the environment variable.
\c C:\dev\nsis>scons ZLIB_W32=C:\dev\zlib-1.2.7
@ -91,7 +91,7 @@ In case of errors about the compiler or the Platform SDK not being found, use:
\c set VCToolkitInstallDir=C:\Path\To\VCToolkit
\c scons MSTOOLKIT=yes
The open-source \W{http://www.mingw.org/}{MinGW} can also be used to for building, but this results in noticeably larger installers. Borland C++ or Open Watcom C/C++ might also work, but haven't been tested.
The open-source \W{http://www.mingw.org/}{MinGW} can also be used to for building but this results in noticeably larger installers. Borland C++ or Open Watcom C/C++ might also work, but haven't been tested.
To compile the documentation as a CHM file, hhc.exe must be in the PATH. It is available as part of \W{http://wayback.archive.org/web/20121021033631/http://msdn.microsoft.com/en-us/library/ms669985}{HTML Help Workshop}.

4
Docs/src/callback.but
View file

@ -1,6 +1,6 @@
\S1{callbacks} Callback Functions
You can create callback functions which have special names, that will be called by the installer at certain points in the install. Below is a list of currently available callbacks:
You can create callback functions (which have special names), that will be called by the installer at certain points in the install. Below is a list of available callbacks:
\S2{instcallbacks} Install Callbacks
@ -116,7 +116,7 @@ Example:
\S3{onverifyinstdir} .onVerifyInstDir
This callback enables control over whether or not an installation path is valid for your installer. This code will be called every time the user changes the install directory, so it shouldn't do anything crazy with \R{messagebox}{MessageBox} or the likes. If this function calls \R{abort}{Abort}, the installation path in $INSTDIR is deemed invalid.
This callback enables control over whether or not an installation path is valid for your installer. This code will be called every time the user changes the install directory, so it shouldn't do anything crazy with \R{messagebox}{MessageBox} or the like. If this function calls \R{abort}{Abort}, the installation path in $INSTDIR is deemed invalid.
Example:

55
Docs/src/compiler.but
View file

@ -2,7 +2,7 @@
\S0{compcommands} Compiler Utility Commands
These commands are similar to the C preprocessor in terms of purpose and functionality. They allow file inclusion, conditional compilation, executable header packing, and processes execution during the build process. Note: None of these commands allow the use of variables.
These commands are similar to the C preprocessor in terms of purpose and functionality. They allow file inclusion, conditional compilation, executable header packing and process execution during the build process. Note: None of these commands allow the use of variables.
Number literals support the \c{0b}, \c{0o}, \c{0n} and \c{0x} radix prefixes (base 2, 8, 10 and 16 respectively). Note: The deprecated plain \c{0} octal prefix is also supported in some places but its usage is discouraged.
@ -24,7 +24,7 @@ This command will include 'file' as if it was part of the original script. Note
\c directory
Adds another include directory to the include directories list. This list is searched when \R{include}{!include} is used. This list's initial value is $\{NSISDIR\}\\Include alone.
Adds another include directory to the include directories list. This list is searched when \R{include}{!include} is used. This list's initial value is $\{NSISDIR\}\\Include.
\c !addincludedir ..\include
\c !include something.nsh
@ -35,7 +35,7 @@ Adds another include directory to the include directories list. This list is sea
Causes the NSIS compiler to scan the given directory for plug-in DLLs. If you don't specify the plug-in architecture it is assumed to match the current target architecture. If the architecture does not match the installer will probably crash!
\c !addplugindir myplugin
\c !addplugindir ..\myplugin
\c MyPlugin::SomeFunction
\S1{appendfile} !appendfile
@ -63,7 +63,7 @@ This command will change the compiler to the new directory, new_path. new_path c
\S1{delfile} !delfile
\c file
\c [/nonfatal] file
This command deletes a file.
@ -97,7 +97,7 @@ This command will execute 'command' using a call to CreateProcess(). Unlike \R{s
On POSIX platforms, \R{execute}{!execute} will use system() just like \R{system}{!system}.
\c !execute '"%WINDIR%\notepad.exe" "${NSISDIR}\license.txt"'
\c !execute '"$%WINDIR%\notepad.exe" /P "${NSISDIR}\COPYING"'
\S1{makensis} !makensis
@ -120,7 +120,7 @@ This option makes the compiler use an external EXE packer (such as \W{http://www
\c command
This option will execute 'command' using a call to system() after the output EXE has been generated. You can typically use it to sign (Authenticode) your installer. If 'command' contains a '%1' it will be replaced by the executable filename.
This option will execute 'command' using a call to system() after the output EXE has been generated. You can typically use it to sign (Authenticode) your installer. If 'command' contains a '%1' it will be replaced by the executables filename.
\c !finalize 'sign.bat "%1" "Product Installer" http://example.com'
@ -130,7 +130,7 @@ This option will execute 'command' using a call to system() after the output EXE
This command will execute 'command' using a call to system(). You can store the return value in a define ('symbol') or halt execution if the return value compared (using 'compare') to 'comparevalue' is false. 'compare' can be '<' or '>' or '<>' or '='.
\c !system '"%WINDIR%\notepad.exe" "${NSISDIR}\license.txt"'
\c !system '"%WINDIR%\notepad.exe" "${NSISDIR}\COPYING"'
\c !system 'echo !define something > newinclude.nsh'
\c !include newinclude.nsh
\c !ifdef something
@ -149,10 +149,10 @@ This command creates a temporary file. It puts its path into a define, named \e{
\c !tempfile FILE
\c !define /date DATE "%H:%M:%S %d %b, %Y"
\c !system 'echo built on ${DATE} > "${FILE}"'
\c !undef DATE
\c File /oname=build.txt "${FILE}"
\c !delfile "${FILE}"
\c !undef FILE
\c !undef DATE
\S1{ppgetdllversion} !getdllversion
@ -160,7 +160,7 @@ This command creates a temporary file. It puts its path into a define, named \e{
This is similar to \R{getdllversionlocal}{GetDLLVersionLocal}, only it stores the version number in defines and can therefore be used anywhere, not just inside functions and sections.
\c !getdllversion "$%windir%\explorer.exe" expv_
\c !getdllversion "$%WINDIR%\Explorer.exe" expv_
\c !echo "Explorer.exe version is ${expv_1}.${expv_2}.${expv_3}.${expv_4}"
\S1{warning} !warning
@ -224,7 +224,7 @@ NSIS version used to build the script.
\S1{prensispackedversion} $\{NSIS_PACKEDVERSION\}
NSIS version as a 32 bit number.
NSIS version as a 32-bit number.
\c !if 0x3014000 >= "${NSIS_PACKEDVERSION}"
\c !error "NSIS 3.15 or higher is required to build this installer!"
@ -244,39 +244,26 @@ The size of a pointer (in bytes) in the generated installer.
A Unicode (UCS-4) character.
\c !define U+ABC "SIS" # Define will override
\c DetailPrint "${U+2115}${U+ABC}" # DOUBLE-STRUCK CAPITAL N + "SIS"
\c DetailPrint "${U+2115}SIS" # DOUBLE-STRUCK CAPITAL N + "SIS"
\S1{scopepredefines} Scope Predefines
Standard predefines that contain information of the current code scope.
Standard predefines that contain information about the current code scope.
\S2{prescopeglobal} $\{__GLOBAL__\}
Defined in the global scope.
\c Section test
\c
\c !ifdef ${__GLOBAL__}
\c !error "this shouldn't be here!"
\c !endif
\c
\c SectionEnd
\c
\c Function test
\c
\c !ifdef ${__GLOBAL__}
\c !error "this shouldn't be here!"
\c !endif
\c
\c FunctionEnd
\c
\c PageEx instfiles
\c
\c !ifdef ${__GLOBAL__}
\c !error "this shouldn't be here!"
\c !endif
\c
\c PageExEnd
\S2{prescopesection} $\{__SECTION__\}
@ -288,7 +275,6 @@ Defined as the section name, without any prefixes, in \R{ssection}{section} scop
\c !endif
\c
\c Section test
\c
\c !ifndef __SECTION__
\c !error "missing predefine!"
\c !endif
@ -296,23 +282,18 @@ Defined as the section name, without any prefixes, in \R{ssection}{section} scop
\c !if ${__SECTION__} != test
\c !error "wrong predefine value!"
\c !endif
\c
\c SectionEnd
\c
\c Section !test
\c
\c !if ${__SECTION__} != test
\c !error "wrong predefine value!"
\c !endif
\c
\c SectionEnd
\c
\c Section un.test
\c
\c !if ${__SECTION__} != test
\c !error "wrong predefine value!"
\c !endif
\c
\c SectionEnd
\S2{prescopefunction} $\{__FUNCTION__\}
@ -324,7 +305,6 @@ Defined as the function name, without any prefixes, in \R{ffunction}{function} s
\c !endif
\c
\c Function test
\c
\c !ifndef __FUNCTION__
\c !error "missing predefine!"
\c !endif
@ -332,15 +312,12 @@ Defined as the function name, without any prefixes, in \R{ffunction}{function} s
\c !if ${__FUNCTION__} != test
\c !error "wrong predefine value!"
\c !endif
\c
\c FunctionEnd
\c
\c Function un.test
\c
\c !if ${__FUNCTION__} != test
\c !error "wrong predefine value!"
\c !endif
\c
\c FunctionEnd
\S2{prescopepageex} $\{__PAGEEX__\}
@ -352,7 +329,6 @@ Defined as the page type in \R{pageex}{PageEx} scope.
\c !endif
\c
\c PageEx instfiles
\c
\c !ifndef __PAGEEX__
\c !error "missing predefine!"
\c !endif
@ -360,7 +336,6 @@ Defined as the page type in \R{pageex}{PageEx} scope.
\c !if ${__PAGEEX__} != instfiles
\c !error "wrong page type"
\c !endif
\c
\c PageExEnd
\S2{prescopeuninstall} $\{__UNINSTALL__\}
@ -372,19 +347,15 @@ Defined in \R{ssection}{section}, \R{ffunction}{function} or \R{pageex}{PageEx}
\c !endif
\c
\c Function test
\c
\c !ifdef __UNINSTALL__
\c !error "this shouldn't be here!"
\c !endif
\c
\c FunctionEnd
\c
\c Function un.test
\c
\c !ifndef __UNINSTALL__
\c !error "missing predefine!"
\c !endif
\c
\c FunctionEnd
\S2{prescopemacro} $\{__MACRO__\}
@ -395,4 +366,4 @@ Defined as the name of the current macro.
\S1{compenvvar} $%envVarName%
$%envVarName% will be replaced on compile time by the environment variable envVarName.
$%envVarName% will be replaced at compile time by the environment variable envVarName.

18
Docs/src/compilerflags.but
View file

@ -1,6 +1,6 @@
\S1{flags} Compiler Flags
The following commands affect how the compiler generates code and compresses data. Unless otherwise noted, these commands are valid anywhere in the script, and effect every line below where each one is placed (until overridden by another command). They cannot be jumped over using \R{flowcontrol}{flow control instructions}.
The following commands affect how the compiler generates code and compresses data. Unless otherwise noted, these commands are valid anywhere in the script and affect every line below where each one is placed (until overridden by another command). They cannot be jumped over using \R{flowcontrol}{flow control instructions}.
For example, in the following script, blah.dat will never be overwritten.
@ -25,7 +25,7 @@ Instead, the following should be used.
\c \\<b\\>on\\</b\\>|off
This command specifies whether the user should be able to skip a file or not. A user has an option to skip a file if \R{asetoverwrite}{SetOverwrite} is set to on (default) and the installer fails to open a file for writing when trying to extract a file. If \e{off} is used the ignore button which allows the user to skip the file will not show and the user will only have an option to abort the installation (Cancel button) or retry opening the file for writing (Retry button). If \e{on} is used the user will have an option to skip the file (error flag will be set - see \R{asetoverwrite}{SetOverwrite}).
This command specifies whether the user should be able to skip a file or not. A user has an option to skip a file if \R{asetoverwrite}{SetOverwrite} is set to on (default) and the installer fails to open a file for writing when trying to extract a file. If \e{off} is used the ignore button which allows the user to skip the file will not be shown and the user will only have an option to abort the installation (Cancel button) or retry opening the file for writing (Retry button). If \e{on} is used the user will have an option to skip the file (error flag will be set - see \R{asetoverwrite}{SetOverwrite}).
\S2{afilebufsize} FileBufSize
@ -45,7 +45,7 @@ Note that this option has no effect when solid compression is used.
\c [/SOLID] [/FINAL] \\<b\\>zlib\\</b\\>|bzip2|lzma
This command sets the compression algorithm used to compress files/data in the installer. It can only be used outside of sections and functions and before any data is compressed. Different compression methods can not be used for different files in the same installer. It is recommended to use it on the very top of the script to avoid compilation errors.
This command sets the compression algorithm used to compress files/data in the installer. It can only be used outside of sections and functions and before any data is compressed. Different compression methods can not be used for different files in the same installer. It is recommended to use it at the very top of the script to avoid compilation errors.
Three compression methods are supported: ZLIB, BZIP2 and LZMA.
@ -69,7 +69,7 @@ Sets the dictionary size in megabytes (MB) used by the LZMA compressor (default
\c \\<b\\>on\\</b\\>|off
This command tells the compiler whether or not to do datablock optimizations. Datablock optimizations have the compiler check to see if any data being added to the data block is already in the data block, and if so, it is simply referenced as opposed to added (can save a little bit of size). It is highly recommended to leave this option on.
This command tells the compiler whether or not to do datablock optimizations. Datablock optimizations causes the compiler to check to see if any data being added to the data block is already in the data block, and if so, it is simply referenced as opposed to added (can save a little bit of size). It is highly recommended to leave this option on.
\S2{asetdatesave} SetDateSave
@ -99,8 +99,8 @@ Generate a \R{intro-unicode}{Unicode installer}. It can only be used outside of
\c [/LANG=lang_id] keyname value
Adds a field in the Version Tab of the File Properties. This can either be a field provided by the system or a user defined field.
The following fields are provided by the System:
Adds a string entry to the version information stored in the installer and uninstaller. These can be viewed in the File Properties Version or Details tab. keyname can either be a special name known by Windows or a user defined name. /LANG=0 can be used to indicate a language neutral language id.
The following names are known by Windows:
\b ProductName
@ -126,7 +126,7 @@ The following fields are provided by the System:
\b SpecialBuild
The name of these fields are translated on the target system, whereas user defined fields remain untranslated.
The displayed name of these special entries are translated on the target system, whereas user defined keynames remain untranslated.
\c VIAddVersionKey /LANG=${LANG_ENGLISH} "ProductName" "Test Application"
\c VIAddVersionKey /LANG=${LANG_ENGLISH} "Comments" "A test comment"
@ -142,7 +142,7 @@ The name of these fields are translated on the target system, whereas user defin
Sets the Product Version in the VS_FIXEDFILEINFO version information block.
\c VIProductVersion "1.2.3.4"
\c VIProductVersion 1.2.3.4
\S2{vifileversion} VIFileVersion
@ -150,5 +150,5 @@ Sets the Product Version in the VS_FIXEDFILEINFO version information block.
Sets the File Version in the VS_FIXEDFILEINFO version information block (You should also set the FileVersion string with VIAddVersionKey so the information is displayed at the top of the Version Tab in the Properties of the file). If you don't provide a File Version the Product Version is used in the VS_FIXEDFILEINFO block.
\c VIFileVersion "1.2.3.4"
\c VIFileVersion 1.2.3.4

6
Docs/src/defines.but
View file

@ -14,7 +14,7 @@ Define/conditional compilation related commands:
This command will add \e{gflag} to the global define list. This will have a similar effect as using the /D switch on the command line (the define only becomes effective after the !define command).
If \e{/date} or \e{/utcdate} are used, \e{value} will be passed into strftime and the result will be used as the value of \e{gflag}. strftime converts special symbols into certain parts of the current time or date. For example, %H will be converted into the current hour in 24-hour format. For a complete list of available symbols, search for strftime on \W{http://msdn.microsoft.com/}{MSDN}. On POSIX, you can get the list by using \c{man strftime}.
If \e{/date} or \e{/utcdate} are used, \e{value} will be passed to strftime() and the result will be used as the value of \e{gflag}. strftime converts special symbols into certain parts of the current time or date. For example, %H will be converted into the current hour in 24-hour format. For a complete list of available symbols, search for strftime on \W{http://msdn.microsoft.com/}{MSDN}. On POSIX, you can get the list by using \c{man strftime}.
If \e{/math} is used, the result of 'val1 OP val2', where OP may be +,-,*,&,|,^,/,<<,>>,>>> or % , will be used as the value of \e{gflag}. Note that val1 AND val2 MUST be integer values!
@ -25,7 +25,7 @@ If \e{/file} is used, the entire text file specified (including whitespace and n
\c !define /date NOW "%H:%M:%S %d %b, %Y"
\c !define /math RESULT 3 + 10
\c !define /math REST 15 % ${RESULT}
\c !define /file BUNCHASTUFF somesourcefile.cpp
\c !define /file BunchaStuff somesourcefile.cpp
\c !define /redef USE_SOMETHING ${RESULT} ;redefine USE_SOMETHING
\S1{undef} !undef
@ -65,7 +65,7 @@ The opposite of !ifdef. The lines will be compiled when the gflag has not been d
This command, when paired with an !endif command, will tell the compiler whether or not to compile the lines in between the two lines. If value is non-zero, or the comparison of value and value2 depending on the operator results in true, the contained lines will be compiled. Otherwise, they will be skipped.
op can be either == or != (case-insensitive string comparison), S== or S!= (case-sensitive string comparison), =, <>, <=, <, > or >= (int/hex/float comparison), & (bitwise AND comparison), && or || (boolean comparison).
If [!] is set, return value will be switched from true to false and vice versa.
If [!] is set, the result will be flipped from true to false and vice versa.
\c !if 1 < 0x2
\c !echo "1 is smaller than 2!!"

24
Docs/src/file.but
View file

@ -10,7 +10,7 @@ Closes a file handle opened with \R{FileOpen}{FileOpen}.
\c user_var(handle output) filename openmode
Opens a file named "filename", and sets the handle output variable with the handle. The openmode should be one of "r" (read) "w" (write, all contents of file are destroyed) or "a" (append, meaning opened for both read and write, contents preserved). In all open modes, the file pointer is placed at the beginning of the file. If the file cannot be opened, the handle output is set to empty, and the error flag is set.
Opens a file named "filename" and sets the handle output variable with the handle. The openmode should be one of "r" (read) "w" (write, all contents of file are destroyed) or "a" (append, meaning opened for both read and write, contents preserved). In all open modes, the file pointer is placed at the beginning of the file. If the file cannot be opened the handle output is set to empty and the error flag is set.
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}.
@ -21,7 +21,7 @@ If no absolute path is specified the current folder will be used. The current fo
\c handle user_var(output) [maxlen]
Reads a string (ANSI characters) from a file opened with \R{FileOpen}{FileOpen}. The string is read until either a newline (or carriage return newline pair) occurs, or until a null byte is read, or until maxlen is met (if specified). By default, strings are limited to 1024 characters (a special build with larger NSIS_MAX_STRLEN can be compiled or downloaded). If the end of file is read and no more data is available, the output string will be empty, and the error flag will be set.
Reads a string (ANSI characters) from a file opened with \R{FileOpen}{FileOpen}. The string is read until either a newline (or carriage return newline pair) occurs, or until a null byte is read, or until maxlen is met (if specified). By default, strings are limited to 1024 characters (a special build with larger NSIS_MAX_STRLEN can be compiled or downloaded). If the end of file is reached and no more data is available, the output string will be empty and the error flag will be set.
\NsisWarnBlockContainerBegin
\NsisBlockHeaderExeheadU
@ -44,7 +44,7 @@ DBCS text is supported but conversion output is limited to UCS-2/BMP, surrogate
\NsisFuncReqU
Reads a string (UTF-16LE characters) from a file opened with \R{FileOpen}{FileOpen}. The string is read until either a newline (or carriage return newline pair) occurs, or until a null wide-character is read, or until maxlen is met (if specified). By default, strings are limited to 1024 characters (a special build with larger NSIS_MAX_STRLEN can be compiled or downloaded). If the end of file is read and no more data is available, the output string will be empty, and the error flag will be set. If present, the BOM at the start of the file is skipped.
Reads a string (UTF-16LE characters) from a file opened with \R{FileOpen}{FileOpen}. The string is read until either a newline (or carriage return newline pair) occurs, or until a null wide-character is read, or until maxlen is met (if specified). By default, strings are limited to 1024 characters (a special build with larger NSIS_MAX_STRLEN can be compiled or downloaded). If the end of file is reached and no more data is available, the output string will be empty and the error flag will be set. If present, the BOM at the start of the file is skipped.
\c ClearErrors
\c FileOpen $0 $INSTDIR\file.dat r
@ -58,7 +58,7 @@ Reads a string (UTF-16LE characters) from a file opened with \R{FileOpen}{FileOp
\c handle user_var(output)
Reads a byte from a file opened with \R{FileOpen}{FileOpen}. The byte is stored in the output as an integer (0-255). If the end of file is read and no more data is available, the output will be empty, and the error flag will be set.
Reads a byte from a file opened with \R{FileOpen}{FileOpen}. The byte is stored in the output as an integer (0-255). If the end of file is reached and no more data is available, the output will be empty and the error flag will be set.
\c ClearErrors
\c FileOpen $0 $INSTDIR\file.dat r
@ -75,7 +75,7 @@ Reads a byte from a file opened with \R{FileOpen}{FileOpen}. The byte is stored
\NsisFuncReqU
Reads a word (2-bytes) from a file opened with \R{FileOpen}{FileOpen}. The word is stored in the output as an integer (0-65535). If the end of file is read and no more data is available, the output will be empty, and the error flag will be set.
Reads a word (2-bytes) from a file opened with \R{FileOpen}{FileOpen}. The word is stored in the output as an integer (0-65535). If the end of file is reached and no more data is available, the output will be empty and the error flag will be set.
\c ClearErrors
\c FileOpen $0 $INSTDIR\file.dat r
@ -90,7 +90,7 @@ Reads a word (2-bytes) from a file opened with \R{FileOpen}{FileOpen}. The word
\c handle offset [mode] [user_var(new position)]
Seeks a file opened with \R{FileOpen}{FileOpen}. If mode is omitted or specified as SET, the file is positioned to "offset", relative to the beginning of the file. If mode is specified as CUR, then the file is positioned to "offset", relative to the current file position. If mode is specified as END, then the file is positioned to "offset", relative to the end of the file. If the final parameter "new position" is specified, the new file position will be stored to that variable.
Seeks a file opened with \R{FileOpen}{FileOpen}. If mode is omitted or specified as SET, the file is positioned to "offset", relative to the beginning of the file. If mode is specified as CUR, then the file is positioned to "offset", relative to the current file position. If mode is specified as END, then the file is positioned to "offset", relative to the end of the file. If the final parameter "new position" is specified, the new file position will be stored in that variable.
\c ClearErrors
\c FileOpen $0 $INSTDIR\file.dat r
@ -135,12 +135,12 @@ Writes a Unicode (UTF-16LE) string to a file opened with \R{FileOpen}{FileOpen}.
\c handle string
Writes the integer interpretation of 'string' to a file opened with \R{FileOpen}{FileOpen}. Of course you can enter the integer value directly. The following code writes a "Carriage Return / Line Feed" - Enter to the file.
Writes the integer interpretation of 'string' to a file opened with \R{FileOpen}{FileOpen}. The error flag is set if an error occurs while writing. The following code writes a "Carriage Return / Line Feed" pair to the file.
\c FileWriteByte file_handle "13"
\c FileWriteByte file_handle "10"
If an error occurs while writing, the error flag will be set. Note that the low byte of the integer is used, i.e. writing 256 is the same as writing 0, etc.
Note that only the low byte of the integer is used, i.e. writing 256 is the same as writing 0, etc.
\S2{FileWriteWord} FileWriteWord
@ -148,12 +148,12 @@ If an error occurs while writing, the error flag will be set. Note that the low
\NsisFuncReqU
Writes the integer interpretation of 'string' as a WORD (2-bytes, range: 0-65535) to a file opened with \R{FileOpen}{FileOpen}. Of course you can enter the integer value directly. The following code writes a "Carriage Return / Line Feed" - Enter to the file.
Writes the integer interpretation of 'string' as a WORD (2-bytes, range: 0-65535) to a file opened with \R{FileOpen}{FileOpen}. The error flag is set if an error occurs while writing. The following code writes a "Carriage Return / Line Feed" pair to the file.
\c FileWriteWord file_handle "13"
\c FileWriteWord file_handle "10"
If an error occurs while writing, the error flag will be set. Note that the low WORD of the integer is used, i.e. writing 65536 is the same as writing 0, etc.
Note that only the low WORD of the integer is used, i.e. writing 65536 is the same as writing 0, etc.
\S2{FindClose} FindClose
@ -165,7 +165,7 @@ Closes a search opened with \R{FindFirst}{FindFirst}.
\c user_var(handle output) user_var(filename output) filespec
Performs a search for 'filespec', placing the first file found in filename_output (a user variable). It also puts the handle of the search into handle_output (also a user variable). If no files are found, both outputs are set to empty, and the error flag is set. Best used with \R{FindNext}{FindNext} and \R{FindClose}{FindClose}. Note that the filename output is without path.
Performs a search for 'filespec', placing the first file found in filename_output (a user variable). It also puts the handle of the search into handle_output (also a user variable). If no files are found, both outputs are set to empty and the error flag is set. \R{FindClose}{FindClose} must be used to close the handle. Note that the filename output is without path.
\c FindFirst $0 $1 $INSTDIR\*.txt
\c loop:
@ -180,4 +180,4 @@ Performs a search for 'filespec', placing the first file found in filename_outpu
\c handle user_var(filename_output)
Continues a search began with \R{FindFirst}{FindFirst}. handle should be the handle_output_variable returned by \R{FindFirst}{FindFirst}. If the search is completed (there are no more files), filename_output is set to empty, and the error flag is set. Note that the filename output is without path.
Continues a search began with \R{FindFirst}{FindFirst}. handle should be the handle_output_variable returned by \R{FindFirst}{FindFirst}. If the search is completed (there are no more files), filename_output is set to empty and the error flag is set. Note that the filename output is without path.

11
Docs/src/flowcontrol.but
View file

@ -2,7 +2,7 @@
\S2{abort} Abort
\c user_message
\c [user_message]
Cancels the install, stops execution of script, and displays user_message in the status display. Note: you can use this from \R{callbacks}{Callback functions} to do special things. \R{pages}{Page callbacks} also uses \R{abort}{Abort} for special purposes.
@ -47,18 +47,17 @@ Gets the address of the current instruction (the \R{getcurrentaddress}{GetCurren
\c Function func
\c DetailPrint "function"
\c IntOp $0 $0 + 2
\c IntOp $0 $0 + 2 ; Calculate the address after of the instruction after "Goto callFunc" in the Section
\c Call $0
\c DetailPrint "function end"
\c FunctionEnd
\c
\c Section
\c DetailPrint "section"
\c DetailPrint "section"
\c GetCurrentAddress $0
\c Goto callFunc
\c
\c DetailPrint "back to section"
\c DetailPrint "back in section"
\c Return
\c
\c callFunc:
@ -113,7 +112,7 @@ If a user variable is specified, jumps to absolute address (generally you will w
\c label_to_goto_if_abort [label_to_goto_if_no_abort]
If abort is called it will "return" true. This can happen if the user chose abort on a file that failed to create (or overwrite) or if the user aborted by hand. This function can only be called from the leave function of the instfiles \R{page}{page}.
Will "return" true if the installation has been aborted. This can happen if the user chose abort on a file that failed to create (or overwrite) or if the user aborted by hand. This function can only be called from the leave function of the instfiles \R{page}{page}.
\c Page instfiles "" "" instfilesLeave
\c
@ -184,7 +183,7 @@ Compares two integers val1 and val2. If val1 and val2 are equal, Gotos jump_if_e
\c val1 val2 jump_if_equal [jump_if_val1_less] [jump_if_val1_more]
Compares two unsigned integers val1 and val2. If val1 and val2 are equal, Gotos jump_if_equal, otherwise if val1 < val2, Gotos jump_if_val1_less, otherwise if val1 > val2, Gotos jump_if_val1_more. Performs the comparison as unsigned integers.
Same as \R{intcmp}{IntCmp}, but treats the values as unsigned integers.
\S2{messagebox} MessageBox

10
Docs/src/generalpurpose.but
View file

@ -40,7 +40,7 @@ You should always specify an absolute path.
Creates a shortcut 'link.lnk' that links to 'target.file', with optional parameters 'parameters'.
The icon used for the shortcut is 'icon.file,icon_index_number'; for default icon settings use empty strings for both icon.file and icon_index_number.
start_options should be one of: \e{SW_SHOWNORMAL}, \e{SW_SHOWMAXIMIZED}, \e{SW_SHOWMINIMIZED}, or an empty string.
keyboard_shortcut should be in the form of 'flag|c' where flag can be a combination (using |) of: \e{ALT}, \e{CONTROL}, \e{EXT}, or \e{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 \R{setoutpath}{SetOutPath} before creating the Shortcut or use /NoWorkingDir if you don't need to set the working directory.
keyboard_shortcut should be in the form of 'flag|c' where flag can be a combination (using |) of: \e{ALT}, \e{CONTROL}, \e{EXT}, or \e{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 as the working directory. You can change it by using \R{setoutpath}{SetOutPath} before creating the Shortcut or use /NoWorkingDir if you don't need to set the working directory.
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).
@ -72,7 +72,7 @@ This is similar to \R{getdllversion}{GetDLLVersion}, only it acts on the system
\c filename user_var(high dword output) user_var(low dword output)
Gets the last write time of "filename". Sets the user output variables with the high and low dwords of the timestamp on success; on failure the outputs are empty and the error flag is set.
Gets the last write time of "filename". Sets the user output variables with the high and low dwords of the FILETIME timestamp on success; on failure the outputs are empty and the error flag is set.
\S2{getfiletimelocal} GetFileTimeLocal
@ -84,7 +84,7 @@ This is similar to \R{getfiletime}{GetFileTime}, only it acts on the system buil
\c [/SHORT] user_var(output) path_or_file
Assign to the user variable $x, the full path of the file specified. If the path portion of the parameter is not found, the error flag will be set and $x will be empty. If /SHORT is specified, the path is converted to the short filename form. However, if /SHORT is not specified, the path isn't converted to its long filename form. To get the long filename, call GetLongPathName using the System plug-in. Note that GetLongPathName is only available on Windows 98, Windows 2000 and above.
Assign the full path of the file specified to user variable $x. If the path portion of the parameter is not found, the error flag will be set and $x will be empty. If /SHORT is specified, the path is converted to the short filename form. However, if /SHORT is not specified, the path isn't converted to its long filename form. To get the long filename, call GetLongPathName using the System plug-in. Note that GetLongPathName is only available on Windows 98, Windows 2000 and above.
\c StrCpy $INSTDIR $PROGRAMFILES\NSIS
\c SetOutPath $INSTDIR
@ -103,7 +103,7 @@ Assign to the user variable $x, the full path of the file specified. If the path
\c user_var(output) [base_dir]
Assign to the user variable $x, the name of a temporary file. The file will have been created, so you can then overwrite it with what you please. The name of the temporary file is guaranteed to be unique. If to want the temporary file to be created in another directory than the Windows temp directory, specify a base_dir. \R{delete}{Delete} the file when done with it.
Assign to the user variable $x, the name of a temporary file. The file will be created for you and it will be empty. The name of the temporary file is guaranteed to be unique. If to want the temporary file to be created in another directory other than the Windows temp directory, specify a base_dir. You should \R{delete}{Delete} the file when you are done with it.
\c GetTempFileName $0
\c File /oname=$0 something.dat
@ -114,7 +114,7 @@ Assign to the user variable $x, the name of a temporary file. The file will have
\c user_var(output) filename
Assign to the user variable $x, the full path of the file named by the second parameter. The error flag will be set and $x will be empty if the file cannot be found. Uses \R{searchpath}{SearchPath}() to search the system paths for the file.
Assign to the user variable $x, the full path of the file named by the second parameter. The error flag will be set and $x will be empty if the file cannot be found. Uses \W{http://msdn.microsoft.com/en-us/library/aa365527}{SearchPath()} to search the system paths for the file.
\S2{setfileattributes} SetFileAttributes

128
Docs/src/headers.but
View file

@ -75,7 +75,7 @@ Call functions:
\\<b\\>Note:\\</b\\>
\\<br\\>- Error flag if disk or directory isn't exist
\\<br\\>- Error flag if syntax error
\\<br\\>- See also \W{http://nsis.sourceforge.net/Locate_plugin}{Locate plugin}
\\<br\\>- See also: \W{http://nsis.sf.net/Locate_plugin}{Locate plugin}
\\<b\\>Example (Find one file):\\</b\\>
@ -320,16 +320,15 @@ Call functions:
\\<b\\>Note:\\</b\\>
\\<br\\>- Error flag if disk or directory isn't exist
\\<br\\>- Error flag if syntax error
\\<br\\>- See also \W{http://nsis.sourceforge.net/Locate_plugin}{Locate plugin}
\\<br\\>- See also: \W{http://nsis.sf.net/Locate_plugin}{Locate plugin}
\\<b\\>Example (1):\\</b\\>
\\<b\\>Examples:\\</b\\>
\c Section
\c ; Find file size "C:\WINDOWS\Explorer.exe" in kilobytes
\c Section 'Find file size of "$WINDIR\Explorer.exe" in KiB'
\c
\c ${GetSize} "C:\WINDOWS" "/M=Explorer.exe /S=0K /G=0" $0 $1 $2
\c ; $0="220" Kb
\c ${GetSize} "$WINDIR" "/M=Explorer.exe /S=0K /G=0" $0 $1 $2
\c ; $0="220" KiB
\c ; $1="1" files
\c ; $2="" directories
\c
@ -337,13 +336,10 @@ Call functions:
\c MessageBox MB_OK "Error"
\c SectionEnd
\\<b\\>Example (2):\\</b\\>
\c Section
\c ; Find folder size "C:\Installs\Reanimator\Drivers" in megabytes
\c Section 'Find folder size of "C:\Installs\Drivers" in MiB'
\c
\c ${GetSize} "C:\Installs\Reanimator\Drivers" "/S=0M" $0 $1 $2
\c ; $0="132" Mb
\c ${GetSize} "C:\Installs\Drivers" "/S=0M" $0 $1 $2
\c ; $0="132" MiB
\c ; $1="555" files
\c ; $2="55" directories
\c
@ -351,12 +347,9 @@ Call functions:
\c MessageBox MB_OK "Error"
\c SectionEnd
\\<b\\>Example (3):\\</b\\>
\c Section
\c ; Find sum of files and folders "C:\WINDOWS" (no subfolders)
\c Section 'Find sum of files and folders in "$WINDIR" (no subfolders)'
\c
\c ${GetSize} "C:\WINDOWS" "/G=0" $0 $1 $2
\c ${GetSize} "$WINDIR" "/G=0" $0 $1 $2
\c ; $0="" size
\c ; $1="253" files
\c ; $2="46" directories
@ -505,12 +498,12 @@ Call functions:
\\<b\\>Note:\\</b\\>
\\<br\\>- Error flag if file isn't exist
\\<br\\>- Error flag if syntax error
\\<br\\>- See also \W{http://nsis.sourceforge.net/Time_plugin}{Time plugin}
\\<br\\>- See also: \W{http://nsis.sf.net/Time_plugin}{Time plugin}
\\<b\\>Example (Get local time):\\</b\\>
\\<b\\>Examples:\\</b\\>
\c Section
\c Section 'Get local time'
\c ${GetTime} "" "L" $0 $1 $2 $3 $4 $5 $6
\c ; $0="01" day
\c ; $1="04" month
@ -523,9 +516,7 @@ Call functions:
\c MessageBox MB_OK 'Date=$0/$1/$2 ($3)$\nTime=$4:$5:$6'
\c SectionEnd
\\<b\\>Example (Get file time):\\</b\\>
\c Section
\c Section 'Get file time'
\c ${GetTime} "$WINDIR\Explorer.exe" "C" $0 $1 $2 $3 $4 $5 $6
\c ; $0="12" day
\c ; $1="10" month
@ -534,15 +525,13 @@ Call functions:
\c ; $4="2" hour
\c ; $5="32" minute
\c ; $6="03" seconds
\c
\c
\c IfErrors 0 +2
\c MessageBox MB_OK "Error" IDOK +2
\c MessageBox MB_OK 'Date=$0/$1/$2 ($3)$\nTime=$4:$5:$6'
\c SectionEnd
\\<b\\>Example (Get system time):\\</b\\>
\c Section
\c Section 'Get system time'
\c ${GetTime} "" "LS" $0 $1 $2 $3 $4 $5 $6
\c ; $0="01" day
\c ; $1="04" month
@ -555,9 +544,7 @@ Call functions:
\c MessageBox MB_OK 'Date=$0/$1/$2 ($3)$\nTime=$4:$5:$6'
\c SectionEnd
\\<b\\>Example (Convert time to 12-hour format AM/PM):\\</b\\>
\c Section
\c Section 'Convert time to 12-hour format AM/PM'
\c ${GetTime} "" "L" $0 $1 $2 $3 $4 $5 $6
\c
\c StrCmp $4 0 0 +3
@ -597,26 +584,18 @@ Call functions:
\c ; $var=0 file has no specified attributes
\\<b\\>Note:\\</b\\>
\\<br\\>- Error flag if file doesn't exist
\\<br\\>- Error flag is set if file doesn't exist
\\<b\\>Example1:\\</b\\>
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetFileAttributes} "C:\MSDOS.SYS" "ALL" $R0
\c ; $R0=READONLY|HIDDEN|SYSTEM|ARCHIVE
\c SectionEnd
\\<b\\>Example2:\\</b\\>
\c Section
\c
\c ${GetFileAttributes} "C:\MSDOS.SYS" "SYSTEM|HIDDEN" $R0
\c ; $R0=1
\c SectionEnd
\\<b\\>Example3:\\</b\\>
\c Section
\c
\c ${GetFileAttributes} "C:\MSDOS.SYS" "NORMAL" $R0
\c ; $R0=0
\c SectionEnd
@ -639,10 +618,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetFileVersion} "C:\ftp\program.exe" $R0
\c ; $R0="1.1.0.12"
\c SectionEnd
\c ${GetFileVersion} "C:\ftp\program.exe" $R0 ; $R0="1.1.0.12"
\S1{getexename} GetExeName
@ -654,10 +630,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetExeName} $R0
\c ; $R0="C:\ftp\program.exe"
\c SectionEnd
\c ${GetExeName} $R0 ; $R0="C:\ftp\program.exe"
\S1{getexepath} GetExePath
@ -669,10 +642,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetExePath} $R0
\c ; $R0="C:\ftp"
\c SectionEnd
\c ${GetExePath} $R0 ; $R0="C:\ftp"
\S1{getparameters} GetParameters
@ -684,10 +654,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetParameters} $R0
\c ; $R0="[parameters]"
\c SectionEnd
\c ${GetParameters} $R0 ; $R0="[parameters]"
\S1{getoptions} GetOptions
@ -751,19 +718,10 @@ Call functions:
\c ${GetRoot} "[FullPath]" $var
\\<b\\>Example1:\\</b\\>
\\<b\\>Examples:\\</b\\>
\c Section
\c ${GetRoot} "C:\Program Files\NSIS" $R0
\c ; $R0="C:"
\c SectionEnd
\\<b\\>Example2:\\</b\\>
\c Section
\c ${GetRoot} "\\SuperPimp\NSIS\Source\exehead\Ui.c" $R0
\c ; $R0="\\SuperPimp\NSIS"
\c SectionEnd
\c ${GetRoot} "C:\Program Files\NSIS" $R0 ; $R0="C:"
\c ${GetRoot} "\\SuperPimp\NSIS\Source\exehead\Ui.c" $R0 ; $R0="\\SuperPimp\NSIS"
\S1{getparent} GetParent
@ -775,10 +733,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetParent} "C:\Program Files\Winamp\uninstwa.exe" $R0
\c ; $R0="C:\Program Files\Winamp"
\c SectionEnd
\c ${GetParent} "C:\Program Files\Winamp\uninstwa.exe" $R0 ; $R0="C:\Program Files\Winamp"
\S1{getfilename} GetFileName
@ -790,10 +745,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetFileName} "C:\Program Files\Winamp\uninstwa.exe" $R0
\c ; $R0="uninstwa.exe"
\c SectionEnd
\c ${GetFileName} "C:\Program Files\Winamp\uninstwa.exe" $R0 ; $R0="uninstwa.exe"
\S1{getbasename} GetBaseName
@ -805,10 +757,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetBaseName} "C:\ftp\program.exe" $R0
\c ; $R0="program"
\c SectionEnd
\c ${GetBaseName} "C:\ftp\program.exe" $R0 ; $R0="program"
\S1{getfileext} GetFileExt
@ -820,10 +769,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${GetFileExt} "C:\ftp\program.exe" $R0
\c ; $R0="exe"
\c SectionEnd
\c ${GetFileExt} "C:\ftp\program.exe" $R0 ; $R0="exe"
\S1{bannertrimpath} BannerTrimPath
@ -934,10 +880,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c ${DirState} "$TEMP" $R0
\c ; $R0="1" directory is full
\c SectionEnd
\c ${DirState} "$TEMP" $R0 ; $R0="1" (directory is full)
\S1{refreshshellicons} RefreshShellIcons
@ -950,8 +893,7 @@ Call functions:
\\<b\\>Example:\\</b\\>
\c Section
\c WriteRegStr HKCR "Winamp.File\DefaultIcon" "" "$PROGRAMFILES\Winamp\WINAMP.EXE,2"
\c
\c WriteRegStr HKCR "Winamp.File\DefaultIcon" "" "$INSTDIR\WINAMP.EXE,2"
\c ${RefreshShellIcons}
\c SectionEnd

16
Docs/src/history.but
View file

@ -236,7 +236,7 @@ Released on July 14th, 2013
\b Default verbosity is /V3 without logo, MakeNSISW still uses /V4.
\b \R{amanifestsupportedos}{ManifestSupportedOS} added support for the Windows 8.1 Preview GUID and it is set by default to avoid GetVersionEx compatibility behavior.
\b \R{amanifestsupportedos}{ManifestSupportedOS} added support for the Windows 8.1 GUID and it is set by default to avoid GetVersionEx compatibility behavior.
\S2{} Minor Changes
@ -248,7 +248,7 @@ Released on July 14th, 2013
\b Minor MakeNSISW fixes and tweaks
\b Zip2Exe Unicode checkbox
\b Added Zip2Exe Unicode checkbox
\H{v3.0a0} 3.0 Alpha 0
@ -276,7 +276,7 @@ Released on May 19th, 2013
\b MakeNSIS can read UTF8SIG and UTF16BOM script files (\W{http://sourceforge.net/support/tracker.php?aid=2026892}{RFE #2026892})
\b All NLF and NSH language files are stored in Unicode (\W{http://sourceforge.net/support/tracker.php?aid=1879642}{RFE #1879642})
\b All NLF and NSH language files are stored as UTF-16LE (\W{http://sourceforge.net/support/tracker.php?aid=1879642}{RFE #1879642})
\b Scripts can control the SupportedOS list in the application manifest using \R{amanifestsupportedos}{ManifestSupportedOS} (\W{http://sourceforge.net/support/tracker.php?aid=2725883}{bug #2725883}, \W{http://sourceforge.net/support/tracker.php?aid=3020103}{RFE #3020103})
@ -298,7 +298,7 @@ Released on May 19th, 2013
\b %temp%\\Low will be used if the installer cannot write to %temp% nor %windir%\\Temp (\W{http://sourceforge.net/support/tracker.php?aid=2909242}{bug #2909242}, \W{http://sourceforge.net/support/tracker.php?aid=2912824}{patch #2912824})
\b Added $\{NSIS_PACKEDVERSION\}, the NSIS version packed in a hex number (\W{http://sourceforge.net/support/tracker.php?aid=2680832}{patch #2680832})
\b Added $\{NSIS_PACKEDVERSION\}, the NSIS version packed as a hex number (\W{http://sourceforge.net/support/tracker.php?aid=2680832}{patch #2680832})
\b Added \R{prescopemacro}{$\{__MACRO__\}} and \R{precounter}{$\{__COUNTER__\}} predefines
@ -578,7 +578,7 @@ Released on December 20th, 2008
\b \L{../Docs/nsDialogs/Readme.html}{nsDialogs}: Added progress bar support
\b \L{../Include/WinVer.nsh}{WinVer.nsh}: Added IsServer, IsWin2003R2, IsStarterEdition, OSHasMediaCenter and OSHasTabletSupport (patch by Anders)
\b \L{../Include/WinVer.nsh}{WinVer.nsh}: Added IsServer, IsWin2003R2, IsStarterEdition, OSHasMediaCenter and OSHasTabletSupport
\b \L{../Include/WinVer.nsh}{WinVer.nsh}: Fixed 95/NT4 ambiguity (\W{http://sourceforge.net/support/tracker.php?aid=2053642}{bug #2053642})
@ -1254,7 +1254,7 @@ Released on April 27th, 2007
\b Added LIBRARY_IGNORE_VERSION option for \R{library_install}{InstallLib} (\W{http://sourceforge.net/support/tracker.php?aid=1699435}{patch #1699435})
\b Added VXD support for \R{getdllversionlocal}{GetDLLVersionLocal} on Windows NT/2000/XP/Vista (\W{http://sourceforge.net/support/tracker.php?aid=1706624}{patch #1706624})
\b Added VXD support for \R{getdllversionlocal}{GetDLLVersionLocal} on Windows NT4/2000/XP/Vista (\W{http://sourceforge.net/support/tracker.php?aid=1706624}{patch #1706624})
\b Avoid \R{library}{Library} warning when UnInstallLib is unused (\W{http://sourceforge.net/support/tracker.php?aid=1692761}{bug #1692761})
@ -2317,7 +2317,7 @@ Released on March 19th, 2005
\b Added MB_RTLREADING style to \R{messagebox}{MessageBox} (\W{http://sourceforge.net/support/tracker.php?aid=1159701}{RFE #1159701})
\b All registry instructions now accept SHCTX which is replaced with HKLM or HKCU on runtime according to \R{setshellvarcontext}{SetShellVarContext} (\W{http://sourceforge.net/support/tracker.php?aid=1124901}{RFE #1124901})
\b All registry instructions now accept SHCTX which is replaced with HKLM or HKCU at runtime according to \R{setshellvarcontext}{SetShellVarContext} (\W{http://sourceforge.net/support/tracker.php?aid=1124901}{RFE #1124901})
\S2{} Minor Changes
@ -2827,7 +2827,7 @@ Released on December 27th, 2003
\b Added \R{adirverify}{DirVerify} and \R{getinstdirerror}{GetInstDirError} to allow custom error checking when the installation directory is invalid or the drive does not have enough space
\b Support for reading environmental variables on compile time: \R{compenvvar}{$%envVarName%}
\b Support for reading environmental variables at compile time: \R{compenvvar}{$%envVarName%}
\b Added /SD parameter for \R{messagebox}{MessageBox}. Allows to set default for silent installers.

33
Docs/src/intro.but
View file

@ -2,33 +2,32 @@
\H{intro-about} About NSIS
An installer is the first experience of a user with your application.
Slow or unsuccessful software installations are the most irritating computer problems.
The installer is your application's first impression.
Slow or unsuccessful software installations is one of the most irritating computer problems.
A quick and user friendly installer is therefore an essential part of your software product.
NSIS (Nullsoft Scriptable Install System) is a tool that allows programmers to create such installers for Windows.
It is released under an open source license and is \R{license}{completely free for any use}.
NSIS creates installers that are capable of installing, uninstalling, setting system settings, extracting files, etc.
Because it's based on script files, you can fully control every part of your installers.
The script language supports variables, functions, string manipulation, just like a normal programming language - but designed for the creation of installers.
Because it's based on script files you can fully control every part of your installer.
The scripting language supports variables, functions and string manipulation, just like a normal programming language - but designed for the creation of installers.
Even with all these features, NSIS is still the smallest installer system available. With the default options, it has an overhead of only 34 KB.
Now you can also create \R{intro-unicode}{Unicode installers}, targeting all the languages supported by the OS without display issues.
With NSIS 3 you can also create \R{intro-unicode}{Unicode installers}, targeting all the languages supported by the OS without display issues.
\H{intro-features} Main Features
\\<b\\>Small overhead size\\</b\\>
NSIS is created to be small, fast and efficient. While other installers often add hundreds of kilobytes or several megabytes to your installer data, a full featured NSIS installer has an overhead of only 34 KB.
NSIS has been designed to be small, fast and efficient. While other installers often add hundreds of kilobytes or several megabytes to your installer data, a fully featured NSIS installer has a overhead of only 34 KB.
\\<b\\>Compatible with all major Windows versions\\</b\\>
You can create a single installer that is compatible with Windows 95, 98, ME, NT4, 2000, XP, 2003, Vista, Server 2008, 7, Server 2008R2, 8, Server 2012, 8.1 and Server 2012R2.
You can create a single installer that is compatible with Windows 95, 98, ME, NT4, 2000, XP, 2003, Vista, Server 2008, 7, Server 2008R2, 8, Server 2012, 8.1, Server 2012R2 and Windows 10.
\\<b\\>Unique compression methods\\</b\\>
You can choose between three different integrated compression method (ZLib, BZip2, LZMA). The new LZMA compression gives better results than any other common compression method. You don't have to use large self-extracting archive modules or other applications. The compression support is included in the 34 KB overhead.
You can choose between three different integrated compression methods (ZLib, BZip2, LZMA). LZMA compression gives better results than any other common compression method. You don't have to use large self-extracting archive modules or other applications, the compression support is included in the 34 KB overhead.
\\<b\\>Script based\\</b\\>
@ -36,11 +35,11 @@ Unlike other systems that can only generate installers based on a list of files
\\<b\\>Multiple languages in one installer\\</b\\>
One installer can support multiple interface languages. More than 60 translations are already included, but you can also create your own language files. RTL (right-to-left) languages such as Arabic and Hebrew are fully supported. Creating Unicode native installer is also possible for even more supported languages.
One installer can support multiple interface languages. More than 60 translations are already included and you can also create your own language files. RTL (right-to-left) languages such as Arabic and Hebrew are fully supported. Creating a Unicode native installer is also possible for even more supported languages.
\\<b\\>Many features and checks for the target system\\</b\\>
The script language provides commands you can use on the target system. From simple features like folder creation and registry editing to text/binary file modification, modification of environment variables and system reboots. Using provided plug-ins you can even use Windows API.
The script language provides commands you can use on the target system. From simple features like folder creation and registry editing to text/binary file modification, modification of environment variables and system reboots. By using one of the provided plug-ins you can even call the Windows API directly.
\\<b\\>Custom dialogs and interfaces\\</b\\>
@ -48,7 +47,7 @@ You can create custom wizard pages to get user input or integrate configuration
\\<b\\>Plug-in system\\</b\\>
NSIS can be extended with plug-ins that can communicate with the installer. They can be written in C, C++, Delphi or another language and can be used to perform installation tasks or extend the installer interface. You can use the plug-in with a single line of script code. Plug-ins can also be compressed like other installation data and will only be included when you are using the provided features.
NSIS can be extended with plug-ins that can communicate with the installer. They can be written in C, C++, Delphi or another language and can be used to perform installation tasks or extend the installer interface. You can use the plug-in with a single line of script code. Plug-ins are also be compressed like other installation data and will only be included when you are using their features.
\\<b\\>Support for web installation, file patching\\</b\\>
@ -56,7 +55,7 @@ The NSIS distribution includes a set of plug-ins that allow you to download file
\\<b\\>Project integration, different releases and automatic builds\\</b\\>
The NSIS compiler features a powerful preprocessor. This allows you to easily integrate multiple projects into a single installer or automatically generate installer builds. You can also generate different releases such as lite and full version.
The NSIS compiler features a powerful preprocessor. This allows you to easily integrate multiple projects into a single installer or automatically generate installer builds. You can also generate different releases such as lite and full versions.
\\<b\\>Easy and human readable file formats\\</b\\>
@ -94,7 +93,7 @@ The NSIS script format and the format used for interface dialogs are easy, docum
\b Installers can be as large as 2GB
\b Optional silent mode for automated installations
\b Optional \R{silent}{silent} mode for automated installations
\b A preprocessor with support for defined symbols, macro's, conditional compilation, standard predefines
@ -148,12 +147,10 @@ The NSIS script format and the format used for interface dialogs are easy, docum
\b Completely free for any use. See \R{license}{license}.
\b More
\H{intro-unicode} Unicode installers
Starting with MakeNSIS v3.0 you can choose to create Unicode installers by setting the \R{aunicodetarget}{Unicode} attribute.
Starting with NSIS v3.0 you can choose to create Unicode installers by setting the \R{aunicodetarget}{Unicode} attribute.
These installers will not work on Windows 95/98/ME but they will allow you to display your installer in any Unicode language supported by the OS.
When building a Unicode installer, NSIS variables can hold Unicode characters (0000-FFFF). There should be no need to modify your existing scripts.
When building a Unicode installer NSIS variables can hold Unicode characters (0001-FFFF). There should be no need to modify your existing scripts.
If you want to read/write Unicode files, specific instructions have been added to read/write UTF-16LE strings from/to disk.

2
Docs/src/jumps.but
View file

@ -2,7 +2,7 @@
Unlike labels, relative jumps are, as the name suggests, relative to the place they are called from. You can use relative jumps wherever you can use labels. Relative jumps are marked by numbers. +1 jumps to the next instruction (the default advancement), +2 will skip one instruction and go to the second instruction from the current instruction, -2 will jump two instructions backward, and +10 will skip 9 instructions, jumping to the tenth instruction from the current instruction.
An instruction is every command that is executed at run-time, when the installer is running. \R{messagebox}{MessageBox}, \R{goto}{Goto}, \R{getdllversion}{GetDLLVersion}, \R{FileRead}{FileRead}, \R{setshellvarcontext}{SetShellVarContext} are all instructions. \R{saddsize}{AddSize}, \R{ssection}{Section}, \R{ssectiongroup}{SectionGroup}, \R{ssectionend}{SectionEnd}, \R{asetoverwrite}{SetOverwrite} (and everything under \R{flags}{Compiler Flags}), \R{aname}{Name}, \R{asetfont}{SetFont}, \R{langstring}{LangString}, are not instructions because they are executed at compile time.
A instruction is every command that is executed at run-time, when the installer is running. \R{messagebox}{MessageBox}, \R{goto}{Goto}, \R{getdllversion}{GetDLLVersion}, \R{FileRead}{FileRead}, \R{setshellvarcontext}{SetShellVarContext} are all instructions. \R{saddsize}{AddSize}, \R{ssection}{Section}, \R{ssectiongroup}{SectionGroup}, \R{ssectionend}{SectionEnd}, \R{asetoverwrite}{SetOverwrite} (and everything under \R{flags}{Compiler Flags}), \R{aname}{Name}, \R{asetfont}{SetFont}, \R{langstring}{LangString}, are not instructions because they are executed at compile time.
Examples:

2
Docs/src/labels.but
View file

@ -1,6 +1,6 @@
\S0{labels} Labels
Labels are the targets of \R{goto}{Goto} instructions, or of the various branching instructions (such as \R{iferrors}{IfErrors}, \R{messagebox}{MessageBox}, \R{iffileexists}{IfFileExists}, and \R{strcmp}{StrCmp}). Labels must be within a \R{ssection}{Section} or a \R{ffunction}{Function}. Labels are local in scope, meaning they are only accessible from within the \R{ssection}{Section} or \R{ffunction}{Function} that they reside in.
Labels are the targets of \R{goto}{Goto} instructions and the various branching instructions (such as \R{iferrors}{IfErrors}, \R{messagebox}{MessageBox}, \R{iffileexists}{IfFileExists}, and \R{strcmp}{StrCmp}). Labels must be within a \R{ssection}{Section} or a \R{ffunction}{Function}. Labels are local in scope, meaning they are only accessible from within the \R{ssection}{Section} or \R{ffunction}{Function} that they reside in.
To declare a label, simply use:
\e{MyLabel:}

14
Docs/src/langs.but
View file

@ -4,13 +4,13 @@
\c language_file.nlf
Loads a language file for the construction of a language table. All of the language files that come with NSIS are in \L{../Contrib/Language files}{Contrib\\Language Files}
Loads a language file for the construction of a language table. All of the language files that ship with NSIS are in \L{../Contrib/Language files}{Contrib\\Language Files}
After you have inserted the language file $\{LANG_langfile\} will be defined as the language id (for example, $\{LANG_ENGLISH\} will be defined as 1033). Use it with \R{langstring}{LangString}, \R{licenselangstring}{LicenseLangString}, LangDLL and \R{viaddversionkey}{VIAddVersionKey}.
After you have inserted the language file $\{LANG_langfile\} will be defined as the language id (for example, $\{LANG_ENGLISH\} will be defined as 1033). Use it with \R{langstring}{LangString}, \R{licenselangstring}{LicenseLangString}, \R{langdll}{LangDLL} and \R{viaddversionkey}{VIAddVersionKey}.
\S2{langstring} LangString
\c name language_id string
\c name language_id|0 string
Defines a multilingual string. This means its value may be different (or not, it's up to you) for every language. It allows you to easily make your installer multilingual without the need to add massive switches to the script.
@ -20,7 +20,7 @@ Each language string has a name that identifies it and a value for each language
\b Unlike defines that use curly braces - \{\}, language strings use parenthesis - ().
\b If you change the language in the .onInit function, note that language strings in .onInit will still use the detected language based on the user's default Windows language, because the language is initialized after .onInit.
\b If you change the language in the .onInit function, note that language strings in .onInit will still use the detected language based on the user's default Windows language because the language is initialized after .onInit.
\b Always set language strings for every language in your script.
@ -36,14 +36,14 @@ Each language string has a name that identifies it and a value for each language
\S2{licenselangstring} LicenseLangString
\c name language_id license_path
\c name language_id|0 license_path
Does the same as \R{langstring}{LangString} only it loads the string from a text/RTF file and defines a special LangString that can be used only by \R{alicensedata}{LicenseData}.
Does the same as \R{langstring}{LangString} only it loads the string from a text/RTF file and defines a special LangString that can only be used by \R{alicensedata}{LicenseData}.
\c LicenseLangString license ${LANG_ENGLISH} license-english.txt
\c LicenseLangString license ${LANG_FRENCH} license-french.txt
\c LicenseLangString license ${LANG_GERMAN} license-german.txt
\c
\c LicenseData $(license)
\S0{langs} Multiple Languages

12
Docs/src/library.but
View file

@ -103,13 +103,13 @@ The Windows temp directory could be located on any volume, so you cannot use thi
\S1{library_install_options} Options
\R{define}{Define} any of the following before inserting the InstallLib macro to modify its behavior as specified.
\R{define}{Define} any of the following before inserting a InstallLib macro to modify its behavior as specified.
\S2{} LIBRARY_X64
\b Installs a DLL built for Windows x64.
\b \\<b\\>Warning:\\</b\\> this resets file system redirection.
\b \\<b\\>Warning:\\</b\\> This resets file system redirection.
\S2{} LIBRARY_SHELL_EXTENSION
@ -133,9 +133,9 @@ The Windows temp directory could be located on any volume, so you cannot use thi
\S1{library_install_notes} Notes
\b If you want to support Windows 9x/ME, you can only use short filenames (8.3).
\b If you need to support Windows 9x/ME, you can only use short filenames (8.3).
\b \\<b\\>Warning:\\</b\\> when deploying DLLs, always use redistributable files. Never copy files from your system directory.
\b \\<b\\>Warning:\\</b\\> Always use redistributable files when deploying DLLs, never copy files from your system directory!
\S1{library_install_examples} Example
@ -223,13 +223,13 @@ Location of the library
\S1{library_uninstall_options} Options
\R{define}{Define} any of the following before inserting the UnInstallLib macro to modify its behavior as specified.
\R{define}{Define} any of the following before inserting a UnInstallLib macro to modify its behavior as specified.
\S2{} LIBRARY_X64
\b Uninstalls a DLL built for Windows x64.
\b \\<b\\>Warning:\\</b\\> this resets \R{setregview}{SetRegView} and file system redirection.
\b \\<b\\>Warning:\\</b\\> This resets \R{setregview}{SetRegView} and file system redirection.
\S2{} LIBRARY_SHELL_EXTENSION

2
Docs/src/log.but
View file

@ -4,7 +4,7 @@
\c on|\\<b\\>off\\</b\\>
Sets whether install logging to $INSTDIR\\install.log will happen. $INSTDIR must have a value before you call this function or it will not work. Note that the \e{NSIS_CONFIG_LOG} build setting must be set (\c{scons NSIS_CONFIG_LOG=yes}) on compile time (it is not by default) to support this. See \R{build}{Building NSIS} for more information about recompiling NSIS.
Sets whether install logging to $INSTDIR\\install.log will happen. $INSTDIR must have a value before you call this function or it will not work. Note that the \e{NSIS_CONFIG_LOG} build setting must be set (\c{scons NSIS_CONFIG_LOG=yes}) when building (it is not set by default) to support this. See \R{build}{Building NSIS} for more information about recompiling NSIS.
\S2{logtext} LogText

6
Docs/src/misc.but
View file

@ -4,7 +4,7 @@
\c user_var(error level output)
Returns the last error level set by \R{seterrorlevel}{SetErrorLevel} or -1 if it was never used.
Returns the last error level set by \R{seterrorlevel}{SetErrorLevel} or -1 if it has never been set.
\c GetErrorLevel $0
\c IntOp $0 $0 + 1
@ -69,11 +69,11 @@ Sets the error level of the installer or uninstaller to \e{error_level}. See \R{
\c \\<b\\>32\\</b\\>|64|lastused
Sets the registry view affected by \R{registry}{registry commands}. On Windows x64 there are two views. One for 32-bit applications and one for x64 applications. By default, 32-bit applications running on x64 systems under WOW64 have access only to the 32-bit view. Using \c{SetRegView 64} allows the installer to access keys in the x64 view of the registry.
Sets the registry view affected by \R{registry}{registry commands}. On 64-bit versions of Windows there are two views; one for 32-bit applications and one for 64-bit applications. By default, 32-bit applications running on 64-bit systems (WOW64) only have access to the 32-bit view. Using \c{SetRegView 64} allows the installer to access keys in the 64-bit view of the registry.
Affects \R{deleteregkey}{DeleteRegKey}, \R{deleteregvalue}{DeleteRegValue}, \R{enumregkey}{EnumRegKey}, \R{enumregvalue}{EnumRegValue}, \R{readregdword}{ReadRegDWORD}, \R{readregstr}{ReadRegStr}, \R{writeregbin}{WriteRegBin}, \R{writeregdword}{WriteRegDWORD}, \R{writeregstr}{WriteRegStr} and \R{writeregexpandstr}{WriteRegExpandStr}.
Does not affect \R{ainstalldirregkey}{InstallDirRegKey}. Instead, the registry can be read using \R{readregstr}{ReadRegStr} in \R{oninit}{.onInit}.
Does not affect \R{ainstalldirregkey}{InstallDirRegKey}. Instead, the registry must be read using \R{readregstr}{ReadRegStr} in \R{oninit}{.onInit}.
\c SetRegView 32
\c ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir

2
Docs/src/modernui.but
View file

@ -1,6 +1,6 @@
\A{modernui} Modern User Interface
NSIS 2 makes it is possible to create installers with a custom user interface. The Modern UI is an interface with a style like the wizards of recent Windows versions.
NSIS 2 makes it is possible to create installers with a custom user interface. The Modern UI is a interface with a style like the wizards of recent Windows versions.
This new interface also features new pages (Welcome, Finish, Start Menu) and a description area on the components page. The interface and the graphics can be customized using the provided settings.
Using the Modern UI macros and language files, writing scripts with a modern interface is easy.

18
Docs/src/pages.but
View file

@ -2,7 +2,7 @@
Each (non-silent) NSIS installer has a set of pages. Each page can be a NSIS built-in page or a custom page created by a user's function (with \L{../Docs/nsDialogs/Readme.html}{nsDialogs} or \L{../Docs/InstallOptions/Readme.html}{InstallOptions} for example).
Using the script you can control the pages' order, appearance, and behavior. You can skip pages, paint them white, force the user to stay in a certain page until a certain condition is met, show a readme page, show custom designed pages for input and more. In this section, you will learn how to control all of the above.
The script controls the page order, appearance, and behavior. You can skip pages, paint them white, force the user to stay in a certain page until a certain condition is met, show a readme page, show custom designed pages for input and more. In this section you will learn how to do all of the above.
There are two basic commands regarding pages, \R{page}{Page} and \R{uninstpage}{UninstPage}. The first adds a page to the installer, the second adds a page to the uninstaller. On top of those two there is the \R{pageex}{PageEx} command which allows you to add a page to either one and with greater amount of options. \R{pageex}{PageEx} allows you to set options to the specific page you are adding instead of using the default that's set outside of \R{pageex}{PageEx}.
@ -17,17 +17,17 @@ The page order is set simply by the order \R{page}{Page}, \R{uninstpage}{UninstP
\c UninstPage uninstConfirm
\c UninstPage instfiles
This code will tell NSIS to first show the license page, then the components selection page, then the directory selection page and finally the install log where sections are executed, just like in old installers. The uninstaller will first show the uninstall confirmation page and then the uninstallation log.
This code will tell NSIS to first show the license page, then the components selection page, then the directory selection page and finally the install log where sections are executed. The uninstaller will first show the uninstall confirmation page and then the uninstallation log.
You can specify the same page type more than once.
For backwards compatibility with old NSIS scripts, the following installer pages will be added if no installer page commands are used: license (if \R{alicensetext}{LicenseText} and \R{alicensedata}{LicenseData} were specified), components (if \R{acomponenttext}{ComponentText} was specified and there is more than one visible section), directory (if \R{adirtext}{DirText} was specified) and instfiles. When there are no uninstaller page commands, the following uninstaller pages will be added: uninstall confirmation page (if \R{auninstalltext}{UninstallText} was specified) and instfiles. This method is deprecated, converting scripts to use page commands is highly recommended because you can use the new standard language strings.
For backwards compatibility with old NSIS scripts, the following installer pages will be added if no installer page commands are used: license (if \R{alicensetext}{LicenseText} and \R{alicensedata}{LicenseData} were specified), components (if \R{acomponenttext}{ComponentText} was specified and there is more than one visible section), directory (if \R{adirtext}{DirText} was specified) and instfiles. When there are no uninstaller page commands the following uninstaller pages will be added: uninstall confirmation page (if \R{auninstalltext}{UninstallText} was specified) and instfiles. This method is deprecated, converting scripts to use page commands is highly recommended because you can use the new standard language strings.
\S{pageoptions} Page Options
Each page has its unique set of data that defines how it will look and act. This section describes what data each type of page uses and how you can set it. \R{pagecallbacks_explain}{Callback functions} are described below and are not dealt with in this section.
The list below lists what commands affect the certain page type. Unless mentioned otherwise, these commands can be used both in and out of a \R{pageex}{PageEx} block. If used inside a \R{pageex}{PageEx} block they will only affect the current page being set by \R{pageex}{PageEx}, else they will set the default for every other page.
The list below lists the commands that affect a certain page type. Unless otherwise mentioned, these commands can be used both inside and outside of a \R{pageex}{PageEx} block. If used inside a \R{pageex}{PageEx} block they will only affect the current page being set by PageEx, otherwise they will set the default for all other pages.
\e{License page}
@ -45,7 +45,7 @@ The list below lists what commands affect the certain page type. Unless mentione
\b \R{adirtext}{DirText}
\b \R{adirvar}{DirVar} - can only be used in \R{pageex}{PageEx}
\b \R{adirvar}{DirVar} (can only be used in \R{pageex}{PageEx})
\b \R{adirverify}{DirVerify}
@ -57,19 +57,19 @@ The list below lists what commands affect the certain page type. Unless mentione
\e{Uninstall confirmation page}
\b \R{adirvar}{DirVar} - can only be used in \R{pageex}{PageEx}
\b \R{adirvar}{DirVar} (can only be used in \R{pageex}{PageEx})
\b \R{auninstalltext}{UninstallText}
To set the page caption use \R{acaption}{Caption}.
Use \R{acaption}{Caption} to set the page caption.
\S{pagecallbacks_explain} Callbacks
Each built-in page has three callback functions: the pre-function, the show-creation function and the leave-function. The pre-function is called right before the page is created, the show-function is called right after it is created and before it is shown and the leave-function is called right after the user has pressed the next button and before the page is left.
Each built-in page has three callback functions: the pre-function, the show function and the leave-function. The pre-function is called right before the page is created, the show-function is called right after it has been created but before it is shown and the leave-function is called right after the user has pressed the next button (before actually leaving the page).
\b The pre-function allows you to skip the page using \R{abort}{Abort}.
\b The show-function allows you to tweak the page's user interface with \R{createfont}{CreateFont}, \R{setctlcolors}{SetCtlColors}, \R{sendmessage}{SendMessage} and others.
\b The show-function allows you to tweak the page's user interface with \R{createfont}{CreateFont}, \R{setctlcolors}{SetCtlColors}, \R{sendmessage}{SendMessage} etc.
\b The leave-function allows you to force the user to stay on the current page using \R{abort}{Abort}.

4
Docs/src/plugin.but
View file

@ -2,7 +2,7 @@
The abilities of the NSIS scripting language can be extended by utilising functionality provided in a DLL file. Probably the best known example of this is the InstallOptions.dll bundled with every NSIS release.
When the NSIS compiler starts it scans the plug-ins directory for DLLs and makes a list of the plug-ins found and their exported functions. During compilation if a sequence such as fred::flintstone is encountered where the compiler expected to find a language keyword the compiler will look through this list. If a list entry specifies that fred.dll exports function flintstone NSIS will pack the fred.dll file into the created installer binary.
When the NSIS compiler starts it scans the plug-ins directory for DLLs and makes a list of the plug-ins found and their exported functions. During compilation, if a sequence such as fred::flintstone is encountered where the compiler expected to find a language keyword the compiler will look through this list. If a list entry specifies that fred.dll exports function flintstone NSIS will pack the fred.dll file into the created installer binary.
During execution of a plug-in command NSIS will unpack the necessary DLL to a temporary folder ($PLUGINSDIR), push all of the arguments specified (right-to-left order), and then execute the DLL function.
@ -16,4 +16,4 @@ All parameters are pushed onto the stack (in this case, the plug-in function onl
\S1{calldiskplug} Calling plug-ins manually
If you want to call a plug-in that is stored on user's hard drive or somewhere else, use \R{callinstdll}{CallInstDLL}. Almost all plug-ins provide installer functionality, so using plug-in commands is way easier. Using \R{callinstdll}{CallInstDLL} can be useful when you have created plug-ins that should be linked to a certain version of your application and are being copied to the installation folder.
If you want to call a plug-in that is stored on user's hard drive or somewhere else, use \R{callinstdll}{CallInstDLL}. Almost all plug-ins provide installer functionality, so using plug-in commands is way easier. Using \R{callinstdll}{CallInstDLL} can be useful when you have created plug-ins that are linked to a certain version of your application and are being copied to the installation folder.

4
Docs/src/registry.but
View file

@ -111,7 +111,7 @@ Reads from entry_name in [section_name] of ini_filename and stores the value int
\c user_var(output) root_key sub_key name
Reads a 32 bit DWORD from the registry into the user variable $x. Valid values for root_key are listed under \R{writeregstr}{WriteRegStr}. The error flag will be set and $x will be set to an empty string ("" which is 0) if the DWORD is not present. If the value is present, but is not a DWORD, it will be read as a string and the error flag will be set.
Reads a 32-bit DWORD from the registry into the user variable $x. Valid values for root_key are listed under \R{writeregstr}{WriteRegStr}. The error flag will be set and $x will be set to an empty string ("" which is interpreted as 0 in math operations) if the DWORD is not present. If the value is present, but is not a DWORD, it will be read as a string and the error flag will be set.
\c ReadRegDWORD $0 HKLM Software\NSIS VersionBuild
@ -146,7 +146,7 @@ This command writes a block of binary data to the registry. Valid values for roo
\c root_key subkey key_name value
This command writes a dword (32 bit integer) to the registry (a user variable can be specified). Valid values for root_key are listed under \R{writeregstr}{WriteRegStr}. The error flag is set if the dword could not be written to the registry. If the registry key doesn't exist it will be created.
This command writes a DWORD (32-bit integer) to the registry (a user variable can be specified). Valid values for root_key are listed under \R{writeregstr}{WriteRegStr}. The error flag is set if the dword could not be written to the registry. If the registry key doesn't exist it will be created.
\c WriteRegDWORD HKLM "Software\My Company\My Software" "DWORD Value" 0xDEADBEEF

4
Docs/src/script.but
View file

@ -53,7 +53,7 @@ To represent strings that have spaces, use quotes:
\c 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.
Quotes only have the property of containing a parameter if they surround the rest of the parameter. They can be either single quotes, double quotes, or the backward single quote.
You can escape quotes using $\\:
@ -66,7 +66,7 @@ It is also possible to put newlines, tabs etc. in a string using $\\r, $\\n, $\\
\\<b\\>Variables\\</b\\>
Variables start with $. User variables should be declared.
Variables start with $. User variables must be declared.
\c Var MYVAR
\c

18
Docs/src/sec.but
View file

@ -4,7 +4,7 @@
\c section_index section_flags
Sets the section's flags. The flag is a 32 bit integer. The first bit (lowest) represents whether the section is currently selected, the second bit represents whether the section is a section group (don't modify this unless you really know what you are doing), the third bit represents whether the section is a section group end (again, don't modify), the fourth bit represents whether the section is shown in bold or not, the fifth bit represents whether the section is read-only, the sixth bit represents whether the section group is to be automatically expanded, the seventh bit is set for section groups which are partially selected, the eighth bit is internally used for partially selected section group toggling and the ninth bit is used for reflecting section name changes. The error flag will be set if an out of range section is specified.
Sets the section's flags. The flag is a 32-bit integer. The first bit (lowest) represents whether the section is currently selected, the second bit represents whether the section is a section group (don't modify this unless you really know what you are doing), the third bit represents whether the section is a section group end (again, don't modify), the fourth bit represents whether the section is shown in bold or not, the fifth bit represents whether the section is read-only, the sixth bit represents whether the section group is to be automatically expanded, the seventh bit is set for section groups which are partially selected, the eighth bit is internally used for partially selected section group toggling and the ninth bit is used for reflecting section name changes. The error flag will be set if an out of range section is specified.
Each flag has a name, prefixed with `SF_`:
@ -33,7 +33,7 @@ For more useful macros and definitions, see Include\\Sections.nsh.
\c section_index user_var(output)
Retrieves the section's flags. See above for a description of the flag. The error flag will be set if an out of range section is specified.
Retrieves the section's flags. See SectionSetFlags for a description of the flags. The error flag will be set if an out of range section is specified.
\c Section test test_section_id
\c SectionEnd
@ -83,7 +83,7 @@ Sets the install types the section specified by section_index defaults to the en
\c SectionSetInstTypes 0 5
because the binary value for 5 is "00000101". The error flag will be set if the section index specified is out of range.
because the binary value for 5 is "...00101". The error flag will be set if the section index specified is out of range.
\c Section test test_section_id
\c SectionEnd
@ -113,7 +113,7 @@ Retrieves the install types flags array of a section. See above explanation abou
\c section_index new_size
Sets the Size of the section specified by section_index. Note that the Index starts with Zero. The Value for Size must be entered in KiloByte and supports only whole numbers.
Sets the size of the section specified by section_index. Note that the index starts with zero. The Value for Size must be entered in KiloByte and supports only whole numbers.
\c Section test test_section_id
\c SectionEnd
@ -127,7 +127,7 @@ Sets the Size of the section specified by section_index. Note that the Index sta
\c section_index user_var
Gets the Size of the section specified by section_index and stores the value in the given User Variable. Note that the Index starts with Zero. The error flag will be set if the section index is out of range.
Gets the size of the section specified by section_index and stores the value in the given user variable. Note that the index starts with zero. The error flag will be set if the section index is out of range.
\c Section test test_section_id
\c SectionEnd
@ -143,19 +143,19 @@ Gets the Size of the section specified by section_index and stores the value in
\c inst_type_idx
Sets the current \R{ainsttype}{InstType}. inst_type_idx should be between 0 and 31. The Error Flag is \\<b\\>not\\</b\\> set if an out of range \R{ainsttype}{InstType} was used.
Sets the current \R{ainsttype}{InstType}. inst_type_idx should be between 0 and 31. The error flag is \\<b\\>not\\</b\\> set if an out of range \R{ainsttype}{InstType} was used.
\S2{sgetcurinsttype} GetCurInstType
\c user_var
Get the current \R{ainsttype}{InstType} and stores it in user_var. If the first install type is selected, 0 will be put in user_var. If the second install type is selected, 1 will be put in user_var, and so on. The value of $\{NSIS_MAX_INST_TYPES\} (32 by default) means that the user selected a custom set of sections. Note that simply selecting "Custom" in the drop-down menu is not enough to trigger this. The value is calculated by the sections actually selected.
Get the current \R{ainsttype}{InstType} and stores it in user_var. If the first install type is selected, 0 will be put in user_var. If the second install type is selected, 1 will be put in user_var, and so on. The value of $\{NSIS_MAX_INST_TYPES\} (32 by default) means that the user selected a custom set of sections (Simply selecting "Custom" in the drop-down menu is not enough to trigger this, the value is calculated by the sections actually selected).
\S2{sinsttypesettext} InstTypeSetText
\c inst_type_idx text
Sets the Text of the specified \R{ainsttype}{InstType}. If the Text is empty than the \R{ainsttype}{InstType} is removed. By using a previously unused inst_type_idx number you can create new InstTypes. To add/remove Sections to this new \R{ainsttype}{InstType} see \R{sectionsetinsttypes}{SectionSetInstTypes}. Unlike \R{ssectionin}{SectionIn} the index is zero based, which means the first install type's index is 0.
Sets the text of the specified \R{ainsttype}{InstType}. If the text is empty then the \R{ainsttype}{InstType} is removed. By using a previously unused inst_type_idx number you can create new InstTypes. To add/remove Sections to this new \R{ainsttype}{InstType} see \R{sectionsetinsttypes}{SectionSetInstTypes}. Unlike \R{ssectionin}{SectionIn} the index is zero based, which means the first install type's index is 0.
\c InstType a
\c InstType b
@ -171,7 +171,7 @@ Sets the Text of the specified \R{ainsttype}{InstType}. If the Text is empty tha
\c inst_type_idx user_var
Gets the Text of the specified \R{ainsttype}{InstType}.
Gets the text of the specified \R{ainsttype}{InstType}.
\c InstType a
\c InstType b

6
Docs/src/sections.but
View file

@ -4,7 +4,7 @@ Each NSIS installer contains one or more sections. Each of these sections are cr
\b Each section contains zero or more instructions.
\b Sections are executed in order by the resulting installer, and if \R{acomponenttext}{ComponentText} is set, the user will have the option of disabling/enabling each visible section.
\b Sections are executed in order by the resulting installer, and if a component page is used, the user will have the option of disabling/enabling each visible section.
\b If a section's name is 'Uninstall' or is prefixed with 'un.', it's an uninstaller section.
@ -24,7 +24,7 @@ Tells the installer that the current section needs an additional "size_kb" kilob
\c [/o] [([!]|[-])section_name] [section_index_output]
Begins and opens a new section. If section_name is empty, omitted, or begins with a -, then it is a hidden section and the user will not have the option of disabling it. If the section name is 'Uninstall' or is prefixed with 'un.', then it is a an uninstaller section. If \e{section_index_output} is specified, the parameter will be \R{define}{!defined} with the section index (that can be used for \R{sectionsettext}{SectionSetText} etc). If the section name begins with a !, the section will be displayed as bold. If the /o switch is specified, the section will be unselected by default.
Begins and opens a new section. If section_name is empty, omitted, or begins with a -, then it is a hidden section and the user will not have the option of disabling it. If the section name is 'Uninstall' or is prefixed with 'un.', then it is a an uninstaller section. If \e{section_index_output} is specified, the parameter will be \R{define}{!defined} with the section index (can be used with \R{sectionsettext}{SectionSetText} etc). If the section name begins with a !, the section will be displayed as bold. If the /o switch is specified, the section will be unselected by default.
\c Section "-hidden section"
\c SectionEnd
@ -92,7 +92,7 @@ This command specifies which install types (see \R{ainsttype}{InstType}) the cur
\c [/e] section_group_name [index_output]
This command inserts a section group. The section group must be closed with \R{ssectiongroupend}{SectionGroupEnd}, and should contain 1 or more sections. If the section group name begins with a !, its name will be displayed with a bold font. If /e is present, the section group will be expanded by default. If \e{index_output} is specified, the parameter will be !defined with the section index (that can be used for \R{sectionsettext}{SectionSetText} etc). If the name is prefixed with 'un.' the section group is an uninstaller section group.
This command inserts a section group. The section group must be closed with \R{ssectiongroupend}{SectionGroupEnd}, and should contain 1 or more sections. If the section group name begins with a !, its name will be displayed with a bold font. If /e is present, the section group will be expanded by default. If \e{index_output} is specified, the parameter will be !defined with the section index (can be used with \R{sectionsettext}{SectionSetText} etc). If the name is prefixed with 'un.' the section group is an uninstaller section group.
\c SectionGroup "some stuff"
\c Section "a section"

2
Docs/src/silent.but
View file

@ -16,7 +16,7 @@ To check if the installer/uninstaller is silent use \R{ifsilent}{IfSilent}.
To make sure your installer will be silent when it needs to, you should check with \R{ifsilent}{IfSilent} before each command that might require user intervention or create a window. The \R{messagebox}{MessageBox} command, which is the most common culprit in silent installers, has the /SD switch to set a default answer for silent installers. If you want your installer/uninstaller to be able to be completely silent you should use this switch. All internal NSIS message boxes have defaults for silent installers. The \L{../Examples/silent.nsi}{silent.nsi example} demonstrates all aspects of this topic.
Since the directory page can not be shown on silent installers, the user has an option to specify the installation directory on the command line (this also works on non-silent installers/uninstallers). To do that, the user uses the /D switch as in the following example:
Since the directory page is not shown in silent installers the user has an option to specify the installation directory on the command line (this also works on non-silent installers/uninstallers). To do that, the user uses the /D switch as in the following example:
\c foo.exe /S /D=C:\Program Files\Foo

2
Docs/src/stack.but
View file

@ -35,6 +35,6 @@ Pops a string off of the stack into user variable $x. If the stack is empty, the
\c string
Pushes a string onto the stack. The string can then be Popped off of the stack.
Pushes a string onto the stack. The string can then be Pop'ed off of the stack.
\c Push "a string"

5
Docs/src/string.but
View file

@ -4,7 +4,7 @@
\c user_var(destination) str [maxlen] [start_offset]
Sets the user variable $x with str. Note that str can contain other variables, or the user variable being set (concatenating strings this way is possible, etc). If maxlen is specified, the string will be a maximum of maxlen characters (if maxlen is negative, the string will be truncated abs(maxlen) characters from the end). If start_offset is specified, the source is offset by it (if start_offset is negative, it will start abs(start_offset) from the end of the string).
Sets the user variable $x with str. str can contain variables (including the user variable being set (concatenating strings this way is possible, etc)). If maxlen is specified, the string will be a maximum of maxlen characters (if maxlen is negative, the string will be truncated abs(maxlen) characters from the end). If start_offset is specified, the source is offset by it (if start_offset is negative, it will start abs(start_offset) from the end of the string).
\c StrCpy $0 "a string" # = "a string"
\c StrCpy $0 "a string" 3 # = "a s"
@ -12,11 +12,12 @@ Sets the user variable $x with str. Note that str can contain other variables, o
\c StrCpy $0 "a string" "" 2 # = "string"
\c StrCpy $0 "a string" "" -3 # = "ing"
\c StrCpy $0 "a string" 3 -4 # = "rin"
\c StrCpy $0 "$0$0" # = "rinrin"
\S2{StrLen} StrLen
\c user_var(length output) str
Sets user variable $x with the length of str.
Sets user variable $x to the length of str.
\c StrLen $0 "123456" # = 6

45
Docs/src/tutorial.but
View file

@ -4,13 +4,13 @@
Most software packages you download or buy come with an installer. The installer copies and/or updates files, writes registry keys, writes configuration, creates shortcuts, etc. All of this is done automatically for the user. All the user needs to do is supply some information and the installer will do the rest. The user goes through a wizard, makes the appropriate choices and waits until the installer finishes. After the installer has finished the user is left only with the simple task of starting the program. The user doesn't have to worry about things he might have forgotten because all of the necessary steps were done by the installer.
NSIS is a tool for developers to create such installers. NSIS allows you to create everything from basic installers that just copy files to very complex installers that handle a lot of advanced tasks such as writing registry keys, settings environment variables, downloading the latest files from the internet, customizing the configuration file and more. NSIS is very flexible and its scripting language is easy to learn.
NSIS is a tool for developers to create such installers. NSIS allows you to create everything from basic installers that just copies files to very complex installers that handle a lot of advanced tasks such as writing registry keys, settings environment variables, downloading the latest files from the internet, customizing configuration files and more. NSIS is very flexible and its scripting language is easy to learn.
NSIS compiles all of the files and the installation script into one executable file, so your application will be easy to distribute. NSIS adds only about 34KB of code of its own (for the default configuration) to the data. NSIS boasts the smallest overhead available while still providing a lot of options thanks to its powerful scripting language and support of external plug-ins.
NSIS compiles all of the files and the installation script into one executable file so your application will be easy to distribute. NSIS adds only about 34KB of code of its own (for the default configuration) to the data. NSIS boasts the smallest overhead available while still providing a lot of options thanks to its powerful scripting language and support of external plug-ins.
\H{tutscriptfiles} Script Files
To create a NSIS installer, you first have to write a NSIS script. A NSIS script is just a regular text file with a special syntax. You can edit scripts with every text editor. It's recommended you use a text editor that shows line numbers because NSIS uses line numbers to indicate where errors lie, and to warn you about where errors might lie. An editor that supports syntax highlighting is also recommended. You can download editors made especially for NSIS and files for syntax highlighting at the \W{http://nsis.sf.net/}{NSIS Wiki}.
To create a NSIS installer you first have to write a NSIS script. A NSIS script is just a regular text file with a special syntax. You can edit scripts with any text editor. It's recommended to use a text editor that shows line numbers because NSIS uses line numbers to indicate where errors lie, and to warn you about where errors might lie. An editor that supports syntax highlighting is also recommended. You can download editors made especially for NSIS and files for syntax highlighting from the \W{http://nsis.sf.net/}{NSIS Wiki}.
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. The compiler will treat the new line as an addition to the previous line and will not expect a new command. For example:
@ -27,7 +27,7 @@ The default extension for a script file is .nsi. Header files have the .nsh exte
\H{tutstructure} Scripting structure
A NSIS script can contain Installer Attributes and Sections/Functions. You can also use Compiler Commands for compile-time operations. Required is the \R{aoutfile}{OutFile} instruction, which tells NSIS where to write the installer, and one section.
A NSIS script contains Installer Attributes, Pages and Sections/Functions. You can also use Compiler Commands for compile-time operations. The \R{aoutfile}{OutFile} instruction is required and tells NSIS where to write the installer, you also need at least one section.
\S1{installerattributes} Installer Attributes
@ -52,7 +52,7 @@ For the installer, this typical set of pages will display a license agreement, a
\S1{tut-sections} Sections
In a common installer there are several things the user can install. For example in the NSIS distribution installer you can choose to install the source code, additional plug-ins, examples and more. Each of these components has its own piece of code. If the user selects to install this component, then the installer will execute that code. In the script, that code is defined in sections. Each section corresponds to one component in the components page. The section's name is the displayed component name, and the section code will be executed if that component is selected. It is possible to build your installer with only one section, but if you want to use the components page and let the user choose what to install, you'll have to use more than one section.
It's common for installers to have several things the user can install. For example in the NSIS distribution installer you can choose to install additional tools, plug-ins, examples and more. Each of these components has its own piece of code. If the user selects to install this component then the installer will execute that code. In the script, that code is defined in sections. Each section corresponds to one component on the components page. The section's name is the displayed component name and the section code will be executed if that component is selected. It is possible to build your installer with only one section but if you want to use the components page and let the user choose what to install, you'll have to use more than one section.
Uninstallers can also have multiple sections. Uninstaller section names are prefixed with 'un.'. For example:
@ -80,9 +80,9 @@ For more information about sections see \R{sections}{Sections}.
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.
User functions are called by the user from within sections or other functions using the \R{call}{Call} instruction. User functions will not execute unless you call them. After the code of the function will be executed the installer will continue executing the instructions that came after the \R{call}{Call} instruction, unless you have aborted the installation inside the function. User functions are very useful if you have a set of instructions that need to be executed at several locations in the installers. If you put the code into a function you can save the copying time and you can maintain the code more easily.
User functions are called by the user from within sections or other functions using the \R{call}{Call} instruction. User functions will not execute unless you call them. After the code in the function has executed the installer will continue executing the instructions that came after the \R{call}{Call} instruction, unless you have aborted the installation inside the function. User functions are very useful if you have a set of instructions that need to be executed at several locations in the installers. If you put the code into a function you can save the copying time and you can maintain the code more easily.
Callback functions are called by the installer upon certain defined events such as when the installer starts. Callbacks are optional. 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.
Callback functions are called by the installer upon certain defined events such as when the installer starts. Callbacks are optional. If for example you want to welcome the user to your installer you can 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.
\c Function .onInit
\c MessageBox MB_YESNO "This will install My Program. Do you wish to continue?" IDYES gogogo
@ -100,7 +100,7 @@ For more information about functions see \R{functions}{Functions}.
Conditionally executing code, or executing code in a loop can be done using \R{strcmp}{StrCmp}, \R{intcmp}{IntCmp}, \R{iferrors}{IfErrors}, \R{goto}{Goto} and more. However, there's a much easier way do this. The LogicLib provides some very simple macros that allow easy construction of complex logical structures. Its syntax, explained in \L{../Include/LogicLib.nsh}{LogicLib.nsh}, is similar to other programming languages and can prove to be simpler for beginners and advanced users alike.
For example, checking a value of a variable without the LogicLib can be done as followed.
For example, checking a value of a variable without the LogicLib can be done as follows.
\c StrCmp $0 'some value' 0 +3
\c MessageBox MB_OK '$$0 is some value'
@ -112,7 +112,7 @@ For example, checking a value of a variable without the LogicLib can be done as
\c MessageBox MB_OK '$$0 is "$0"'
\c done:
However, with the LogicLib, the code gets is much more readable and easy to understand, as can be seen in the following example.
However, with the LogicLib the code is much more readable and easy to understand, as can be seen in the following example.
\c ${If} $0 == 'some value'
\c MessageBox MB_OK '$$0 is some value'
@ -145,7 +145,7 @@ Multiple conditions are also supported. The following example will notify the us
The LogicLib removes the need for labels and relative jumps, thus prevents label name conflicts, and removes the need to manually adjust relative jump offsets every time the script is changed.
It also simplifies looping, by supporting the common while, do and for loops. All of the following examples count to five using the LogicLib.
It also simplifies looping by supporting the common while, do and for loops. All of the following examples count to five using the LogicLib.
\c StrCpy $R1 0
\c ${While} $R1 < 5
@ -163,7 +163,7 @@ It also simplifies looping, by supporting the common while, do and for loops. Al
\c DetailPrint $R1
\c ${LoopUntil} $R1 >= 5
To use the LogicLib, the following line needs to put at the top of the script.
To use the LogicLib the following line needs to be added near the top of the script.
\c !include LogicLib.nsh
@ -183,7 +183,7 @@ Declaring and using a user variable:
\c
\c SectionEnd
In addition there is a Stack, which can also be used for temporary storage. To access the stack use the commands \R{Push}{Push} and \R{Pop}{Pop}. \R{Push}{Push} adds a value to the stack, \R{Pop}{Pop} removes one and sets the variable.
In addition there is a stack, which can also be used for temporary storage. To access the stack use the commands \R{Push}{Push} and \R{Pop}{Pop}. \R{Push}{Push} adds a value to the stack, \R{Pop}{Pop} removes one and sets the variable.
For shared code, there are \R{varother}{20 registers available} (like $0 and $R0). These static variables don't have to be declared and you won't get any name conflicts. If you want to use these variables in shared code, store the original values on the stack and restore the original values afterwards.
@ -207,13 +207,13 @@ The more you work with NSIS the more complex the scripts will become. This will
\S1{tutscriptexecution} Script Execution
When a user runs an installer or an uninstaller, pages are displayed in the order they were defined in the script. When the instfiles page is reached, sections, corresponding to the selected components, are executed in the order they were defined in the script. If the components page is not displayed, all sections are executed, assuming they were not unselected or somehow disabled by the script.
When a user runs an installer or uninstaller, pages are displayed in the order they were defined in the script. When the instfiles page is reached, sections, corresponding to the selected components, are executed in the order they were defined in the script. If the components page is not displayed, all sections are executed, assuming they were not unselected or somehow disabled by the script.
Beside code in sections, there's also code in callback functions. If defined, they might be executed before the sections code. For example, the \R{oninit}{.onInit} callback function is executed before anything else in the script. There are also \R{pagecallbacks_explain}{page callback functions} which are executed at certain points of the page display process.
\S1{compilercommands} 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. For example:
Compiler commands will be executed at 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. For example:
\c !define VERSION "1.0.3"
\c Name "My Program ${VERSION}"
@ -221,7 +221,7 @@ Compiler commands will be executed on compile time on your computer. They can be
For more information about defines see \R{compdefines}{Conditional Compilation}.
Another common use is macros. Macros are used to insert code on compile time, depending on defines and using the values of the defines. The macro's commands are inserted 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. For example:
Another common use is macros. Macros are used to insert code at compile time, depending on defines and using the values of the defines. The macro's commands are inserted 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. For example:
\c !macro MyFunc UN
\c Function ${UN}MyFunc
@ -242,19 +242,19 @@ For more information see \R{comptime}{Compile Time Commands}.
The second thing you need to do in order to create your installer after you have created your script is to compile your script. MakeNSIS.exe is the NSIS compiler. It reads your script, parses it and creates an installer for you.
To compile you have to right-click your .nsi file and select Compile NSIS Script. This will cause MakeNSISW, the NSIS Compiler Interface, to launch and call MakeNSIS to compile your script. MakeNSISW will get the output of MakeNSIS and present it to you in a window where you can see it, copy it, test the installer, browse for it and more. Using makensis.exe from the command prompt is also possible.
To compile you can right-click your .nsi file and select Compile NSIS Script. This will cause MakeNSISW, the NSIS Compiler Interface, to launch and call MakeNSIS to compile your script. MakeNSISW receives the output of MakeNSIS and presents it to you in a window where you can see it, copy it, test the installer and more. Using makensis.exe from the command prompt is also possible.
The compiler will check your script and give you warnings or an error. If an error occurs (i.e. 2 parameters required but only 1 given) the compiler will abort and a short error message including the line number will be displayed. For non-critical errors the compiler will give a warning (i.e. two \R{adirtext}{DirText} commands in one script). If your script has no errors the compiler will output an installer for you to distribute.
NSIS supports different compression methods, as explained \R{asetcompressor}{here}. ZLIB is the default compression method, which is fast and uses only a little bit of memory. LZMA is a good method for the creation of small installers for internet distribution. BZIP2 usually compresses better than ZLIB but not as good as LZMA, it is useful if you need lower memory usage or fast script compilation.
It it also possible to compile Windows installer on Linux, BSD or Mac OS X servers. See \R{build}{Building NSIS} for details.
It it also possible to compile Windows installers on Linux, BSD or Mac OS X servers. See \R{build}{Building NSIS} for details.
\H{tutmodernui} Modern UI
A popular user interface for NSIS is the Modern User Interface. It has an interface like the wizards of recent Windows versions. The Modern UI is not only a customized resource file, it has a lots of new interface elements. It features a white header to describe the current step, a description area on the component page, a welcome page, a finish page that allows the user to run the application or reboot the system and more.
For more information, check the \L{../Docs/Modern UI 2/Readme.html}{Modern UI 2 Readme} and the \L{../Examples/Modern UI}{Modern UI Examples}.
For more information, see the \L{../Docs/Modern UI 2/Readme.html}{Modern UI 2 Readme} and the \L{../Examples/Modern UI}{Modern UI Examples}.
\H{tutplugin} Plug-ins
@ -267,15 +267,18 @@ A plug-in call looks like this:
Every plug-in's function has its own requirements when it comes to parameters, some will require none, some will accept as many parameters as you want to send. Examples:
\c nsExec::ExecToLog '"${NSISDIR}\makensis.exe" /CMDHELP'
\c Pop $0 ; Process exit code or "error"
\c InstallOptions::dialog "$PLUGINSDIR\test.ini"
\c Pop $0 ; success/back/cancel/error
\c NSISdl::download http://download.nullsoft.com/winamp/client/winamp291_lite.exe $R0
\c Pop $0 ; "success" or a error code
The plug-ins that NSIS knows of are listed at the top of the output of the compiler. NSIS searches for plug-ins in the \L{../Plugins/}{Plugins folder} under your NSIS directory and lists all of their available functions. You can use \R{addplugindir}{!addplugindir} to tell NSIS to search in other directories too.
The plug-ins that NSIS knows of are listed at the top of the compiler output (verbose level 4). NSIS searches for plug-ins in the \L{../Plugins/}{Plugins folder} under your NSIS directory and lists all of their available functions. You can use \R{addplugindir}{!addplugindir} to tell NSIS to search in other directories too.
The NSIS distribution already included many plug-ins. \L{../Docs/InstallOptions/Readme.html}{InstallOptions} is a popular plug-in that allows you to create custom pages, in combination with the NSIS Page commands (See \R{pages}{Pages}). The \L{../Docs/StartMenu/Readme.txt}{Startmenu plug-in} provides a page that allows the user to choose a Start Menu folder. There are a lot of plug-ins for different purposes, have a look at the \L{../Docs/}{Docs folder} for help files and examples. You can find additional plug-ins on-line: \W{http://nsis.sf.net/}{NSIS Wiki}.
The NSIS distribution already includes many plug-ins. \L{../Docs/InstallOptions/Readme.html}{InstallOptions} is a popular plug-in that allows you to create custom pages, in combination with the NSIS Page commands (See \R{pages}{Pages}). The \L{../Docs/StartMenu/Readme.txt}{Startmenu plug-in} provides a page that allows the user to choose a Start Menu folder. There are a lot of plug-ins for different purposes, take a look in the \L{../Docs/}{Docs folder} for help files and examples. You can find additional plug-ins online: \W{http://nsis.sf.net/}{NSIS Wiki}.
You can also create a plug-in yourself. C/C++ and Delphi header files are already available, see the \L{../Examples/Plugin/}{example plugin} for how to do this. Source code of included plug-ins can also be found in the source code package.
\H{tutmore} More
This tutorial has described the basic NSIS features, to learn more about everything NSIS can do, take some time to read this manual.
This tutorial has described the basic NSIS features, to learn more about everything NSIS can do, take some time to read the rest of this manual.

43
Docs/src/ui.but
View file

@ -2,7 +2,7 @@
\S2{BringToFront} BringToFront
Makes the installer window visible and brings it to the top of the window list. If an application was executed that shows itself in front of the installer, a \R{BringToFront}{BringToFront} would bring the installer back in focus.
Makes the installer window visible and brings it to the top of the window list. If an application was executed that shows itself in front of the installer, \R{BringToFront}{BringToFront} would bring the installer back in focus.
Recent Windows versions restrict the setting of foreground windows. If the user is working with another application during installation, the user may be notified using a different method.
@ -25,11 +25,11 @@ You can get the current font used by NSIS using the ^Font and ^FontSize \R{langs
Adds the string "user_message" to the details view of the installer.
\c DetailPrint "this message will show on the installation window"
\c DetailPrint "this message will be shown in the installation window"
\S2{enablewindow} EnableWindow
\c hwnd (1|0)
\c hwnd state(1|0)
Enables or disables mouse and keyboard input to the specified window or control. Possible states are 0 (disabled) or 1 (enabled).
@ -42,22 +42,22 @@ Enables or disables mouse and keyboard input to the specified window or control.
\c user_var(hwnd output) windowclass [windowtitle] [windowparent] [childafter]
Searches for a window. Behaves like the win32 FindWindowEx(). Searches by windowclass (and/or windowtitle if specified). If windowparent or childafter are specified, the search will be restricted as such. If windowclass or windowtitle is specified as "", they will not be used for the search. If the window is not found, the user variable returned is 0. To accomplish old-style \R{findwindow}{FindWindow} behavior, use \R{findwindow}{FindWindow} with \R{sendmessage}{SendMessage}.
Searches for a window. Behaves like Win32's FindWindowEx(). Searches by windowclass (and/or windowtitle if specified). If windowparent or childafter are specified, the search will be restricted as such. If windowclass or windowtitle is specified as "", they will not be used for the search. If the window is not found the user variable is set to 0. To accomplish old-style \R{findwindow}{FindWindow} behavior, use \R{findwindow}{FindWindow} with \R{sendmessage}{SendMessage}.
\c FindWindow $0 "#32770" "" $HWNDPARENT
\c FindWindow $0 "my window class" "my window title"
\c FindWindow $1 "#32770" "" $HWNDPARENT # Finds the inner dialog
\c FindWindow $2 "EDIT" "" $1 # Finds the first edit control in the inner dialog
\S2{getdlgitem} GetDlgItem
\c user_var(output) dialog item_id
Retrieves the handle of a control identified by item_id in the specified dialog box dialog. If you want to get the handle of a control on the inner dialog, first use FindWindow user_var(output) "#32770" "" $HWNDPARENT to get the handle of the inner dialog.
Retrieves the handle of a control identified by item_id in the specified dialog box dialog. If you want to get the handle of a control in the inner dialog, first use FindWindow to get the handle of the inner dialog.
\c GetDlgItem $0 $HWNDPARENT 1 # next/install button
\S2{hidewindow} HideWindow
Hides the installer.
Hides the installer window.
\S2{iswindow} IsWindow
@ -81,23 +81,14 @@ If HWND is a window, Gotos jump_if_window, otherwise, Gotos jump_if_not_window (
\c HWND msg wparam lparam [user_var(return value)] [/TIMEOUT=time_in_ms]
Sends a message to HWND. If a user variable $x is specified as the last parameter (or one before the last if you use /TIMEOUT), the return value of \R{sendmessage}{SendMessage} will be stored to it. Note that when specifying 'msg' you must just use the integer value of the message. If you wish to send strings use "STR:a string" as wParam or lParam where needed.
\b \e{WM_CLOSE} 16
\b \e{WM_COMMAND} 273
\b \e{WM_USER} 1024
Include WinMessages.nsh to have all of Windows messages defined in your script.
To send a string param, put STR: before the parameter, for example: "STR:Some string".
Use /TIMEOUT=time_in_ms to specify the duration, in milliseconds, of the time-out period.
Sends a message to HWND. If a user variable $x is specified as the last parameter (or one before the last if you use /TIMEOUT), the return value from SendMessage will be stored in it. Note that when specifying 'msg' you must just use the integer value of the message. Include WinMessages.nsh to have all Windows messages defined in your script. If you wish to send strings use "STR:a string" as wParam or lParam where needed. Use /TIMEOUT=time_in_ms to specify the duration, in milliseconds, of the time-out period.
\c !include WinMessages.nsh
\c FindWindow $0 "Winamp v1.x"
\c SendMessage $0 ${WM_CLOSE} 0 0
\c
\c GetDlgItem $1 $HWNDPARENT 2
\c SendMessage $1 ${WM_SETTEXT} 0 "STR:Goodbye"
\S2{setautoclose} SetAutoClose
@ -109,7 +100,7 @@ Overrides the default auto window-closing flag (specified for the installer usin
\c [/IMGID=item_id_in_dialog] [/RESIZETOFIT] path_to_bitmap_file.bmp
Sets the current bitmap file displayed as the branding image. If no IMGID is specified, the first image control found will be used, or the image control created by \R{aaddbrandingimage}{AddBrandingImage}. Note that this bitmap must be present on the user's machine. Use File first to put it there. If /RESIZETOFIT is specified the image will be automatically resized (very poorly) to the image control size. If you used \R{aaddbrandingimage}{AddBrandingImage} you can get this size, by compiling your script and watching for \R{aaddbrandingimage}{AddBrandingImage} output, it will tell you the size. \R{setbrandingimage}{SetBrandingImage} will not work when called from .onInit!
Sets the current bitmap file displayed as the branding image. If no IMGID is specified, the first image control found will be used, or the image control created by \R{aaddbrandingimage}{AddBrandingImage}. Note that this bitmap must be present on the user's machine. Use File first to put it there. If /RESIZETOFIT is specified the image will be automatically resized (very poorly) to the image control size. If you used \R{aaddbrandingimage}{AddBrandingImage} you can get this size by compiling your script and watching for \R{aaddbrandingimage}{AddBrandingImage} output, it will tell you the size. SetBrandingImage will not work when called from .onInit!
\S2{setdetailsview} SetDetailsView
@ -131,13 +122,15 @@ Sets mode at which commands print their status. None has commands be quiet, list
\c hwnd [/BRANDING] [text_color] [transparent|bg_color]
Sets a background color and the text color for a static control, edit control, button or a dialog. \e{text_color} and \e{bg_color} don't accept variables. Use \R{getdlgitem}{GetDlgItem} to get the handle (HWND) of the control. To make the control transparent specify "transparent" as the background color value. You can also specify /BRANDING with or without text color and background color to make the control completely gray (or any other color you choose). This is used by the branding text control in the MUI.
Sets the text and background color of a static control, edit control, button or a dialog. \e{text_color} and \e{bg_color} don't accept variables. Use \R{getdlgitem}{GetDlgItem} to get the handle (HWND) of the control. To make the control transparent specify "transparent" as the background color value. You can also specify /BRANDING with or without text color and background color to make the control completely gray (or any other color you choose). This is used by the branding text control in the MUI.
\c FindWindow $0 "#32770" "" $HWNDPARENT
\c GetDlgItem $0 $0 1006
\c SetCtlColors $0 0xFF0000 0x00FF00
\\<b\\>Warning:\\</b\\> setting the background color of check boxes to "transparent" may not function properly when using \c{\R{axpstyle}{XPStlye} on}. The background may be completely black, instead of transparent, when using certain Windows themes.
\NsisWarnBlockContainerBegin
\\<b\\>Warning:\\</b\\> Setting the background color of check boxes to "transparent" may not function properly when using \c{\R{axpstyle}{XPStyle} on}. The background may be completely black, instead of transparent, when using certain Windows themes.
\NsisWarnBlockContainerEnd
\S2{setsilent} SetSilent
@ -149,7 +142,7 @@ Sets the installer to silent mode or normal mode. See \R{asilentinstall}{SilentI
\c hwnd show_state
Sets the visibility of a window. Possible show_states are the same as \W{http://msdn2.microsoft.com/en-us/library/ms633548}{Windows ShowWindow} function. SW_* constants are defined in \L{../Include/WinMessages.nsh}{Include\\WinMessages.nsh}.
Sets the visibility of a window. Possible show_states are the same as the Windows \W{http://msdn2.microsoft.com/en-us/library/ms633548}{ShowWindow} function. SW_* constants are defined in \L{../Include/WinMessages.nsh}{Include\\WinMessages.nsh}.
\c !include WinMessages.nsh
\c GetDlgItem $0 $HWNDPARENT 1

2
Docs/src/uninstall.but
View file

@ -4,6 +4,6 @@
\c [Path\]exename.exe
Writes the uninstaller to the filename (and optionally path) specified. Only valid from within an install section or function, and requires that you have an uninstall section in your script. See also Uninstall configuration. You can call this one or more times to write out one or more copies of the uninstaller.
Writes the uninstaller to the filename (and optionally path) specified. Only valid from within an install section or function 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.
\c WriteUninstaller $INSTDIR\uninstaller.exe

12
Docs/src/usage.but
View file

@ -3,15 +3,15 @@
\H{usage} MakeNSIS Usage
NSIS installers are generated by using the 'MakeNSIS' program to compile a NSIS script (.NSI) into an installer executable.
The NSIS development kit installer sets up your computer so that you can compile a .nsi file by simply right-clicking on it in explorer, and selecting 'compile'.
The NSIS development kit installer sets up your computer so that you can compile a .nsi file by simply right-clicking on it in Explorer and selecting 'compile'.
If you want to use MakeNSIS on the command line, the syntax of the makensis command is:
If you want to use MakeNSIS on the command line, the syntax of makensis is:
\c makensis [ option | script.nsi | - ] [...]
\S1{usagereference} Options
\b /LICENSE displays a keen license page.
\b /LICENSE displays license information.
\b The /V switch followed by a number between 0 and 4 will set the verbosity of output accordingly. 0=no output, 1=errors only, 2=warnings and errors, 3=info, warnings, and errors, 4=all output.
@ -25,7 +25,7 @@ If you want to use MakeNSIS on the command line, the syntax of the makensis comm
\b /CMDHELP prints basic usage information for command (if specified), or all commands (if command is not specified).
\b /HDRINFO prints out information on what options were used to compile makensis was compiled with.
\b /HDRINFO prints information about which options were used to compile makensis.
\b /NOCD disables the current directory change to that of the .nsi file
@ -45,12 +45,10 @@ If you want to use MakeNSIS on the command line, the syntax of the makensis comm
\S1{usagenotes} Notes
\b Parameters are processed by order. \c{makensis /Ddef script.nsi} is not the same as \c{makensis script.nsi /Ddef}.
\b Parameters are processed in order. \c{makensis /Ddef script.nsi} is not the same as \c{makensis script.nsi /Ddef}.
\b If multiple scripts are specified, they are treated as one concatenated script.
\b On Windows 95, 98 and NT, below normal and above normal process priorities are not available. On those systems, below normal will actually set priority to idle and above normal will set to high.
\S1{usageenvironment} Environment variables
makensis checks a number of environment variables that tell it where to locate the things it needs in order to create installers. These variables include:

24
Docs/src/usefulfunc.but
View file

@ -5,15 +5,11 @@
\c ; GetIEVersion
\c ;
\c ; Based on Yazno's function, http://yazno.tripod.com/powerpimpit/
\c ; Returns on top of stack
\c ; 1-6 (Installed IE Version)
\c ; or
\c ; '' (IE is not installed)
\c ; Returns 1-6 (IE Version) or '' (IE is not installed) on top of the stack
\c ;
\c ; Usage:
\c ; Call GetIEVersion
\c ; Pop $R0
\c ; ; at this point $R0 is "5" or whatnot
\c ; Pop $R0 ; at this point $R0 is "5" or whatnot
\c
\c Function GetIEVersion
\c Push $R0
@ -59,7 +55,7 @@
\c ; Usage:
\c ; Call IsDotNETInstalled
\c ; Pop $0
\c ; StrCmp $0 1 found.NETFramework no.NETFramework
\c ; StrCmp $0 1 found_dotNETFramework no_dotNETFramework
\c
\c Function IsDotNETInstalled
\c Push $0
@ -79,15 +75,11 @@
\c ; IsFlashInstalled
\c ;
\c ; By Yazno, http://yazno.tripod.com/powerpimpit/
\c ; Returns on top of stack
\c ; 0 (Flash is not installed)
\c ; or
\c ; 1 (Flash is installed)
\c ; Returns the result on top of the stack
\c ;
\c ; Usage:
\c ; Call IsFlashInstalled
\c ; Pop $R0
\c ; ; $R0 at this point is "1" or "0"
\c ; Pop $R0 ; $R0 is "1" or "0" at this point
\c
\c Function IsFlashInstalled
\c Push $R0
@ -141,7 +133,7 @@
\H{installerfilename} Get Installer Filename
\c System::Call 'kernel32::GetModuleFileName(p 0, t .R0, i 1024) i r1'
\c System::Call 'kernel32::GetModuleFileName(p 0, t .R0, i ${NSIS_MAX_STRLEN}) i.r1'
\c ;$R0 will contain the installer filename
\H{multipleinstances} Prevent Multiple Instances
@ -155,8 +147,8 @@ Put the following code in your \R{oninit}{.onInit function}:
\c MessageBox MB_OK|MB_ICONEXCLAMATION "The installer is already running."
\c Abort
'myMutex' should be replaced by a unique value.
'myMutex' must be replaced by a unique value!
\H{morefuncs} More
You can find more useful scripts at \W{http://nsis.sourceforge.net/wiki/}{the NSIS Wiki}, \W{http://forums.winamp.com/forumdisplay.php?s=&forumid=65}{the NSIS forum} and \W{http://nsis.sourceforge.net/}{NSIS development page}.
You can find more useful scripts on \W{http://nsis.sourceforge.net/wiki/}{the NSIS Wiki}, \W{http://forums.winamp.com/forumdisplay.php?s=&forumid=65}{the NSIS forum} and the \W{http://nsis.sourceforge.net/}{NSIS development page}.

74
Docs/src/usefulinfos.but
View file

@ -14,27 +14,29 @@ As of NSIS 2.01, you can set the error level to other values using \R{seterrorle
Note that uninstallers copy themselves to the temporary directory and execute from there so the original uninstaller can be deleted. This means the error level the uninstaller sets is not available to the executing process, unless it simulates this copy process and executes the copied uninstaller. To simulate this process, use:
\c CopyFiles $INSTDIR\uninstaller.exe $TEMP
\c ExecWait '"$TEMP\uninstaller.exe" _?=$INSTDIR' $0
\c InitPluginsDir
\c CopyFiles $INSTDIR\uninstaller.exe $PLUGINSDIR
\c ExecWait '"$PLUGINSDIR\uninstaller.exe" _?=$INSTDIR' $0
\c DetailPrint "uninstaller set error level $0"
If you don't do this, you'll only be able to know if the uninstaller failed copying itself to the temporary directory.
\H{useful_add_uninst_infos}Add uninstall information to Add/Remove Programs
Create a key with your product name under \\<b\\>HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\</b\\> to add entries to the "Add/Remove Programs" section in the Control Panel.
Create a key with your product name under HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall to add entries to the "Add/Remove Programs" section in the Control Panel.
For Windows NT (NT4/2000/XP), it's also possible to create the key in the HKCU hive, so it will only appear for the current user.
There are several values you can write to key to give information about your application and the uninstaller.
Write a value using the \R{writeregstr}{WriteRegStr} command (for strings) or \R{writeregdword}{WriteRegDWORD} command (for DWORD values). Example:
Write a value using the \R{writeregstr}{WriteRegStr} command (for strings) or \R{writeregdword}{WriteRegDWORD} command (for DWORD values).
Example:
\c WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\Product" "DisplayName" "Application Name"
\c WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyProduct" "DisplayName" "Application Name"
\c WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyProduct" "UninstallString" '"$INSTDIR\uninst.exe"'
\\<b\\>Required values\\</b\\>
\e{DisplayName} (string) - Name of the application \\<br\\>
\e{UninstallString} (string) - Path and filename of the uninstaller. You should \\<b\\>always\\</b\\> quote the path to make sure spaces in the path will not disrupt Windows to find the uninstaller.
\e{UninstallString} (string) - Path and filename of the uninstaller. You should \\<b\\>always\\</b\\> quote the path.
\\<b\\>Optional values\\</b\\>
@ -70,10 +72,10 @@ If both NoModify and NoRepair are set to 1, the button displays "Remove" instead
\H{useful_system_plugin} Calling an external DLL using the System.dll plug-in
Some install processes are required to call functions contained inside third party DLLs. A prime example of this is when installing a Palm(TM) conduit.
Some installers need to call functions in third-party DLLs. A prime example of this is when installing a Palm(TM) conduit.
\\<b\\>Some background about System.dll\\</b\\> \\<br\\>
The System.dll plug-in (by Brainsucker) enables calling of external DLLs by providing the '\R{call}{Call}' function. There are a number of other functions provided by System.dll, but they will not be covered here. For more details about the other functions, lock the doors, take the phone off the hook, screw your head on *real* tight and head on over to the \L{../Docs/System/System.html}{System readme}.
The System.dll plug-in enables calling of external DLLs by using its 'Call' function. There are a number of other functions provided by System.dll but they will not be covered here. For more details about the other functions, lock the doors, take the phone off the hook, screw your head on *real* tight and head on over to the \L{../Docs/System/System.html}{System readme}.
\\<u\\>Data Types\\</u\\> \\<br\\>
System.dll recognises the following data types:
@ -84,7 +86,7 @@ System.dll recognises the following data types:
\b i - int (a 32bit integer)
\b l - long & large integer (also known as int64)
\b l - large integer (also known as int64)
\b t - text, string (LPTSTR, pointer to first character)
@ -97,16 +99,16 @@ System.dll recognises the following data types:
\\<u\\>Mapping System.dll variables to NSIS script variables\\</u\\> \\<br\\>
There's not much point in being able to call an external function if you can't get any data back. System.dll maps function variables to NSIS script variables in the following way:
NSIS $0..$9 become System.dll r0..r9
NSIS $R0..$R9 become System.dll r10..r19
NSIS $0..$9 becomes System.dll r0..r9
NSIS $R0..$R9 becomes System.dll r10..r19
Each parameter is specified by type, input and output. To skip input or output use a dot. Examples:
String (pointer to a characters array), input is 'happy calling':
String (pointer to a character array), input is 'happy calling':
\c t 'happy calling'
String (pointer to a characters array), input is taken from $5 and changes to the array made by the call are saved into $R8:
String (pointer to a character array), input is taken from $5 and changes to the array made by the callee are saved into $R8:
\c t r5R8
@ -119,19 +121,19 @@ Pointer to a 64-bit integer, output pushed on stack, no input:
\c *l .s
Using System.dll::Call
To call a function in a third party DLL, the \R{call}{Call} function is used like this:
To call a function in a third party DLL, the Call function is used like this:
\c System::Call 'YourDllName::YourDllFunction(i, *i, t) i(r0, .r1, r2) .r3'
The '(r0, .r1, r2) .r3' section at the end are the parameters that are passed between your DLL and your NSIS script. As can be seen in this parameters list type and input/output can be separated. Each block of "(parms list) return value" overrides and/or adds to the last one. In this case, the first block specifies the types and the second specifies input and output.
The '(r0, .r1, r2) .r3' section at the end are the parameters that are passed between your DLL and your NSIS script. As can be seen in this parameters list, type and input/output can be separated. Each block of "(parms list) return value" overrides and/or adds to the last one. In this case, the first block specifies the types and the second specifies input and output.
\\<b\\>Before starting to code the NSIS script\\</b\\> \\<br\\>
Before you start to code any NSIS code, you need to know the full prototype of the function you are going to call. For the purposes of this example, we will use the 'CmGetHotSyncExecPath' function from the Palm 'CondMgr.dll'. This function is used to return the full path of 'HotSync.exe'.
Before you start to code any NSIS code you need to know the full prototype of the function you are going to call. For the purposes of this example, we will use the 'CmGetHotSyncExecPath' function from the Palm 'CondMgr.dll'. This function is used to return the full path of 'HotSync.exe'.
\\<u\\>Function Definition\\</u\\> \\<br\\>
int CmGetHotSyncExecPath(TCHAR *pPath, int *piSize);
int __stdcall CmGetHotSyncExecPath(TCHAR *pPath, int *piSize);
where
@ -161,9 +163,9 @@ CmGetHotSyncExecPath(t, *i) i
i.e. It takes a text variable, a pointer to int, and returns an int value.
\\<u\\>Using the external dll function\\</u\\> \\<br\\>
Now that we've sorted out what the function does, and how it maps to the System.dll format, we can use the function in a NSIS script.
Now that we've sorted out what the function does and how it maps to the System.dll format we can use the function in a NSIS script.
First, you have to change the output directory to that where the DLL you want to use is. It may also work if the DLL is on the system path, but this hasn't been tested.
First you have to change the output directory to that where the DLL you want to use is. It may also work if the DLL is in the system path but this hasn't been tested.
The following code fragment will install 'condmgr.dll' to a temporary directory, execute the CmGetHotSyncExecPath function and display returned data.
Save this script
@ -200,7 +202,7 @@ Good Luck!
\H{dumplogtofile} Dump Content of Log Window to File
This function will dump the log of the installer (installer details) to a file of your choice. I created this function for Afrow_UK who requested a way to dump the log to a file in \W{http://forums.winamp.com/showthread.php?s=&threadid=125431}{this forum thread}.
This function will dump the log of the installer (installer details) to a file of your choice.
To use it, push a file name and call it. It will dump the log to the file specified. For example:
@ -214,9 +216,9 @@ Here is the function:
\c !define LVM_GETITEMCOUNT 0x1004
\c !define LVM_GETITEMTEXT 0x102D
\c !define LVM_GETITEMTEXTA 0x102D
\c
\c Function DumpLog
\c Function DumpLog # Written by KiCHiK
\c Exch $5
\c Push $0
\c Push $1
@ -237,8 +239,8 @@ Here is the function:
\c System::Call "*(i, i, i, i, i, i, i, i, i) p \
\c (0, 0, 0, 0, 0, r3, ${NSIS_MAX_STRLEN}) .r1"
\c loop: StrCmp $2 $6 done
\c System::Call "User32::SendMessage(p, i, p, p) i \
\c ($0, ${LVM_GETITEMTEXT}, $2, r1)"
\c System::Call "User32::SendMessageA(p, i, p, p) i \
\c ($0, ${LVM_GETITEMTEXTA}, $2, r1)"
\c System::Call "*$3(&t${NSIS_MAX_STRLEN} .r4)"
\c FileWrite $5 "$4$\r$\n"
\c IntOp $2 $2 + 1
@ -260,14 +262,12 @@ Here is the function:
\c Exch $5
\c FunctionEnd
written by KiCHiK
Here's the function to generate a Unicode file if you're building a \R{intro-unicode}{Unicode installer}.
Here's the function to generate a UTF-16LE file if you're building a \R{intro-unicode}{Unicode installer}.
\c !define LVM_GETITEMCOUNT 0x1004
\c !define LVM_GETITEMTEXT 0x1073
\c !define LVM_GETITEMTEXTW 0x1073
\c
\c Function DumpLog
\c Function DumpLog # Written by KiCHiK, modified by Jim Park
\c Exch $5
\c Push $0
\c Push $1
@ -290,7 +290,7 @@ Here's the function to generate a Unicode file if you're building a \R{intro-uni
\c (0, 0, 0, 0, 0, r3, ${NSIS_MAX_STRLEN}) .r1"
\c loop: StrCmp $2 $6 done
\c System::Call "User32::SendMessageW(p, i, p, p) i \
\c ($0, ${LVM_GETITEMTEXT}, $2, r1)"
\c ($0, ${LVM_GETITEMTEXTW}, $2, r1)"
\c System::Call "*$3(&t${NSIS_MAX_STRLEN} .r4)"
\c FileWriteUTF16LE $5 "$4$\r$\n"
\c IntOp $2 $2 + 1
@ -312,17 +312,13 @@ Here's the function to generate a Unicode file if you're building a \R{intro-uni
\c Exch $5
\c FunctionEnd
Modified by Jim Park.
\H{readreg_multi_sz} How to Read REG_MULTI_SZ Values
I wrote this script to help rpetges in \W{http://forums.winamp.com/showthread.php?s=&threadid=131154}{this forum thread}. It reads a registry value of the type REG_MULTI_SZ and prints it out. Don't forget to edit where it says "Edit this!" when you test this script. The values must point to a REG_MULTI_SZ value or the example will spit out an error.
KiCHiK wrote this script to help rpetges in \W{http://forums.winamp.com/showthread.php?s=&threadid=131154}{this forum thread}. It reads a registry value of the type REG_MULTI_SZ and prints it out. Don't forget to edit where it says "Edit this!" when you test this script. The values must point to a REG_MULTI_SZ value or the example will spit out an error.
\c OutFile "REG_MULTI_SZ Reader.exe"
\c
\c Name "REG_MULTI_SZ Reader"
\c
\c ShowInstDetails show
\c
\c !define HKEY_CLASSES_ROOT 0x80000000
@ -334,10 +330,8 @@ I wrote this script to help rpetges in \W{http://forums.winamp.com/showthread.ph
\c !define HKEY_PERFORMANCE_NLSTEXT 0x80000060
\c !define HKEY_CURRENT_CONFIG 0x80000005
\c !define HKEY_DYN_DATA 0x80000006
\c
\c !define KEY_QUERY_VALUE 0x0001
\c !define KEY_ENUMERATE_SUB_KEYS 0x0008
\c
\c !define REG_NONE 0
\c !define REG_SZ 1
\c !define REG_EXPAND_SZ 2
@ -433,8 +427,6 @@ I wrote this script to help rpetges in \W{http://forums.winamp.com/showthread.ph
\c
\c SectionEnd
written by KiCHiK
\H{unicode_defines}Predefined Macros for Unicode support
There are two macros that can help you write scripts that work for both Unicode and ANSI installers. To figure out if the script is being compiled to generate a Unicode installer, use !ifdef check for $\{NSIS_UNICODE\}. To see what the size of the default character is, use $\{NSIS_CHAR_SIZE\}. It will be 1 for ANSI and 2 for Unicode installers.
There are two macros that can help you write scripts that work for both Unicode and ANSI installers. To figure out if the script is being compiled to generate a Unicode installer, use !ifdef to check for $\{NSIS_UNICODE\}. To see what the size of a character is, use $\{NSIS_CHAR_SIZE\}. It will be 1 for ANSI and 2 for Unicode installers.

38
Docs/src/var.but
View file

@ -1,12 +1,12 @@
\H{variables} Variables
All variables are global and can be used in Sections or Functions. Note that, by default, variables are limited to 1024 characters. To extend this limit, \R{build}{build NSIS} with a bigger value of the NSIS_MAX_STRLEN build setting or use the \W{http://nsis.sourceforge.net/download/specialbuilds/}{special build}.
All variables are global and can be used in Sections or Functions. Note that by default, variables are limited to 1024 characters. To extend this limit, \R{build}{build NSIS} with a bigger value of the NSIS_MAX_STRLEN build setting or use the \W{http://nsis.sourceforge.net/download/specialbuilds/}{special build}.
\S1{varuser} User Variables
\e{$VARNAME}
User variables can be declared with the \R{var}{Var} command. You can use these variables to store values, work with string manipulation etc.
User variables must be declared with the \R{var}{Var} command. You can use these variables to store values, work with string manipulation etc.
\S2{var} Var
@ -27,7 +27,7 @@ Declare a user variable. Allowed characters for variables names: [a-z][A-Z][0-9]
\e{$0, $1, $2, $3, $4, $5, $6, $7, $8, $9, $R0, $R1, $R2, $R3, $R4, $R5, $R6, $R7, $R8, $R9}
Registers. These variables can be used just like user variables, but are usually used in shared functions or macros. You don't have to declare these variables, so you won't get any name conflicts when using them in shared code. When using these variables in shared code, it's recommended that you use the stack to save and restore their original values. These variables can also be used for communication with plug-ins, because they can be read and written by the plug-in DLLs.
Registers. These variables can be used just like user variables, but are usually used in shared functions or macros. You don't have to declare these variables so you won't get any name conflicts when using them in shared code. When using these variables in shared code it's recommended that you use the stack to save and restore their original values. These variables can also be used for communication with plug-ins because they can be read and written by the plug-in DLLs.
\e{$INSTDIR}
@ -51,7 +51,7 @@ The command line of the installer. The format of the command line can be one of
\e{$LANGUAGE}
The identifier of the language that is currently used. For example, English is 1033. You can change this variable in \R{oninit}{.onInit}.
The identifier of the language that is currently used. For example, English is 1033. You can only change this variable in \R{oninit}{.onInit}.
\S1{varconstant} Constants
@ -69,11 +69,11 @@ The common files directory. This is a directory for components that are shared a
\e{$DESKTOP}
The Windows desktop directory (usually \c{C:\\Windows\\Desktop} but detected at runtime). The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
The Windows desktop directory. The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
\e{$EXEDIR}
The directory containing the installer executable (technically you can modify this variable, but it is probably not a good idea).
The directory containing the installer executable (technically this is a variable and you can modify it, but it is probably not a good idea).
\e{$EXEFILE}
@ -85,7 +85,7 @@ The full path of the installer executable.
\e{$\{NSISDIR\}}
A symbol that contains the path where NSIS is installed. Useful if you want to call resources that are in NSIS directory e.g. Icons, UIs etc.
A symbol that contains the path where NSIS is installed. Useful if you want to reference resources that are in NSIS directory e.g. Icons, UIs etc.
When compiled with support for keeping makensis and the data in the same place (the default on Windows), it is in the same place as makensis, on other platforms it is set at compile time (See the INSTALL file for info). In both instances you can modify it at runtime by setting the NSISDIR environment variable. See \k{usageenvironment} for more info.
@ -99,11 +99,11 @@ The Windows system directory (usually \c{C:\\Windows\\System} or \c{C:\\WinNT\\S
\e{$TEMP}
The system temporary directory (usually \c{C:\\Windows\\Temp} but detected at runtime).
The temporary directory.
\e{$STARTMENU}
The start menu folder (useful in adding start menu items using \R{createshortcut}{CreateShortcut}). The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
The start menu folder (useful for adding start menu items using \R{createshortcut}{CreateShortcut}). The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
\e{$SMPROGRAMS}
@ -115,13 +115,13 @@ The start menu programs / startup folder. The context of this constant (All User
\e{$QUICKLAUNCH}
The quick launch folder for IE4 active desktop and above. If quick launch is not available, simply returns the same as $TEMP.
The quick launch folder for IE4 active desktop and above. If quick launch is not available it simply returns the same as $TEMP.
\e{$DOCUMENTS}
The documents directory. A typical path for the current user is \c{C:\\Documents and Settings\\Foo\\My Documents}. The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
This constant is not available on Windows 95 with Internet Explorer 4 not installed.
This constant is not available on Windows 95 unless Internet Explorer 4 is installed.
\e{$SENDTO}
@ -135,7 +135,7 @@ The directory that contains shortcuts to the user's recently used documents.
The directory that contains shortcuts to the user's favorite websites, documents, etc. The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
This constant is not available on Windows 95 with Internet Explorer 4 not installed.
This constant is not available on Windows 95 unless Internet Explorer 4 is installed.
\e{$MUSIC}
@ -159,7 +159,7 @@ This constant is available on Windows XP, ME and above.
The directory that contains link objects that may exist in the My Network Places/Network Neighborhood folder.
This constant is not available on Windows 95 with Internet Explorer 4 and Active Desktop not installed.
This constant is not available on Windows 95 unless Internet Explorer 4 with Active Desktop is installed.
\e{$FONTS}
@ -173,7 +173,7 @@ The document templates directory. The context of this constant (All Users or Cur
The application data directory. Detection of the current user path requires Internet Explorer 4 and above. Detection of the all users path requires Internet Explorer 5 and above. The context of this constant (All Users or Current user) depends on the \R{setshellvarcontext}{SetShellVarContext} setting. The default is the current user.
This constant is not available on Windows 95 with Internet Explorer 4 and Active Desktop not installed.
This constant is not available on Windows 95 unless Internet Explorer 4 with Active Desktop is installed.
\e{$LOCALAPPDATA}
@ -191,19 +191,19 @@ This constant is not available on Windows 95 and Windows 98.
Internet Explorer's temporary internet files directory.
This constant is not available on Windows 95 and Windows NT with Internet Explorer 4 and Active Desktop not installed.
This constant is not available on Windows 95 nor Windows NT 4 unless Internet Explorer 4 with Active Desktop is installed.
\e{$COOKIES}
Internet Explorer's cookies directory.
This constant is not available on Windows 95 and Windows NT with Internet Explorer 4 and Active Desktop not installed.
This constant is not available on Windows 95 nor Windows NT 4 unless Internet Explorer 4 with Active Desktop is installed.
\e{$HISTORY}
Internet Explorer's history directory.
This constant is not available on Windows 95 and Windows NT with Internet Explorer 4 and Active Desktop not installed.
This constant is not available on Windows 95 nor Windows NT 4 unless Internet Explorer 4 with Active Desktop is installed.
\e{$PROFILE}
@ -219,13 +219,13 @@ This constant is available on Windows 2000, ME and above.
\e{$RESOURCES}
The resources directory that stores themes and other Windows resources (usually \c{C:\\Windows\\Resources} but detected at runtime).
The resources directory that stores themes and other Windows resources (usually \c{$WINDIR\\Resources} but detected at runtime).
This constant is available on Windows XP and above.
\e{$RESOURCES_LOCALIZED}
The localized resources directory that stores themes and other Windows resources (usually \c{C:\\Windows\\Resources\\1033} but detected at runtime).
The localized resources directory that stores themes and other Windows resources (usually \c{$WINDIR\\Resources\\1033} but detected at runtime).
This constant is available on Windows XP and above.

8
Source/tokens.cpp
View file

@ -74,7 +74,7 @@ static tokenType tokenlist[TOK__LAST] =
{TOK_GETINSTDIRERROR,_T("GetInstDirError"),1,0,_T("$(user_var: error output)"),TP_CODE},
{TOK_ROOTDIRINST,_T("AllowRootDirInstall"),1,0,_T("(true|false)"),TP_GLOBAL},
{TOK_CHECKBITMAP,_T("CheckBitmap"),1,0,_T("local_bitmap.bmp"),TP_GLOBAL},
{TOK_ENABLEWINDOW,_T("EnableWindow"),2,0,_T("hwnd (1|0)"),TP_CODE},
{TOK_ENABLEWINDOW,_T("EnableWindow"),2,0,_T("hwnd state(1|0)"),TP_CODE},
{TOK_ENUMREGKEY,_T("EnumRegKey"),4,0,_T("$(user_var: output) rootkey subkey index\n root_key=(HKCR|HKLM|HKCU|HKU|HKCC|HKDD|HKPD|SHCTX)"),TP_CODE},
{TOK_ENUMREGVAL,_T("EnumRegValue"),4,0,_T("$(user_var: output) rootkey subkey index\n root_key=(HKCR|HKLM|HKCU|HKU|HKCC|HKDD|HKPD|SHCTX)"),TP_CODE},
{TOK_EXCH,_T("Exch"),0,1,_T("[$(user_var)] | [stack_item_index]"),TP_CODE},
@ -127,11 +127,11 @@ static tokenType tokenlist[TOK__LAST] =
{TOK_INTFMT,_T("IntFmt"),3,0,_T("$(user_var: output) format_string input"),TP_CODE},
{TOK_ISWINDOW,_T("IsWindow"),2,1,_T("hwnd jump_if_window [jump_if_not_window]"),TP_CODE},
{TOK_GOTO,_T("Goto"),1,0,_T("label"),TP_CODE},
{TOK_LANGSTRING,_T("LangString"),3,0,_T("[un.]name lang_id string"),TP_GLOBAL},
{TOK_LANGSTRING,_T("LangString"),3,0,_T("[un.]name lang_id|0 string"),TP_GLOBAL},
{TOK_LANGSTRINGUP,_T("LangStringUP"),0,0,_T("obsolete, use LangString."),TP_ALL},
{TOK_LICENSEDATA,_T("LicenseData"),1,0,_T("local_file_that_has_license_text | license_lang_string"),TP_PG},
{TOK_LICENSEFORCESELECTION,_T("LicenseForceSelection"),1,2,_T("(checkbox [accept_text] | radiobuttons [accept_text] [decline_text] | off)"),TP_PG},
{TOK_LICENSELANGSTRING,_T("LicenseLangString"),3,0,_T("name lang_id license_path"),TP_GLOBAL},
{TOK_LICENSELANGSTRING,_T("LicenseLangString"),3,0,_T("name lang_id|0 license_path"),TP_GLOBAL},
{TOK_LICENSETEXT,_T("LicenseText"),1,1,_T("license_page_description [license_button_text]"),TP_PG},
{TOK_LICENSEBKCOLOR,_T("LicenseBkColor"),1,0,_T("background_color"),TP_GLOBAL},
{TOK_LOADNLF,_T("LoadLanguageFile"),1,0,_T("language.nlf"),TP_GLOBAL},
@ -300,7 +300,7 @@ static tokenType tokenlist[TOK__LAST] =
// Added by ramon 3 jun 2003
{TOK_DEFVAR,_T("Var"),1,1,_T("[/GLOBAL] var_name"),TP_ALL},
// Added by ramon 6 jun 2003
{TOK_VI_ADDKEY,_T("VIAddVersionKey"),2,1,_T("/LANG=lang_id keyname value"),TP_GLOBAL},
{TOK_VI_ADDKEY,_T("VIAddVersionKey"),2,1,_T("[/LANG=lang_id] keyname value"),TP_GLOBAL},
{TOK_VI_SETPRODUCTVERSION,_T("VIProductVersion"),1,0,_T("[version_string_X.X.X.X]"),TP_GLOBAL},
{TOK_VI_SETFILEVERSION,_T("VIFileVersion"),1,0,_T("[version_string_X.X.X.X]"),TP_GLOBAL},
{TOK_LOCKWINDOW,_T("LockWindow"),1,0,_T("(on|off)"),TP_CODE},

4
TODO.txt
View file

@ -3,8 +3,6 @@ TODO
NSIS
* Make Unicode version compile on other compilers / platforms.
* Compiler plug-ins
* Empty subsections should not show
@ -18,7 +16,7 @@ EXAMPLES
PLUG-INS
* InstallOptions - custom class names so you can include whatever control
* InstallOptions - custom class names so you can include any control
you want
* nsExec - live outputs