/ 
PAR-0.06
River stage two • 7 direct dependents • 14 total dependents
/ PAR

NAME

PAR - Perl Archive

VERSION

This document describes version 0.06 of PAR, released October 16, 2002.

SYNOPSIS

(If you want to make an executable that contains all module, scripts and data files, please consult par.pl instead.)

Following examples assume a foo.par file in Zip format; support for compressed gzip (*.tgz) format is planned.

To use Hello.pm, lib/Hello.pm or lib/arch/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

Run test.pl or script/test.pl from foo.par:

% perl -MPAR foo.par test.pl	# only when $0 ends in '.par'
% perl -MPAR foo.par		# looks for 'main.pl' by default

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;

DESCRIPTION

This module let you easily bundle a blib/ tree into a zip file, called a Perl Archive, or PAR.

To generate a .par file, all you have to do is compress a lib/ tree containing modules, e.g.:

% perl Makefile.PL
% make
% cd blib
% zip -r mymodule.par lib/

Afterwards, you can just use mymodule.par anywhere in your @INC, use PAR, and it would 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.

Please see "SYNOPSIS" for most typical use cases.

NOTES

For Perl versions without PerlIO support, the IO::Scalar module is needed to support __DATA__ sections in script and modules inside a PAR file.

If you choose to compile script/par.pl with perlcc, it will automatically include the correct module (PerlIO::scalar or IO::Scalar) if you have it installed.

SEE ALSO

par.pl

Archive::Zip, "require" in perlfunc

ex::lib::zip, Acme::use::strict::with::pride

PerlIO::scalar, IO::Scalar

ACKNOWLEDGMENTS

Nicholas Clark for pointing out the mad source filter hook within the (also mad) coderef @INC hook.

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.

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

COPYRIGHT

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