NAME¶
PAR - Perl Archive Toolkit
SYNOPSIS¶
(If you want to make an executable that contains all module, scripts and data
files, please consult the pp utility instead. pp used to be part of the PAR
distribution but is now shipped as part of the PAR::Packer distribution
instead.)
Following examples assume a
foo.par file in Zip format.
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
Since version 0.950, you can also use a different syntax for loading
.par
archives:
use PAR { file => 'foo.par' }, { file => 'otherfile.par' };
Why? Because you can also do this:
use PAR { file => 'foo.par, fallback => 1 };
use Foo::Bar;
Foo::Bar will be searched in the system libs first and loaded from
foo.par if it wasn't found!
use PAR { file => 'foo.par', run => 'myscript' };
This will load
foo.par as usual and then execute the
script/myscript file from the archive. Note that your program will not
regain control. When
script/myscript exits, so does your main program.
To make this more useful, you can defer this to runtime: (otherwise
equivalent)
require PAR;
PAR->import( { file => 'foo.par', run => 'myscript' } );
If you have PAR::Repository::Client installed, you can do this:
use PAR { repository => 'http://foo/bar/' };
use Module; # not locally installed!
And PAR will fetch any modules you don't have from the specified PAR repository.
For details on how this works, have a look at the SEE ALSO section below.
Instead of an URL or local path, you can construct an PAR::Repository::Client
object manually and pass that to PAR. If you specify the "install =>
1" option in the "use PAR" line above, the distribution
containing "Module" will be permanently installed on your system.
("use PAR { repository => '
http://foo/bar', install => 1 };")
Furthermore, there is an "upgrade => 1" option that checks for
upgrades in the repository in addition to installing. Please note that an
upgraded version of a module is only loaded on the next run of your
application.
Adding the "dependencies => 1" option will enable
PAR::Repository::Client's static dependency resolution
(PAR::Repository::Client 0.23 and up).
Finally, you can combine the "run" and "repository" options
to run an application directly from a repository! (And you can add the
"install" option, too.)
use PAR { repository => 'http://foo/bar/', run => 'my_app' };
# Will not reach this point as we executed my_app,
DESCRIPTION¶
This module lets you use special zip files, called
Perl
Archives,
as libraries from which Perl modules can be loaded.
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.
A
.par file is mostly a zip of the
blib/ directory after the build
process of a CPAN distribution. To generate a
.par file yourself, 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. Support for generating
.par files is
going to be in the next (beyond 0.2805) release of Module::Build.
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 the PAR::Packer distribution, or using the self-contained
parl utility which is also distributed with PAR::Packer 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 (see PAR::Packer)
% 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
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_GLOBAL_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{TEMPDIR}, $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.
import options¶
When you "use PAR {...}" or call PAR->import({...}), the following
options are available.
PAR->import({ file => 'foo.par' });
# or
PAR->import({ repository => 'http://foo/bar/' });
- file
- The par filename.
You must pass one option of either 'file' or 'repository'.
- repository
- A par repository (exclusive of file)
- fallback
- Search the system @INC before the par.
Off by default for loading .par files via "file =" ...>.
On by default for PAR repositories.
To prefer loading modules from a repository over the locally installed
modules, you can load the repository as follows:
use PAR { repository => 'http://foo/bar/', fallback => 0 };
- run
- The name of a script to run in the par. Exits when done.
- no_shlib_unpack
- Skip unpacking bundled dynamic libraries from shlib/$archname. The client
may have them installed, or you may wish to cache them yourself. In either
case, they must end up in the standard install location (such as
/usr/local/lib/) or in $ENV{PAR_TEMP} before you require the module
which needs them. If they are not accessible before you require the
dependent module, perl will die with a message such as "cannot open
shared object file..."
SEE ALSO¶
The PAR homepage at <
http://par.perl.org>.
PAR::Tutorial, PAR::FAQ (For a more current FAQ, refer to the homepage.)
The PAR::Packer distribution which contains the packaging utilities: par.pl,
parl, pp.
PAR::Dist for details on PAR distributions.
PAR::Repository::Client for details on accessing PAR repositories.
PAR::Repository for details on how to set up such a repository.
Archive::Zip, "require" in perlfunc
ex::lib::zip, Acme::use::strict::with::pride
Steffen Mueller has detailed slides on using PAR for application deployment at
http://steffen-mueller.net/talks/appdeployment/
<
http://steffen-mueller.net/talks/appdeployment/>.
PAR supports the prefork module. It declares various run-time dependencies so
you can use the prefork module to get streamlined processes in a forking
environment.
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"
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.
AUTHORS¶
Audrey Tang <cpan@audreyt.org>
Steffen Mueller <smueller@cpan.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¶
Copyright 2002-2010 by Audrey Tang <cpan@audreyt.org>. Copyright 2005-2010
by Steffen Mueller <smueller@cpan.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>