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

updated outdated stuff, pages / plug-in calls / multiple languages improved, red defaults, fixes

Browse source 
git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@3150 212acab6-be3b-0410-9dea-997c60f758d6
This commit is contained in:
joostverburg 2003-11-16 19:57:44 +00:00
parent b0d4888c3a
commit 1026f26b40
6 changed files with 71 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

24
Docs/src/plugin.but
View file

@ -4,28 +4,24 @@ The abilities of the NSIS scripting language can be extended by utilising functi
When the NSIS compiler starts it scans the plugins directory for DLLs and makes a list of the plugins found and their exported functions. During compilation if a sequence such as fred::flintstone is encountered where the compiler expected to find a language keyword the compiler will look through this list. If a list entry specifies that fred.dll exports function flintstone NSIS will pack the fred.dll file into the created installer binary.
During execution of the created installer if a plugin command is executed NSIS will unpack the necessary DLL to the $TEMP directory, push all of the arguments specified (right-to-left order), and then execute the DLL function. If the /NOUNLOAD option is specified the DLL will not be unloaded until the installer exits or the next time you use the DLL without /NOUNLOAD. Please note that the last call to the plugin must not have the /NOUNLOAD flag or the plugin will not be deleted from $PLUGINSDIR, thus garbage will be left on the user's machine.
During execution of a plugin command NSIS will unpack the necessary DLL to a temporary folder ($PLUGINSDIR), push all of the arguments specified (right-to-left order), and then execute the DLL function. If the /NOUNLOAD option is specified the DLL will not be unloaded until the installer exits or the next time you use the DLL without /NOUNLOAD. Please note that the last call to the plugin must not have the /NOUNLOAD flag or the plugin will not be deleted from $PLUGINSDIR, thus garbage will be left on the user's machine.
\S1{usingplug} Using Plugin Commands
The following two examples both invoke the same plugin command. The first example shows the (still okay) syntax that scripts written for versions of NSIS earlier than 2.0a4 had to use, and the second is how it can be scripted more succinctly now. The newer syntax automatically handles packing & extraction of the DLL file, and stacks up arguments for you too.
A plug-in call looks like this:
\c ; Pre 2.0a4 syntax
\c SetOutPath $TEMP
\c GetTempFileName $8
\c File /oname=$8 InstallOptions.dll
\c Push "ini_file_location.ini"
\c CallInstDLL dialog
\c ; Newer syntax
\c InstallOptions::dialog "ini_file_location.ini"
InstallOptions needs the name of it's ini file as a parameter to the dialog function so it has to be pushed onto the stack before the dialog call is made. Some plugin commands may not need any parameters on the stack, others might require two or three. To use a plugin command you will need to read the documentation for the plugin so that you know what parameters it's functions require, if any.
All parameters are pushed onto the stack (in this case, the plug-in function only needs one parameter). Some plugin commands may not need any parameters on the stack, others might require more of them. To use a plug-in command you will need to read the documentation for the plug-in so that you know what parameters its functions require.
\S1{disablingplug} Disabling Plugin Unloading
CallInstDLL has an option not to unload the DLL after usage. To use it with the newer plugin command syntax just specify the first parameter as /NOUNLOAD. For example:
If you don't want to unload the DLL after calling a function, use /NOUNLOAD as the first parameter. For example:
\c InstallOptions::dialog /NOUNLOAD "ini_file_location.ini"
\c dll:function /NOUNLOAD "param"
You can also use \R{setpluginunload}{SetPluginUnload} alwaysoff to avoid writing /NOUNLOAD each and every time you use the same plugin.
You can also use \R{setpluginunload}{SetPluginUnload} alwaysoff to avoid writing /NOUNLOAD each and every time you use the same plugin.
\S1{calldiskplug} Calling plug-ins manually
If you want to call a plug-in that is stored on user's hard drive or somewhere else, use \R{callinstdll}{CallInstDLL}. Almost all plug-ins provide installer functionality, so using plug-in commands is way easier. Using \R{callinstdll}{CallInstDLL} can be useful when you have created plug-ins that should be linked to a certain version of your application and are being copied to the installation folder.