NfUtils header file

Links

Go to Forum thread

Download current version:
Version 1.2.0.0 (07-11-2006): nfUtils12.zip

Download older versions:
Version 1.1.0.0 (06-30-2006): nfUtils11.zip
Version 1.0.0.0 (06-03-2006): nfUtils.zip

Description

nfUtils is a collection of macros and functions in a NSIS header file, intended to ease the development and usage of new functions and macros for your own header files.

How to use

Download the zipped installer for the current version of nfUtils, unzip and start the installer nfUtils.exe. The installer will add the following files to your NSIS installation:

nfUtils.nsh (the header file)
nfUtils.nsi (the installer script)
nfUtils.exe (the installer)
nfgetver.exe (utility used by nfUtils.nsh)

Basically you will only need nfUtils.nsh in the include directory of your NSIS installation: nfgetver.exe will be generated by nfUtils.nsh, when nfgetver is needed and unavailable. The installer's script is provided for learning purposes, because it will show the usage of some macros and functions.

To use the header, place this at the beginning of your script:

!include "nfUtils.nsh"

First steps

Descriptions for nfUtils' macros and functions can be obtained by adding the instruction

{$nfu.!Help} ?

to your script. This help is implemented by using symbols (NSIS' gflags) for the descriptive text. Because there is a limitation of 64kB per symbolvalue, nfUtils groups its help into sections, which are identified by prefixes. Currently there are two groups with the prefix "" (none) and "nfu." (for nfUtils' macros and functions). Thus, the instruction

{$nfu.!Help} nfu.

will give you an index of all descriptions, which have been installed with the prefix "nfu.", by using one of the macros ${nfu.!InstallMacro}, ${nfu.!InstallFunction} or ${nfu.!InstallDescription}. Finally, the instruction

{$nfu.!Help} "nfu.!InstallMacro"

will output the description, which has been provided for the macro "!InstallMacro" (prefixed by "nfu."). It goes without saying that you may (and should) use this little helpsystem for your own macros and functions (avoid using the prefix "nfu." for your code or you could loose compatibility with future versions of nfUtils). But ${nfu.!Help} is only a by-product of the more important macros ${nfu.!InstallFunction} and ${nfu.!InstallMacro}. In the following you will find the descriptions of all macros and functions provided by the current release of nfUtils.

Documentation

nfUtils needs at least NSIS Version 2.15, the following instructions can be compiled only on a Windows type operating system (not on Linux, FreeBSD, Solaris, etc.):
${nfu.!FileVersion}
${nfu.!Help}
${nfu.!IncludeTextIfExist}
${nfu.SetInstallerName}
${nfu.SetStdAttributes}
${nfu.SetVersionInfo}

nfu.!AddFile

Usage: ${nfu.!AddFile} FileOptions OutFolder

Description: You will need this macro only when using ${nfu.ProcessStdSwitches}. It will record the FileOptions with a prepended FILE-instruction for later insertion into the hidden section, which will be created by adding ProcessStdSwitches to the script via ${nfu.!AddFunction}.
Using !AddFile after "${nfu.!AddFunction} nfu.ProcessStdSwitches", will be ignored.
The parameter Outfolder will instruct ProcessStdSwitches to extract the file(s) to the specified subfolder within the destination folder the user has selected. When using '/ICON' as FileOptions, !AddFile will prepare the inclusion of the icon, which will be set by SetInstallerName or SetStdAttributes. '/ICON' will use the default outfolder "" (this is the root of the installer archive) when you specify "" for the parameter Outfolder. Non-empty values will change the default. Be sure to use only paths without a drive letter to keep the resources relative to the root.

nfu.!AddFunction

Usage: ${nfu.!AddFunction} FunctionName

Description: Adds the code for the function FunctionName to the script. The function must have been installed with the supportmacro "InstallFunction". See nfu.!InstallFunction for further information.

nfu.!Append

Usage: ${nfu.!Append} SymbolName Value

