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:

Download perl plugin

The nsperl.dll included in the package is linked with Perl ActiveState 5.8.3 DLL. 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).

Here is the changelog:

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.

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.