/usr/man/cat.3/PAR.3.Z(/usr/man/cat.3/PAR.3.Z)
NAME
PAR - Perl Archive Toolkit
VERSION
This document describes version 0.87 of PAR, released January 31, 2005.
SYNOPSIS
(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
DESCRIPTION
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 spe-
cific PAR file. Alternatively, consider using the par.pl utility bun-
dled 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.
NOTES
Settings in META.yml packed inside the PAR file may affect PAR's opera-
tion. 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/tempo-
rary directory is as follows:
o If PAR_TEMP is specified, use it as the cache directory for
extracted libraries, and do not clean it up after execution.
o If PAR_TEMP is not set, but PAR_CLEAN is specified, set PAR_TEMP to
"TEMP\par-USER\temp-PID\", cleaning it after execution.
o If both are not set, use "TEMP\par-USER\temp-MTIME\" as the
PAR_TEMP, reusing any existing files inside. MTIME is the last-
modified timestamp of the program.
SEE ALSO
PAR::Tutorial, PAR::FAQ
par.pl, parl, pp
Archive::Zip, "require" in perlfunc
ex::lib::zip, Acme::use::strict::with::pride
ACKNOWLEDGMENTS
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" implementa-
tion.
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.
AUTHORS
Autrijus Tang <autrijus@autrijus.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-sub-
scribe@perl.org> to participate in the discussion.
Please submit bug reports to <bug-par@rt.cpan.org>.
COPYRIGHT
Copyright 2002, 2003, 2004, 2005 by Autrijus Tang <autrijus@autri-
jus.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>
perl v5.8.6 2005-01-30 PAR(3)
See also App::Packer::PAR(3): man 3 App::Packer::PAR
See also PAR::Dist(3): man 3 PAR::Dist
See also PAR::FAQ(3): man 3 PAR::FAQ
See also PAR::Filter(3): man 3 PAR::Filter
See also PAR::Filter::Bleach(3): man 3 PAR::Filter::Bleach
See also PAR::Filter::Bytecode(3): man 3 PAR::Filter::Bytecode
See also PAR::Filter::Obfuscate(3): man 3 PAR::Filter::Obfuscate
See also PAR::Filter::PatchContent(3): man 3 PAR::Filter::PatchContent
See also PAR::Filter::PodStrip(3): man 3 PAR::Filter::PodStrip
See also PAR::Heavy(3): man 3 PAR::Heavy
See also PAR::Packer(3): man 3 PAR::Packer
See also PAR::Tutorial(3): man 3 PAR::Tutorial
Man(1) output converted with
man2html