Description: Appends Value to SymbolName's value. SymbolName does not need to be defined.

nfu.!AppendIf

Usage: ${nfu.!AppendIf} Condition SymbolName Value

Description: Appends Value to SymbolName's value if !ifCondition is met. SymbolName does not need to be defined.

nfu.!Calculate

Usage: ${nfu.!Calculate} SymbolName Op Value

Description: SymbolName := SymbolName Op Value, where Op may be +,-,*,/ or %. SymbolName and Value must represent integers. SymbolName does not need to be defined - it will be initialized to 0, if undefined.

nfu.!Compare

Usage: ${nfu.!Compare} ResultSymbol Value1 Value2

Description: This macro will do a case-insensitive string comparison of Value1 and Value2 and sets ResultSymbol to "1" on equality. The symbol does not need to be defined.
Note: This macro is obsolete since NSIS 2.19, because !if will do the same.

nfu.!Exchange

Usage: ${nfu.!Exchange} SymbolName1 SymbolName2

Description: Exchanges the values of both symbols. None of the symbols need to be defined.

nfu.!FileVersion

Usage: ${nfu.!FileVersion} SymbolName Filename

Description: Redefines the symbol SymbolName with the fileversion of FileName. SymbolName does not need to be defined. If the file does not exist or has no version information, then the symbol's value will be empty.
Note: This instruction has limitations.

nfu.!FreeFile

Usage: ${nfu.!FreeFile}

Description: Deletes the last temporary file created by ${nfu.!MakeFile}.

nfu.!FreeSymbol

Usage: ${nfu.!FreeSymbol}

Description: !undefines the last symbol created by ${nfu.!MakeSymbol}.

nfu.Function

Usage: ${nfu.Function} FunctionName io1 v1 io2 v2 io3 v3 io4 v4 io5 v5 io6 v6 io7 v7 io8 v8 io9 v9 io10 v10

Description: This macro will add "Function FunctionName" to your script, followed by the code to load parameters from the stack into the variables v* (usually $0-$9, $R0-$R9, but $VARs should also work) you have specified in the parameterlist of the macro. io* must be specified with in or out, depending on which variable you need to hold an input parameter on entry of the function or which one is planned to hold a result value on the end of the function. Leave unused pairs of (io/v) empty ("" "").
The macro expects that the first input parameter (the leftmost Vn with IOn=in) has been pushed first onto the stack before the functioncall, and will prepare the results, so that the first output parameter has to be the first one, which has to be popped off the stack after return from the function: this order will be established by ${nfu.!InstallFunction} to prepare the call of a function. See also ${nfu.FunctionEnd}.
Note: Beginning with NSIS 2.19, the keywords in and out no longer need to be lowercase.

nfu.FunctionEnd

Usage: ${nfu.FunctionEnd}

Description: Inserts the code prepared by ${nfu.Function} to put the results onto the stack and to recover the values of the variables, which have been used in the parameterlist of ${nfu.Function}. The macro closes your functionbody with the keyword FunctionEnd.

nfu.!Help

Usage: ${nfu.!Help} Item

Description: Shows usage and description for items, which have been registered with ${nfu.!InstallMacro}, ${nfu.!InstallFunction} or ${nfu.!InstallDescription}. Item is either the Prefix or the concatenation of Prefix and the MacroName, FunctionName or Item, you have used with one of these instructions. ${nfu.!Help} ? will show an index of all registered prefixes, to get help for nonprefixed items, use ${nfu.!Help} "". ${nfu.!Help} will stop the compilation of the script.
Note: This instruction has limitations.

nfu.HideBackButton

Usage: ${nfu.HideBackButton}

Description: Hides the Back-Button, when used in the Show-Callback of an installer page.

nfu.HideCancelButton

Usage: ${nfu.HideCancelButton}

Description: Hides the Cancel-Button, when used in the Show-Callback of an installer page.

nfu.!IncludeFileIf

Usage: ${nfu.!IncludeFileIf} Condition IncludeFileName

