The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Archive-SelfExtract-1.3
River stage zero No dependents
++
/ Archive::SelfExtract

NAME

Archive::SelfExtract - bundle compressed archives with Perl code

SYNOPSIS

    use Archive::SelfExtract;
    
    # writes output script to STDOUT
    Archive::SelfExtract::createExtractor( "perlcode.pl", "somefiles.zip" );
    
    # with various options:
    Archive::SelfExtract::createExtractor( "perlcode.pl", "somefiles.zip",
                                           perlbin => "/opt/perl58/bin/perl",
                                           output_fh => $someFileHandle,
                                         );

See also the command line tool, mkselfextract.

DESCRIPTION

Archive::SelfExtract allows you create Perl programs out of compressed zip archives. Given a piece of code and an archive, it creates a single file which, when run, unpacks the archive and then runs the code.

This module provides a function for creating a self-extractor script, a function to unpack the archive, and utility functions for wrapped programs.

This module exports nothing.

Functions

createExtractor( $scriptFileName, $archiveFileName, %options )

Takes the contents of the given Perl script and zip archive, and outputs a Perl script which unpacks the archive and then executes the input script.

By default, the output is printed to STDOUT.

Available options:

output_fh

createExtractor() should use this filehandle instead of STDOUT for the generated script.

perlbin

By default, createExtractor() will generate a script with a shebang line of #!/usr/bin/perl, a typical location for the perl interpreter. If you need to use a different location, use the perlbin option.

cleanup()

Deletes the temporary directory into which the archive was unpacked. Wrapped scripts may wish to use this before they exit, to prevent excess pollution of the user's temporary space.

_extract( $filehandle )

Used by scripts generated by createExtractor(). You will typically not use this function directly.

Unpacks the archive in the wrapped script into the temporary directory $Archive::SelfExtract::Tempdir. If the unpacking is not successful, an exception is thrown.

The Wrapped Script

The input script which gets wrapped by createExtractor() has very few restrictions about what it may contain. However, Archive::SelfExtract works by inserting lines of code before and after the lines from the input. The script should not use __END__ or __DATA__ markers, since they will cause compilation of the genertated program to end prematurely.

To do anything useful, the script will probably want to know where the unpacked files are. This location is stored in $Archive::SelfExtract::Tempdir.

If you have tasks which need to be performed before the archive is unpacked, put them in a BEGIN block.

You may also want to call Archive::SelfExtract::cleanup() when exiting your script, otherwise the archived files will be left in the (supposedly temporary) location they were unpacked.

MOTIVATION

This was developed for creating single-file installers for application distributions. We needed a platform-independant bootstrapper which could get enough of an environment set up for the "real" installer (written in Java, as it happens) to run. Tools such as ActiveState's PerlApp, or pp from the PAR distribution, allow us to turn a generated self-extracting script into a standalone Win32 executable.

Archive::SelfExtract was conceived of for BIE, the open source Business Integration Engine from WDI. The WDI web site (http://www.brunswickwdi.com) provides the latest information about BIE.

TODO

Command line option control over the location of the temp directory, verbosity, etc.

Use something other than IO::Stringy for decompression, since holding the entire compressed archive in memory will get bad for large archives.

Accomodate __END__ in input scripts.

Use the "eval exec" trick instead of fretting over the shebang line.

Perhaps: allow zip to be attached as Base64 data, rather than as raw.

Perhaps: support formats other than zip.

SEE ALSO

mkselfextract, perl.

Compress::SelfExtracting shrinks a single program into a compressed file which is executable Perl code.

PAR allows packaging modules and scripts into single resources, and includes a tool for creating native executables out of those resources.

COPYRIGHT

Copyright 2004 Greg Fast (gdf@speakeasy.net)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.