NfUtils header file: Difference between revisions
No edit summary |
No edit summary |
||
Line 62: | Line 62: | ||
== Documentation == | == Documentation == | ||
nfUtils needs at least NSIS Version 2.15, the following instructions | 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.!FileVersion|${nfu.!FileVersion}]]<br> | ||
[[#nfu.!Help|${nfu.!Help}]]<br> | [[#nfu.!Help|${nfu.!Help}]]<br> |
Revision as of 17:19, 26 July 2006
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.
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 resultvalue 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}.
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} SymbolName
Description: Shows description for symbols, which have been registered with ${nfu.!InstallMacro}, ${nfu.!InstallFunction} or ${nfu.!InstallDescription}.
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 Symbol Usage Description
Description: Adds PrefixSymbol to NFU's helpsystem. You may query the Description by adding ${nfu.!Help} PrefixSymbol 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.
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.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.