Description: !IncludeFileIf will !include the specified file, if !ifCondition is met. Useful if want to make sure that you dont include a file, which is already included by another headerfile.

nfu.!IncludeTextIfExist

Usage: ${nfu.!IncludeTextIfExist} FileName IncludeText

Description: !IncludeTextIfExist will write IncludeText to a temporary includefile, which will be included to your script if FileName exists at compile-time. Multiline instructions are supported.
Note: This instruction has limitations.

nfu.!InstallDescription

Usage: ${nfu.!InstallDescription} Prefix Item Usage Description

Description: Adds PrefixItem to NFU's helpsystem. You may query Usage and Description by adding ${nfu.!Help} PrefixItem to your script.

nfu.!InstallFunction

Usage: ${nfu.!InstallFunction} Prefix FunctionName io1 p1 io2 p2 io3 p3 io4 p4 io5 p5 io6 p6 io7 p7 io8 p8 io9 p9 io10 p10 Description

Description: InstallFunction dynamically defines a macro, which contains the calling-code for a function, which you have included in a macro definition like "!macro PrefixFunctionName Un1 Un2", followed by "Function ${Un2}PrefixFunctionName", where Prefix and FunctionName may be substituted by anything you like, as long as this forms a valid identifier for macros and functions.
You may leave Prefix empty ("") - this parameter is provided only to avoid naming conflicts with other headerfiles, which introduce functions with the same name, you want to use for your code. The built-in help of nfUtils will also use Prefix to group the descriptions of macros and functions.
The macro parameters 'Un1' and 'Un2' will be passed as "" and "" or "Un" and "un.", when you ${nfu.!AddFunction} PrefixFunctionName or PrefixUnFunctionName.
The function may have up to 10 parameters, depending on the information you have provided with io1-io10 and p1-p10. io* are constants in or out, so that InstallFunction knows that it has to push parameter p* on the stack prior to the call, or p* has to be popped off the stack after the call. If the function needs less than 10 parameters, you have to pass "" for the unused pairs of parameters (io*,p*).
It does not matter, whether you specify in- before out-parameters, out- before in-parameters or even mix them up, only the sequence within the in-parameters and within the out-parameters must fit to your function.
The parameterlist io* and p* is also used to generate the usage information for the function. You may use any name for p*, but the names must be unique, at least within the group of in- and out-parameters - you will get a macro definition error if you dont follow this rule: you may specify 'out' 'Parameter' 'in' 'Parameter' for (io1,p1), (io2,p2), but not 'in' 'Parameter' 'in' 'Parameter'. The resulting usage information will be

Usage: ${PrefixFunctionName} out:Parameter in:Parameter

so please use names, which contribute a little more to the meaning of a parameter than this poor example.
The parameter Description will be displayed in the integrated helpsystem. You may use "", if you dont want to give a description.
InstallFunction will also generate two symbols, so that you may insert the macro with the calling-code by adding ${PrefixFunctionName} or ${PrefixUnFunctionName} to your script, followed by the correct number of parameters, according to the usage information of the function.
Before you may use these symbols, you have to add the function's code outside of any section or function by adding '${nfu.!AddFunction} PrefixFunctionName' to your script. Use '${nfu.!AddFunction} PrefixUnFunctionName', if you want to include the function in an uninstaller.
Note: Beginning with NSIS 2.19, the keywords in and out no longer need to be lowercase.

nfu.!InstallMacro

Usage: ${nfu.!InstallMacro} Prefix MacroName ParamList Description

Description: !defines a symbol PrefixMacroName with "!insertmacro PrefixMacroName" and registers the symbol in NFU's helpsystem with the given Description and usage information according to ParamList.

nfu.!MakeFile

Usage: ${nfu.!MakeFile}

Description: Inserts the instruction !tempfile and defines a temporary symbol to hold the filename of the temporary file. Use "${nfu.TempFile}" to access the name of the symbol, and "${${nfu.TempFile}}" to get the filename. Never !undefine symbols created by this macro, use ${nfu.!FreeFile} to delete the file and undefine the symbol.

