|
|
PAR - Perl Archive Toolkit
This document describes version 0.93 of PAR, released Mai 11, 2006.
(If you want to make an executable that contains all module, scripts and data files, please consult the bundled pp utility 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;
% perl -MPAR -Ifoo.par -MHello
% perl -MPAR -Ifoo -MHello # ditto
Following paths inside the PAR file are searched:
/lib/
/arch/
/i386-freebsd/ # i.e. $Config{archname}
/5.8.0/ # i.e. $Config{version}
/5.8.0/i386-freebsd/ # both of the above
/
PAR files may also (recursively) contain other PAR files. All files under following paths will be considered as PAR files and searched as well:
/par/i386-freebsd/ # i.e. $Config{archname}
/par/5.8.0/ # i.e. $Config{version}
/par/5.8.0/i386-freebsd/ # both of the above
/par/
Run script/test.pl or test.pl from foo.par:
% perl -MPAR foo.par test.pl # only when $0 ends in '.par'
However, if the .par archive contains either script/main.pl or main.pl, then it is used instead:
% perl -MPAR foo.par test.pl # runs main.pl; @ARGV is 'test.pl'
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;
You can also use wildcard characters:
use PAR '/home/foo/*.par'; # loads all PAR files in that directory
This module lets you easily bundle a typical blib/ tree into a zip
file, called a Perl Archive, or PAR.
It supports loading XS modules by overriding DynaLoader bootstrapping 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/
Afterward, you can just use mymodule.par anywhere in your @INC,
use PAR, and it will Just Work.
For convenience, you can set the PERL5OPT environment variable to
-MPAR to enable PAR processing globally (the overhead is small
if not used); setting it to -MPAR=/path/to/mylib.par will load a
specific PAR file. Alternatively, consider using the par.pl utility
bundled with this module, or using the self-contained parl utility
on machines without PAR.pm installed.
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.
Settings in META.yml packed inside the PAR file may affect PAR's
operation. For example, pp provides the -C (--clean) option
to control the default behavior of temporary file creation.
Currently, pp-generated PAR files may attach four PAR-specific attributes in META.yml:
par:
clean: 0 # default value of PAR_CLEAN
signature: '' # key ID of the SIGNATURE file
verbatim: 0 # was packed prerequisite's PODs preserved?
version: x.xx # PAR.pm version that generated this PAR
User-defined environment variables, like PAR_CLEAN, always overrides the ones set in META.yml. The algorithm for generating caching/temporary directory is as follows:
If PAR_GLOBAL_TEMP is specified, use it as the cache directory for extracted libraries, and do not clean it up after execution.
If PAR_GLOBAL_TEMP is not set, but PAR_CLEAN is specified, set
PAR_GLOBAL_TEMP to TEMP/par-USER/temp-PID/, cleaning it
after execution.
If both are not set, use TEMP/par-USER/cache-HASH/ as the
PAR_GLOBAL_TEMP, reusing any existing files inside.
Here is a description of the variables the previous paths.
TEMP is a temporary directory, which can be set via
$ENV{PAR_GLOBAL_TMPDIR},
$ENV{TMPDIR}, $ENV{TEMP} or $ENV{TMP}, in that order of priority.
If none of those are set, C:\TEMP, /tmp are checked. If neither
of them exists, . is used.
USER is the user name, or SYSTEM if none can be found. On Win32,
this is $Win32::LoginName. On Unix, this is $ENV{USERNAME> or
$ENV{USER}.
PID is the process ID. Forked children use the parent's PID.
HASH is a crypto-hash of the entire par file or executable,
calculated at creation time. This value can be overloaded with pp's
--tempdir parameter.
By default, PAR strips POD sections from bundled modules. In case
that causes trouble, you can turn this off by setting the
environment variable PAR_VERBATIM to 1.
the PAR::Tutorial manpage, the PAR::FAQ manpage
par.pl, parl, pp
the Archive::Zip manpage, require in the perlfunc manpage
the ex::lib::zip manpage, the Acme::use::strict::with::pride manpage
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.
Uri Guttman for suggesting read_file and par_handle interfaces.
Antti Lankila for making me implement the self-contained executable
options via par.pl -O.
See the AUTHORS file in the distribution for a list of people who have sent helpful patches, ideas or comments.
Audrey Tang <cpan@audreyt.org>
http://par.perl.org/ is the official PAR website. You can write to the mailing list at <par@perl.org>, or send an empty mail to <par-subscribe@perl.org> to participate in the discussion.
Please submit bug reports to <bug-par@rt.cpan.org>. If you need support, however, joining the <par@perl.org> mailing list is preferred.
Copyright 2002, 2003, 2004, 2005, 2006 by Audrey Tang <cpan@audreyt.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.