PAR - Perl Archive Toolkit
This document describes version 0.62 of PAR, released January 7, 2002.
(If you want to make an executable that contains all module, scripts and data files, please consult pp instead.)
Following examples assume a foo.par file in Zip format; support for compressed tar (*.tgz/*.tbz2) format is under consideration.
To use Hello.pm from ./foo.par:
% perl -MPAR=./foo.par -MHello % perl -MPAR=./foo -MHello # the .par part is optional
Same thing, but search foo.par in the @INC;
@INC
% perl -MPAR -Ifoo.par -MHello % perl -MPAR -Ifoo -MHello # ditto
The search path for the above two examples are:
/ /lib/ /arch/ /i386-freebsd/ # i.e. $Config{archname} /5.8.0/ # i.e. $Config{version} /5.8.0/i386-freebsd/ # both of the above
Run test.pl or script/test.pl from foo.par:
% perl -MPAR foo.par test.pl # only when $0 ends in '.par'
However, if the .par archive contains either main.pl or script/main.pl, then it is used instead:
% perl -MPAR foo.par test.pl # runs main.pl, with 'test.pl' as @ARGV
Use in a program:
use PAR 'foo.par'; use Hello; # reads within foo.par # PAR::read_file() returns a file inside any loaded PARs my $conf = PAR::read_file('data/MyConfig.yaml'); # PAR::par_handle() returns an Archive::Zip handle my $zip = PAR::par_handle('foo.par') my $src = $zip->memberNamed('lib/Hello.pm')->contents;
This module lets you easily bundle a typical blib/ tree into a zip file, called a Perl Archive, or PAR.
PAR
It supports loading XS modules by overriding DynaLoader boostrapping methods; it writes shared object file to a temporary file at the time it is needed.
To generate a .par file, all you have to do is compress the modules under arch/ and lib/, e.g.:
% perl Makefile.PL % make % cd blib % zip -r mymodule.par arch/ lib/
Afterwards, you can just use mymodule.par anywhere in your @INC, use PAR, and it will Just Work.
For maximal convenience, you can set the PERL5OPT environment variable to -MPAR to enable PAR processing globally (the overhead is small if not used), or to -MPAR=/path/to/mylib.par to load a specific PAR file. Alternatively, consider using the par.pl utility bundled with this module.
PERL5OPT
-MPAR
-MPAR=/path/to/mylib.par
Note that self-containing scripts and executables created with par.pl and pp may also be used as .par archives:
% pp -o packed.exe source.pl # generate packed.exe % perl -MPAR=packed.exe other.pl # this also works % perl -MPAR -Ipacked.exe other.pl # ditto
Please see "SYNOPSIS" for most typical use cases.
Since version 0.60, all files and data are extracted into a temporary directory, with the same name as its CRC32 checksum, to speed up the loading time of the next round. To inhibit this behaviour, set the PAR_CLEARTEMP environment to a true value.
PAR_CLEARTEMP
If you object to this feature, or think that only shared object files should be left for the next round, just mail me. :-)
My presentation, "Introduction to Perl Archive Toolkit": http://www.autrijus.org/par-intro/slide001.html
par.pl, parl, pp
Archive::Zip, "require" in perlfunc
ex::lib::zip, Acme::use::strict::with::pride
Nicholas Clark for pointing out the mad source filter hook within the (also mad) coderef @INC hook, as well as (even madder) tricks one can play with PerlIO to avoid source filtering.
Ton Hospel for convincing me to ditch the Filter::Simple implementation.
Filter::Simple
Uri Guttman for suggesting read_file and par_handle interfaces.
read_file
par_handle
Antti Lankila for making me implement the self-contained executable options via par.pl -O.
par.pl -O
See the AUTHORS file in the distribution for a list of people who have sent helpful patches, ideas or comments.
Autrijus Tang <autrijus@autrijus.org>
Copyright 2002 by Autrijus Tang <autrijus@autrijus.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
To install PAR, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PAR
CPAN shell
perl -MCPAN -e shell install PAR
For more information on module installation, please visit the detailed CPAN module installation guide.