nfu.!MakeSymbol

Usage: ${nfu.!MakeSymbol} Value

Description: Defines a temporary symbol. Use "${nfu.TempSymbol}" to access its name, and "${${nfu.TempSymbol}}" to get its value. Never !undefine symbols created by this macro, use ${nfu.!FreeSymbol} instead.

nfu.!Redefine

Usage: ${nfu.!Redefine} SymbolName Value

Description: Redefines SymbolName with the new Value. SymbolName does not need to be defined.

nfu.!Replace

Usage: ${nfu.!Replace} DstSymbolName SrcString SearchFor ReplaceWith

Description: This macro will define the symbol SearchFor with the value ReplaceWith, so that every occurence of ${SearchFor} in SrcString will be replaced with ReplaceWith.
The result will be assigned to the symbol DstSymbolName. If you leave this parameter empty, then the result will be added to your script. If you specify "nfu.TempSymbol" for this parameter, the result will be assigned to the last temporary symbol you have generated with ${nfu.!MakeSymbol}.
You may inhibit or defer the evaluation of symbols with this macro. Compare the results of the following instructions:

!echo '--- ${nfu.Help} ---'
${nfu.!Replace} "" "!echo '--- ${?}{nfu.Help} ---'" "?" "$"

nfu.SetInstallerName

Usage: ${nfu.SetInstallerName} InstallerName

Description: Sets the installer attributes Name, Caption, Outfile and Icon to InstallerName, InstallerName, InstallerName.exe and InstallerName.ico. The macro checks the availibility of InstallerName.ico and sets Icon to Icon.ico, if it does not exist. No Icon will be set, if none of the icons exist. The macro also (re)defines the symbol nfu.myName, which will be set to InstallerName for later use in your code.
Note: This instruction has limitations.

nfu.SetStdAttributes

Usage: ${nfu.SetStdAttributes} InstallerName Version Company Copyright Comments

Description: Invokes ${nfu.SetInstallerName} and ${nfu.SetVersionInfo}.
Note: This instruction has limitations.

nfu.SetVersionInfo

Usage: ${nfu.SetVersionInfo} InstallerName Version Company Copyright Comments

Description: Sets the installer attributes for the installer's version information. InstallerName will be set for the ProductName, FileDescription, InternalName and OriginalFileName. Version will be used for the ProductVersion and FileVersion, and may be the name of a file, whose version will be detected at compile-time, so that the installer could get the same version like the executable you want to distribute. The macro also (re)defines the symbol nfu.myVersion, which will be set to Version for later use in your code.
Note: This instruction has limitations.

nfu.SkipPageOnSrcExtract

Usage: ${nfu.SkipPageOnSrcExtract}

Description: You will need this only, if you wish to use 'nfu.ProcessStdSwitches' and you have defined one or more installerpages before adding ProcessStdSwitches with AddFunction. If you insert this macro as the first instruction in the creator- or pre-function of a page, it will skip the page by an Abort, if the /e- or /x-switch has been specified with a non-silent option in the commandline.

nfu.SkipSectionOnSrcExtract

Usage: ${nfu.SkipSectionOnSrcExtract}

Description: You will need this only, if you wish to use 'nfu.ProcessStdSwitches'. If you insert this macro as the first instruction of a section, the section will be skipped by a Return, if the /e- or /x-switch has been specified with a non-silent option in the commandline. It is usually not intended to run the regular installer sections, when the user only wants to extract the projectfiles of the installer! You may also use SkipSectionOnSrcExtract in functions.

nfu.!Undefine

Usage: ${nfu.!Undefine} SymbolName

Description: Undefines SymbolName. SymbolName does not need to be defined.

nfu.GetAppPath

Usage: ${nfu.GetAppPath} out:AppPath in:AppName

