NfUtils header file: Difference between revisions
No edit summary |
|||
| (31 intermediate revisions by 2 users not shown) | |||
| Line 35: | Line 35: | ||
<highlight-nsis> | <highlight-nsis> | ||
!include "nfUtils.nsh" | |||
</highlight-nsis> | </highlight-nsis> | ||
| Line 46: | Line 46: | ||
</highlight-nsis> | </highlight-nsis> | ||
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 | 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 | ||
<highlight-nsis> | <highlight-nsis> | ||
| Line 52: | Line 52: | ||
</highlight-nsis> | </highlight-nsis> | ||
will give you an index of all descriptions, which have been installed with the prefix "nfu.", by using one of the macros { | 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.!InstallMacro}]], [[#nfu.!InstallFunction|${nfu.!InstallFunction}]] or [[#nfu.!InstallDescription|${nfu.!InstallDescription}]]. Finally, the instruction | ||
<highlight-nsis> | <highlight-nsis> | ||
| Line 58: | Line 58: | ||
</highlight-nsis> | </highlight-nsis> | ||
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 { | 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|${nfu.!Help}]] is only a by-product of the more important macros [[#nfu.!InstallFunction|${nfu.!InstallFunction}]] and [[#nfu.!InstallMacro|${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.):<br> | |||
[[#nfu.!FileVersion|${nfu.!FileVersion}]]<br> | |||
[[#nfu.!Help|${nfu.!Help}]]<br> | |||
[[#nfu.!IncludeTextIfExist|${nfu.!IncludeTextIfExist}]]<br> | |||
[[#nfu.SetInstallerName|${nfu.SetInstallerName}]]<br> | |||
[[#nfu.SetStdAttributes|${nfu.SetStdAttributes}]]<br> | |||
[[#nfu.SetVersionInfo|${nfu.SetVersionInfo}]]<br> | |||
=== nfu.!AddFile === | |||
---- | |||
Usage: ${nfu.!AddFile} FileOptions OutFolder<br><br> | Usage: ${nfu.!AddFile} FileOptions OutFolder<br><br> | ||
Description: You will need this macro only when using | Description: You will need this macro only when using [[#nfu.ProcessStdSwitches|${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 [[#nfu.ProcessStdSwitches|ProcessStdSwitches]] to the script via [[#nfu.!AddFunction|${nfu.!AddFunction}]].<br> | ||
Using !AddFile after "${nfu.!AddFunction} nfu.ProcessStdSwitches", will be | Using !AddFile after "[[#nfu.!AddFunction|${nfu.!AddFunction}]] nfu.ProcessStdSwitches", will be | ||
ignored.<br> | ignored.<br> | ||
The parameter Outfolder will instruct ProcessStdSwitches to extract the file(s) | The parameter ''Outfolder'' will instruct ProcessStdSwitches to extract the file(s) | ||
to the specified subfolder within the | to the specified subfolder within the destination folder the user has selected. | ||
When using '/ICON' as 'FileOptions', !AddFile will prepare the inclusion of the | When using '/ICON' as ''FileOptions'', !AddFile will prepare the inclusion of the | ||
icon, which will be set by SetInstallerName or SetStdAttributes. '/ICON' will use | icon, which will be set by [[#nfu.SetInstallerName|SetInstallerName]] or [[#nfu.SetStdAttributes|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. | ||
values will change the | |||
=== nfu.!AddFunction === | |||
---- | |||
Usage: ${nfu.!AddFunction} FunctionName<br><br> | Usage: ${nfu.!AddFunction} FunctionName<br><br> | ||
Description: Adds the code for the function FunctionName to the script. The function must have been installed with the supportmacro "InstallFunction". See | Description: Adds the code for the function ''FunctionName'' to the script. The function must have been installed with the supportmacro "InstallFunction". See [[#nfu.!InstallFunction|nfu.!InstallFunction]] for further information. | ||
=== nfu.!Append === | |||
---- | |||
Usage: ${nfu.!Append} SymbolName Value<br><br> | Usage: ${nfu.!Append} SymbolName Value<br><br> | ||
Description: Appends Value to SymbolName's value. SymbolName does not need to be defined. | Description: Appends ''Value'' to ''SymbolName'''s value. ''SymbolName'' does not need to be defined. | ||
=== nfu.!AppendIf === | |||
---- | |||
Usage: ${nfu.!AppendIf} Condition SymbolName Value<br><br> | Usage: ${nfu.!AppendIf} Condition SymbolName Value<br><br> | ||
Description: Appends Value to SymbolName's value if ! | Description: Appends ''Value'' to ''SymbolName'''s value if '''!if'''''Condition'' is met. ''SymbolName'' does not need to be defined. | ||
=== nfu.!Calculate === | |||
---- | |||
Usage: ${nfu.!Calculate} SymbolName Op Value<br><br> | Usage: ${nfu.!Calculate} SymbolName Op Value<br><br> | ||
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. | 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<br><br> | Usage: ${nfu.!Compare} ResultSymbol Value1 Value2<br><br> | ||
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. | 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. | ||
<br>'''Note:''' This macro is obsolete since NSIS 2.19, because '''!if''' will do the same. | |||
=== nfu.!Exchange === | |||
---- | |||
Usage: ${nfu.!Exchange} SymbolName1 SymbolName2<br><br> | Usage: ${nfu.!Exchange} SymbolName1 SymbolName2<br><br> | ||
Description: Exchanges the values of both symbols. None of the symbols need to be defined. | Description: Exchanges the values of both symbols. None of the symbols need to be defined. | ||
== nfu.!FileVersion == | === nfu.!FileVersion === | ||
---- | |||
Usage: ${nfu.!FileVersion} SymbolName Filename<br><br> | Usage: ${nfu.!FileVersion} SymbolName Filename<br><br> | ||
Description: Redefines the symbol 'SymbolName' with the fileversion of '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 | ''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. | version information, then the symbol's value will be empty. | ||
<br>'''Note:''' This instruction has [[#Documentation|limitations]]. | |||
== nfu.!FreeFile == | === nfu.!FreeFile === | ||
---- | |||
Usage: ${nfu.!FreeFile}<br><br> | Usage: ${nfu.!FreeFile}<br><br> | ||
Description: Deletes the last temporary file created by | Description: Deletes the last temporary file created by [[#nfu.!MakeFile|${nfu.!MakeFile}]]. | ||
=== nfu.!FreeSymbol === | |||
---- | |||
Usage: ${nfu.!FreeSymbol}<br><br> | Usage: ${nfu.!FreeSymbol}<br><br> | ||
Description: ! | Description: '''!undef'''ines the last symbol created by [[#nfu.!MakeSymbol|${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<br><br> | Usage: ${nfu.Function} FunctionName io1 v1 io2 v2 io3 v3 io4 v4 io5 v5 io6 v6 io7 v7 io8 v8 io9 v9 io10 v10<br><br> | ||
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 | 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 ("" "").<br> | ||
The macro expects that the first input parameter (the leftmost | The macro expects that the first input parameter (the leftmost ''V''n with ''IO''n='''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|${nfu.!InstallFunction}]] to prepare the call of a function. See also [[#nfu.FunctionEnd|${nfu.FunctionEnd}]]. | ||
<br>'''Note:''' Beginning with NSIS 2.19, the keywords '''in''' and '''out''' no longer need to be lowercase. | |||
=== nfu.FunctionEnd === | |||
---- | |||
Usage: ${nfu.FunctionEnd}<br><br> | Usage: ${nfu.FunctionEnd}<br><br> | ||
Description: Inserts the code prepared by | Description: Inserts the code prepared by [[#nfu.Function|${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|${nfu.Function}]]. The macro closes your functionbody with the keyword '''FunctionEnd'''. | ||
== nfu.!Help == | === nfu.!Help === | ||
---- | |||
Usage: ${nfu.!Help} | Usage: ${nfu.!Help} Item<br><br> | ||
Description: Shows | Description: Shows usage and description for items, which have been registered with [[#nfu.!InstallMacro|${nfu.!InstallMacro}]], [[#nfu.!InstallFunction|${nfu.!InstallFunction}]] or [[#nfu.!InstallDescription|${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. | ||
<br>'''Note:''' This instruction has [[#Documentation|limitations]]. | |||
=== nfu.HideBackButton === | |||
---- | |||
Usage: ${nfu.HideBackButton}<br><br> | Usage: ${nfu.HideBackButton}<br><br> | ||
Description: Hides the Back-Button, when used in the Show-Callback of | Description: Hides the Back-Button, when used in the Show-Callback of an installer page. | ||
=== nfu.HideCancelButton === | |||
---- | |||
Usage: ${nfu.HideCancelButton}<br><br> | Usage: ${nfu.HideCancelButton}<br><br> | ||
Description: Hides the Cancel-Button, when used in the Show-Callback of | Description: Hides the Cancel-Button, when used in the Show-Callback of an installer page. | ||
=== nfu.!IncludeFileIf === | |||
---- | |||
Usage: ${nfu.!IncludeFileIf} Condition IncludeFileName<br><br> | Usage: ${nfu.!IncludeFileIf} Condition IncludeFileName<br><br> | ||
Description: !IncludeFileIf will ! | Description: !IncludeFileIf will '''!include''' the specified file, if '''!if'''''Condition'' 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<br><br> | Usage: ${nfu.!IncludeTextIfExist} FileName IncludeText<br><br> | ||
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. | 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. | ||
<br>'''Note:''' This instruction has [[#Documentation|limitations]]. | |||
== nfu.!InstallDescription == | === nfu.!InstallDescription === | ||
---- | |||
Usage: ${nfu.!InstallDescription} Prefix Item Usage Description<br><br> | |||
Description: Adds ''PrefixItem'' to NFU's helpsystem. You may query ''Usage'' and ''Description'' by adding [[#nfu.!Help|${nfu.!Help}]] ''PrefixItem'' to your script. | |||
Usage: ${nfu.! | === nfu.!InstallFunction === | ||
Description: | ---- | ||
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<br><br> | |||
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.<br> | |||
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.<br> | |||
The macro parameters 'Un1' and 'Un2' will be passed as "" and "" or "Un" and "un.", when you [[#nfu.!AddFunction|${nfu.!AddFunction}]] PrefixFunctionName or PrefixUnFunctionName.<br> | |||
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*).<br> | |||
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.<br> | |||
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 | |||
<highlight-nsis> | |||
Usage: ${PrefixFunctionName} out:Parameter in:Parameter | |||
</highlight-nsis> | |||
so please use names, which contribute a little more to the meaning of a parameter | |||
than this poor example.<br> | than this poor example.<br> | ||
The parameter 'Description' will be displayed in the integrated helpsystem. You may use "", if you dont want to give a description.<br> | The parameter ''Description'' will be displayed in the integrated helpsystem. You may use "", if you dont want to give a description.<br> | ||
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.<br> | 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.<br> | ||
Before you may use these symbols, you have to add the function's code outside of | 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 | any section or function by adding '[[#nfu.!AddFunction|${nfu.!AddFunction}]] PrefixFunctionName' to your script. Use '[[#nfu.!AddFunction|${nfu.!AddFunction}]] PrefixUnFunctionName', if you want to include the function in an uninstaller. | ||
script. Use '${nfu.!AddFunction} PrefixUnFunctionName', if you want to include the | <br>'''Note:''' Beginning with NSIS 2.19, the keywords '''in''' and '''out''' no longer need to be lowercase. | ||
function in an uninstaller. | |||
=== nfu.!InstallMacro === | |||
---- | |||
Usage: ${nfu.!InstallMacro} Prefix MacroName ParamList Description<br><br> | Usage: ${nfu.!InstallMacro} Prefix MacroName ParamList Description<br><br> | ||
Description: ! | Description: '''!define'''s 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}<br><br> | Usage: ${nfu.!MakeFile}<br><br> | ||
Description: Inserts the instruction | 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 '''!undef'''ine symbols created by this macro, use [[#nfu.!FreeFile|${nfu.!FreeFile}]] to delete the file and undefine the symbol. | ||
=== nfu.!MakeSymbol === | |||
---- | |||
Usage: ${nfu.!MakeSymbol} Value<br><br> | Usage: ${nfu.!MakeSymbol} Value<br><br> | ||
Description: Defines a temporary symbol. Use "${nfu.TempSymbol}" to access its name, and "${${nfu.TempSymbol}}" to get its value. Never ! | Description: Defines a temporary symbol. Use "${nfu.TempSymbol}" to access its name, and "${${nfu.TempSymbol}}" to get its value. Never '''!undef'''ine symbols created by this macro, use [[#nfu.!FreeSymbol|${nfu.!FreeSymbol}]] instead. | ||
=== nfu.!Redefine === | |||
---- | |||
Usage: ${nfu.!Redefine} SymbolName Value<br><br> | Usage: ${nfu.!Redefine} SymbolName Value<br><br> | ||
Description: Redefines SymbolName with the new Value. SymbolName does not need to be defined. | Description: Redefines ''SymbolName'' with the new ''Value''. ''SymbolName'' does not need to be defined. | ||
=== nfu.!Replace === | |||
---- | |||
Usage: ${nfu.!Replace} DstSymbolName SrcString SearchFor ReplaceWith<br><br> | Usage: ${nfu.!Replace} DstSymbolName SrcString SearchFor ReplaceWith<br><br> | ||
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'.<br> | 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''.<br> | ||
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 | 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|${nfu.!MakeSymbol}]].<br> | ||
You may inhibit or defer the evaluation of symbols with this macro. Compare | You may inhibit or defer the evaluation of symbols with this macro. Compare the results of the following instructions: | ||
the results of the following | |||
<highlight-nsis> | <highlight-nsis> | ||
!echo '--- ${nfu.Help} ---' | !echo '--- ${nfu.Help} ---' | ||
| Line 211: | Line 227: | ||
</highlight-nsis> | </highlight-nsis> | ||
== nfu.SetInstallerName == | === nfu.SetInstallerName === | ||
---- | |||
Usage: ${nfu.SetInstallerName} InstallerName<br><br> | Usage: ${nfu.SetInstallerName} InstallerName<br><br> | ||
Description: Sets the installer attributes 'Name', 'Caption', 'Outfile' and 'Icon' to '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 | Description: Sets the installer attributes | ||
[{{SERVER}}/Docs/Chapter4.html#4.8.1.30 '''Name'''], | |||
[{{SERVER}}/Docs/Chapter4.html#4.8.1.7 '''Caption'''], | |||
[{{SERVER}}/Docs/Chapter4.html#4.8.1.31 '''Outfile'''] and | |||
[{{SERVER}}/Docs/Chapter4.html#4.8.1.18 '''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|nfu.myName]], which will be set to ''InstallerName'' for later use in your code. | |||
<br>'''Note:''' This instruction has [[#Documentation|limitations]]. | |||
=== nfu.SetStdAttributes === | |||
---- | |||
Usage: ${nfu.SetStdAttributes} InstallerName Version Company Copyright Comments<br><br> | Usage: ${nfu.SetStdAttributes} InstallerName Version Company Copyright Comments<br><br> | ||
Description: Invokes ${nfu.SetInstallerName} and ${nfu.SetVersionInfo}. | Description: Invokes [[#nfu.SetInstallerName|${nfu.SetInstallerName}]] and [[#nfu.SetVersionInfo|${nfu.SetVersionInfo}]]. | ||
<br>'''Note:''' This instruction has [[#Documentation|limitations]]. | |||
=== nfu.SetVersionInfo === | |||
---- | |||
Usage: ${nfu.SetVersionInfo} InstallerName Version Company Copyright Comments<br><br> | Usage: ${nfu.SetVersionInfo} InstallerName Version Company Copyright Comments<br><br> | ||
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 | Description: Sets the installer attributes for the [{{SERVER}}/Docs/Chapter4.html#4.8.3.1 installer's version information]. ''InstallerName'' will be set for the | ||
'Version' for later use in your code. | [{{SERVER}}/Docs/Chapter4.html#4.8.3.1 '''ProductName'''], | ||
[{{SERVER}}/Docs/Chapter4.html#4.8.3.1 '''FileDescription'''], | |||
[{{SERVER}}/Docs/Chapter4.html#4.8.3.1 '''InternalName'''] and | |||
[{{SERVER}}/Docs/Chapter4.html#4.8.3.1 '''OriginalFileName''']. | |||
''Version'' will be used for the [{{SERVER}}/Docs/Chapter4.html#4.8.3.2 '''ProductVersion'''] and [{{SERVER}}/Docs/Chapter4.html#4.8.3.1 '''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|nfu.myVersion]], which will be set to ''Version'' for later use in your code. | |||
<br>'''Note:''' This instruction has [[#Documentation|limitations]]. | |||
=== nfu.SkipPageOnSrcExtract === | |||
---- | |||
Usage: ${nfu.SkipPageOnSrcExtract}<br><br> | Usage: ${nfu.SkipPageOnSrcExtract}<br><br> | ||
Description: You will need this only, if you wish to use '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. | Description: You will need this only, if you wish to use '[[#nfu.ProcessStdSwitches|nfu.ProcessStdSwitches]]' and you have defined one or more installerpages before adding [[#nfu.ProcessStdSwitches|ProcessStdSwitches]] with [[#nfu.!AddFunction|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}<br><br> | Usage: ${nfu.SkipSectionOnSrcExtract}<br><br> | ||
Description: You will need this only, if you wish to use '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. | Description: You will need this only, if you wish to use '[[#nfu.ProcessStdSwitches|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<br><br> | Usage: ${nfu.!Undefine} SymbolName<br><br> | ||
Description: Undefines SymbolName. SymbolName does not need to be defined. | Description: Undefines ''SymbolName''. ''SymbolName'' does not need to be defined. | ||
=== nfu.GetAppPath === | |||
---- | |||
Usage: ${nfu.GetAppPath} out:AppPath in:AppName<br><br> | Usage: ${nfu.GetAppPath} out:AppPath in:AppName<br><br> | ||
Description: Returns the fullpath of an application, which is registered under | 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. | "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<br><br> | Usage: ${nfu.UnGetAppPath} out:AppPath in:AppName<br><br> | ||
Description: This is ${nfu.GetAppPath} for use in uninstallers. | Description: This is [[#nfu.GetAppPath|${nfu.GetAppPath}]] for use in uninstallers. | ||
=== nfu.GetParameter === | |||
---- | |||
Usage: ${nfu.GetParameter} out:FirstParameter out:RemainingParameters in:ParameterList<br><br> | Usage: ${nfu.GetParameter} out:FirstParameter out:RemainingParameters in:ParameterList<br><br> | ||
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. | 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<br><br> | Usage: ${nfu.UnGetParameter} out:FirstParameter out:RemainingParameters in:ParameterList<br><br> | ||
Description: This is ${nfu.GetParameter} for use in uninstallers. | Description: This is [[#nfu.GetParameter|${nfu.GetParameter}]] for use in uninstallers. | ||
=== nfu.ProcessStdSwitches === | |||
---- | |||
Usage: ${nfu.ProcessStdSwitches} out:CommandLine in:Usage in:Legend in:ShowHelpWhenNoParams <br><br> | Usage: ${nfu.ProcessStdSwitches} out:CommandLine in:Usage in:Legend in:ShowHelpWhenNoParams <br><br> | ||
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.<br> | Description: When adding this function with [[#nfu.!AddFunction|${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.<br> | ||
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'.<br> | 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''.<br> | ||
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 ("").<br> | 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 ("").<br> | ||
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.<br> | 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.<br> | ||
You will need ${nfu.!AddFile} instead of NSIS' regular FILE-instruction to tell nfUtils which files have to be added to the projectfiles.<br> | You will need [[#nfu.!AddFile|${nfu.!AddFile}]] instead of NSIS' regular '''FILE'''-instruction to tell nfUtils which files have to be added to the projectfiles.<br> | ||
See also the macros ${nfu.SkipPageOnSrcExtract} and ${nfu.SkipSectionOnSrcExtract} for preparing your regular installer-pages and sections to cooperate with ProcessStdSwitches. | See also the macros [[#nfu.SkipPageOnSrcExtract|${nfu.SkipPageOnSrcExtract}]] and [[#nfu.SkipSectionOnSrcExtract|${nfu.SkipSectionOnSrcExtract}]] for preparing your regular installer-pages and sections to cooperate with ProcessStdSwitches.<br> | ||
'''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 == | === nfu.UnProcessStdSwitches === | ||
---- | |||
Usage: ${nfu.UnProcessStdSwitches} out:CommandLine in:Usage in:Legend in:ShowHelpWhenNoParams <br><br> | Usage: ${nfu.UnProcessStdSwitches} out:CommandLine in:Usage in:Legend in:ShowHelpWhenNoParams <br><br> | ||
Description: This is ${nfu.ProcessStdSwitches} for use in uninstallers. | Description: This is [[#nfu.ProcessStdSwitches|${nfu.ProcessStdSwitches}]] for use in uninstallers. | ||
=== nfu.myName === | |||
---- | |||
Usage: ${nfu.myName}<br><br> | Usage: ${nfu.myName}<br><br> | ||
Description: This symbol will be ! | Description: This symbol will be '''!define'''d by [[#nfu.SetInstallerName|${nfu.SetInstallerName}]] or [[#nfu.SetStdAttributes|${nfu.SetStdAttributes}]] and is set to the value of the parameter 'InstallerName'. | ||
=== nfu.myVersion === | |||
---- | |||
Usage: ${nfu.myVersion}<br><br> | Usage: ${nfu.myVersion}<br><br> | ||
Description: This symbol will be ! | Description: This symbol will be '''!define'''d by [[#nfu.SetVersionInfo|${nfu.SetVersionInfo}]] or [[#nfu.SetStdAttributes|${nfu.SetStdAttributes}]] and is set to the value of the parameter 'Version'. | ||
=== nfu.StdLicense === | |||
---- | |||
Usage: ${nfu.StdLicense}<br><br> | Usage: ${nfu.StdLicense}<br><br> | ||
Description: This symbol contains the NSIS License without the first line for the Copyright holder (see NSIS User Manual, Appendix I). | Description: This symbol contains the NSIS License without the first line for the Copyright holder (see NSIS User Manual, [{{SERVER}}/Docs/AppendixI.html Appendix I]). | ||
=== NFU_VERBOSITY === | |||
---- | |||
Usage: ${NFU_VERBOSITY}<br><br> | Usage: ${NFU_VERBOSITY}<br><br> | ||
Description: | 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).<br> | ||
The default is 2, you may define another value N in MakeNSIS' commandline with /DNFU_VERBOSITY=N, or insert a ! | 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.<br> | ||
NFU_VERBOSITY will be preserved after inclusion of the header, so if you want to change verbosity after that point, you have to ${ | 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.!Redefine}]] NFU_VERBOSITY N. | ||
[[Category:Headers]] | [[Category:Headers]] | ||
Latest revision as of 16:32, 11 June 2010
| Author: niteflyer (talk, contrib) |
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.
