Perl plugin
| Author: fabpot (talk, contrib) |
This is a plugin DLL to allow to execute Perl code within a NSIS installer. This code is heavily borrowed from the nsPython code.
Distributed under the Perl Artistic License.
To install the plugin, download and install the following NSIS installer:
The nsperl.dll included in this package is linked with Perl ActiveState 5.8.3 DLL. If you want to link it with another version, just recompile the nsperl.dll. You may test without recompiling nsperl.dll with Opensource Perl 5.8.8.2 version (Strawberry Perl project): Perl58.dll_(strawberry-perl-5.8.8.2).zip
The nsperl.dll included in this package is linked with the offical Perl 5.10.1 compiled with visual studio express 2008. If you want to link it with another version, just recompile the nsperl.dll.
Example of simple functions in Perl:
- To convert the string in $0 in uppercase
nsPerl::exec "uc(NSIS_getvar('0'))" Pop $0
- To change \ by / for $0
nsPerl::exec "$$a = NSIS_getvar('0'); $$a =~ s#\\#/#g; $$a" Pop $0
Comments, bugs and suggestions are welcomed. Send them to Fabien POTENCIER (fabpot@cpan.org), current maintainer Nicolas GEORGES (xlat@cpan.org).
Here is the changelog:
version 1.4.1 - 10/04/2011 ( xlat@cpan.org )
- fix XSLoader related bugs
- add Win32::GUI compiled package to demonstrate testgui_nsPerl.nsi
version 1.4 - 09/04/2011 ( xlat@cpan.org )
- add NSIS_pushstr / NSIS_popstr
- ported to perl 5.10.1 (included compiled perl510.dll)
- build project ported to VC 2008 Express
version 1.3 - 09/11/2004
- some doc tweaks
- always returns 2 strings on the stack (error or ok + string)
- use reshack to pack a perl script in a resource with packhdr (no need to use CRCCheck Off)
- new example with a Win32::GUI script
- use /NOUNLOAD between perl invocation
- refactor the code / fix some bugs
- get rid of the standard C library : now nsPerl.dll is 8ko (from 32ko)
version 1.2 - 04/04/2004
- add execResource to be able to embed a perl script in the .exe (as a RCDATA resource)
version 1.1 - 03/25/2004
- include nsPerl installer .nsi file
version 1.0 - 03/24/2004
- initial version
Here is the readme file:
INTRODUCTION
This is a plugin DLL for the Nullsoft installer system NSIS. It allows to execute Perl code within the installer.
The packed perl58.dll adds about 800k to the installer executable.
Distributed under the Perl Artistic License.
This code is heavily borrowed from the nsPython code. It tries to mimic its interface.
Comments, bugs and suggestions are welcomed. Send them to Fabien POTENCIER (fabpot@cpan.org) If you use it, please send me a note, your usage and perhaps some scripts examples.
INSTALLATION
Just launch the installer. The only mandatory file is nsPerl.dll.
NSIS functions
All functions always returns 2 strings on stack :
- "error" if an error is held or "ok" if everything is fine. - the error message or the result.
nsPerl::exec statements
Execute arbitrary perl code. The return value is the last statement result. Data can be passed back through NSIS-variables.
nsPerl::execResource name
Same as exec but the code is loaded from the RCDATA resource name. To be able to use this function, you must add a RCDATA resource to your exe installer with the perl source code. You must also disable CRC check (CRCCheck Off) if you add the resource after the .exe creation or better, you can use packhdr with reshacker (cf. testgui_nsPerl.nsi for an example).
nsPerl::execFile file
Same as exec but the code is loaded from the given filename.
To avoid the loading of the DLL each time you launch a script, you can use /NOUNLOAD.
There are two examples in the "examples" directory to help you start.
The Perl DLL has to be carried with the installer and unpacked. This is also needed for external perl scripts with execFile and for library modules that are used.
ReserveFile "perl58.dll"
Function .onInit
;Extract Install Options files
;$PLUGINSDIR will automatically be removed when the installer closes
InitPluginsDir
File /oname=$PLUGINSDIR\perl58.dll "perl58.dll"
FunctionEnd
If you want to be able to call your script from command line and from NSIS, you can add
something like that at the top of your perl script:
eval { main::NSIS_getvar('R0'); }; if ($@) { *main::NSIS_log = sub { print STDERR "$_[0] "; }; *main::NSIS_getvar = sub { return ; }; }
NSIS extension functions
The called perl code can use the following functions:
NSIS_log(string)
Write Messages to the NSIS log window.
NSIS_messagebox(string, title)
Pop up a message box. The execution is suspended until the message box is closed. title is optional.
NSIS_getvar(varname_string)
Get a variable from NSIS. The contents of a variable is always a string.
NSIS_setvar(varname_string, value_string)
Set a variable from NSIS. The contents of a variable is always a string.
NSIS_getparent()
Get the parent's handle of the installer. This can be useful in conjunction with Win32::* modules.
v1.4 Introduce:
NSIS_pushstr(value)
Push given value on the NSIS stack. The contents of a variable is always a string.
NSIS_popstr()
Pop a value from the NSIS stack. The contents of a variable is always a string.
HINT
If your installer quits with the message "Unable to load [some path to]\nsPerl.dll" make sure you ship the perl58.dll (or the one that you linked the nsPerl.dll against) with your installer.
Assuming perl58.dll lies in ${NSISDIR}\Plugins\perl58.dll then your code should look like this to make sure everything is packed correctly:
ReserveFile "${NSISDIR}\Plugins\perl58.dll"
Function .onInit
;Extract Install Options files
;$PLUGINSDIR will automatically be removed when the installer closes
InitPluginsDir
File /oname=$PLUGINSDIR\perl58.dll "${NSISDIR}\Plugins\perl58.dll"
FunctionEnd
DISCLAIMER
THIS IS EXPERIMENTAL SOFTWARE. USE AT YOUR OWN RISK. THE AUTHORS CAN NOT BE HELD LIABLE UNDER ANY CIRCUMSTANCES FOR DAMAGE TO HARDWARE OR SOFTWARE, LOST DATA, OR OTHER DIRECT OR INDIRECT DAMAGE RESULTING FROM THE USE OF THIS SOFTWARE. IF YOU DO NOT AGREE TO THESE CONDITIONS, YOU ARE NOT PERMITTED
TO USE OR FURTHER DISTRIBUTE THIS SOFTWARE.