Description: Returns the fullpath of an application, which is registered under "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths". If AppName (e.g. 'iexplore.exe') is not registered or the executable does not exist, then "" will be returned. This also works for applications, which use REG_EXPAND_SZ keys for its registration. The status of the errorflag will be preserved.

nfu.UnGetAppPath

Usage: ${nfu.UnGetAppPath} out:AppPath in:AppName

Description: This is ${nfu.GetAppPath} for use in uninstallers.

nfu.GetParameter

Usage: ${nfu.GetParameter} out:FirstParameter out:RemainingParameters in:ParameterList

Description: Puts the first parameter of the parameterlist to FirstParameter and returns the remaining list left-trimmed in RemainingParameters. If the first parameter is enclosed in quotes, then they will be removed and the remaining string will be trimmed.

nfu.UnGetParameter

Usage: ${nfu.UnGetParameter} out:FirstParameter out:RemainingParameters in:ParameterList

Description: This is ${nfu.GetParameter} for use in uninstallers.

nfu.ProcessStdSwitches

Usage: ${nfu.ProcessStdSwitches} out:CommandLine in:Usage in:Legend in:ShowHelpWhenNoParams

Description: When adding this function with ${nfu.!AddFunction} to your project, you will not only add the code needed to process the commandline-switches /?, /e and /x (the standard switches), but you will also add a directory-, an instfiles-, a (dummy-)licensepage and a hidden section, intended to extract all files, which are needed to recompile the installer with the same functionality as the original installer.
The function should be used as the first instruction in the onInit-Callback of the project. The function will not return, when any of the standard switches have been found at the beginning of the commandline, or when the commandline is empty and you have passed '1' for the parameter ShowHelpWhenNoParams.
ProcessStdSwitches merges the parameters Usage and Legend into its standard helpscreen for the switches /?, /e and /x. If your regular installer does not support commandline-switches, you may leave all in-parameters of the function empty ("").
When the function returns, the parameter CommandLine will contain the original commandline, where the first item (%0, usually the exename of the installer) has been removed.
You will need ${nfu.!AddFile} instead of NSIS' regular FILE-instruction to tell nfUtils which files have to be added to the projectfiles.
See also the macros ${nfu.SkipPageOnSrcExtract} and ${nfu.SkipSectionOnSrcExtract} for preparing your regular installer-pages and sections to cooperate with ProcessStdSwitches.
Note: This function has been tested only with NSIS "Classic" Installers. I'm curious to see if there will be problems with Modern UI...

nfu.UnProcessStdSwitches

Usage: ${nfu.UnProcessStdSwitches} out:CommandLine in:Usage in:Legend in:ShowHelpWhenNoParams

Description: This is ${nfu.ProcessStdSwitches} for use in uninstallers.

nfu.myName

Usage: ${nfu.myName}

Description: This symbol will be !defined by ${nfu.SetInstallerName} or ${nfu.SetStdAttributes} and is set to the value of the parameter 'InstallerName'.

nfu.myVersion

Usage: ${nfu.myVersion}

Description: This symbol will be !defined by ${nfu.SetVersionInfo} or ${nfu.SetStdAttributes} and is set to the value of the parameter 'Version'.

nfu.StdLicense

Usage: ${nfu.StdLicense}

Description: This symbol contains the NSIS License without the first line for the Copyright holder (see NSIS User Manual, Appendix I).

NFU_VERBOSITY

Usage: ${NFU_VERBOSITY}

Description: The value of this symbol controls the verbosity of nfUtils. Possible values are: 4=all, 3=code+symbols, 2=only code, 1=none (==nsis-verbose 3), 0=ignore NFU_VERBOSITY (do not change verbosity of current script, except for errors).
The default is 2, you may define another value N in MakeNSIS' commandline with /DNFU_VERBOSITY=N, or insert a !define prior to inclusion of nfUtils.
NFU_VERBOSITY will be preserved after inclusion of the header, so if you want to change verbosity after that point, you have to ${nfu.!Redefine} NFU_VERBOSITY N.