Stunnix Advanced Web Server - packsite-par - utility to pack site into single executable

• NAME
• SYNOPSIS
• DESCRIPTION
• BUILDING TREE WITH UNPACKED VERSIONS OF SITE, SERVER AND PERL
• OPTIONS
• EXAMPLES

NAME

packsite-par.pl - a script to pack a dynamic Perl-driven web site and Stunnix Perl Web Server into a single executable image.

SYNOPSIS

packsite-par.pl  -D directory-to-append ..   -o output-base-name  [ -z|--need-zip ] [ -r path-to-main-script ] [ -M list-of-required-modules ]..

DESCRIPTION

This is a script to automate building standalone executables containing Stunnix Perl Web Server and the perl-driven dynamic web site, along with utility to start web server automatically on the machine where executable is run and open browser window to show the default page of the site. The backend for building executables used is PAR - http://par.perl.org.

It also can be used for building minimal sets of Perl modules required by Stunnix Perl Web Server and web site, in order to use these modules and perl interpreter iteself as standalone runtime for running web server and site even if no installation of Perl interpreter is present in the system.

The executable is built in 2 stages - at first temporary ZIP archive is created that contains only core modules (i.e. the modules that are present in the installation of perl) used by Stunnix Perl Web Server and dynamic web site. The output of the first stage can be kept in ZIP file if commandline option -z is passed on commandline. On the second stage, that is actually optional, all required resources - namely the web server implementation and entire web site (the names of the directories containing all resources are specified via -D commandline option) - are appended to that ZIP file; after that the ZIP file and perl interpreter are effectively appended to general-purpose executable loader that unpacks ZIP file at runtime and starts the appended perl interpreter for running the file specified by -r option. The base name for the ZIP archive and executable file (i.e. names of files with extension trimmed) is specified with -o commandline option. If dynamic site requires non-standard Perl modules, their names, one per line, should be listed in files; names of these files with lists of modules should be specified via -M option.

The executable files produced this way will unpack the appended ZIP file and perl interpreter to the special cache directory (typically located in /tmp/par-$USER/ on unix or in c:/documents-and-settings/$USER/local settings/par-$USER on WindowsNT-based OSes or in c:/windows/temp/par-$USER on Win9x-based OSes), and run perl interpreter from that directory for execution of the script specified via -r option. On the termination of the script, the cache directory won't be deleted, to speedup starting on the next invokation. Due to this caching it may be inconvenient to pack huge sites into executables since it will take a lot of time to unpack them first time executable is run, and a lot of disk space on the user's box will be taken by extracted version of the site.

For these reasons, shipping dynamic site and perl interpreter with all modules required for running web server and site in the unpacked form may be more convenient. Such way of packing also reduces total size of the data to ship in case browser-based application is meant to be cross-platform and runable on several platforms from the same media (e.g. CDROM). The next section covers this topic.

BUILDING TREE WITH UNPACKED VERSIONS OF SITE, SERVER AND PERL

Please read last paragraphs of previous section on why it may be mode preferable to ship everything in uncompressed form.

To ship site, web server and perl interpreter with all modules in uncompressed form, one has to gather all modules and files used by them that are required to run Stunnix Perl Web Server and web site.

One way of doing this is to use this utility and to specify filenames with list of modules required by the site using -M option as usual and add the -z option. As a result, a .ZIP file will be produced that will contain all modules specified and all files they require (namely dynamically loadable libraries with native code). One has to unpack the resulting ZIP file to some directory and copy perl interpreter (typically /usr/bin/perl or `which perl` on Unix or c:\perl\bin\perl.exe and c:\perl\bin\perlNN.dll on Windows, where NN is 2 digits of perl version number - e.g. ``56'') to the parent directory of it. This is basically all that needs to be done. If the site is for some sort of CDROM, one also will need to write autorun.inf and autorun files for automatic execution of the browser-based application on insertion of the CDROM. Please see autorun.inf and autorun in the same CDROM tree availalable on the http://www.stunnix.com/prod/ws/samplecd.shtml.

OPTIONS

The options after which there is a ellipsis (..) in the synopsis section accept a set of strings and thus may be specified several times. The values passed to such options will be merged. The values for all those options are strings that do not contain spaces and commas in them. If the value of such option contains only one space or comma, it is treated as there were two occurencies of that option with values formed from strings before and after that space or comma character. I.e. the following commandline strings will equally alter the behaviour of this script for option named -X:

    -X a -X b -X c -X d
    -X 'a b' -X c -X d
    -X 'a b c d'
    -X 'a,b' -X c -X d
    -X 'a,b,c,d'

-D directory-to-append

Specifies the directory with resources (i.e. Stunnix Perl Web Server or site itself) to be appended. Multiple -D options may be specified - in which trees will be merged in the resultant archive.

-o output-base-name

Basename for the output file. For ZIP archives, extension .zip will be appended automatically. For executables - default executable suffix will be appended automatically for the target OS. The default value for this option is program.

-z|--need-zip

If this option is passed, the intermediate ZIP file is preserved, and no executable is generated. This can be used for building sets of modules and their support files required for running Stunnix Perl Web Server and the site itself.

-M list-of-required-modules ]..

This option specifies names of files containing lists of modules used by your site. It requests the listed modules and their support files (like dynamilc libraries with native code and all required perl modules) to be added to the archive. The file with list of the modules should contain one module name perl line (everything after # is considered a comment). Such lists can be composed by using get-mods-list.pl utility shipped with Stunnix Perl-Obfus, or by transforming output of scandeps.pl utility (shipped with Module::ScanDeps module that is a requirement of PAR).

-r path-to-main-script

This option specifies relative path to the script that should be executed when executable is invoked. Most typically the name of the script will be startsite.pl; the path to the script is specified as a path to the script inside any of the directories specified by the -D option. The default value is script/startsite.pl.

EXAMPLES

The following commandline

    perl packsite-par.pl -o site -D image -r 1/script/startsite.pl -M modlist-obfui.txt

will pack Stunnix Perl Web Server and the site to the file with name site and extension specific to the OS; the contents of the directory image will be added to the archive; the script 1/script/startsite.pl will be executed when executable is run (so that file named image/1/script/startsite.pl should be present in the current directory); names of modules required by the site will be taken from file modlist-obfui.txt; it has the following content for Project Manager for Stunnix JavaScript Obfuscator:

 Data::Dumper
 Exporter
 File::Spec
 File::Spec::Unix

if -z switch is added to the commandline, file with name site.zip will be created in the current directory; it will contain all modules and their support files required for running Stunnix Perl Web Server and Project Manager.