.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PAR 3"
.TH PAR 3 2024-03-04 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PAR \- Perl Archive Toolkit
.SH SYNOPSIS
.IX Header "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.)
.PP
Following examples assume a \fIfoo.par\fR file in Zip format.
.PP
To use \fIHello.pm\fR from \fI./foo.par\fR:
.PP
.Vb 2
\&    % perl \-MPAR=./foo.par \-MHello
\&    % perl \-MPAR=./foo \-MHello          # the .par part is optional
.Ve
.PP
Same thing, but search \fIfoo.par\fR in \f(CW@INC\fR:
.PP
.Vb 2
\&    % perl \-MPAR \-Ifoo.par \-MHello
\&    % perl \-MPAR \-Ifoo \-MHello          # ditto
.Ve
.PP
Following paths inside the PAR file are searched:
.PP
.Vb 6
\&    /lib/
\&    /arch/
\&    /i386\-freebsd/              # i.e. $Config{archname}
\&    /5.8.0/                     # i.e. $Config{version}
\&    /5.8.0/i386\-freebsd/        # both of the above
\&    /
.Ve
.PP
PAR files may also (recursively) contain other PAR files.
All files under following paths will be considered as PAR
files and searched as well:
.PP
.Vb 4
\&    /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/
.Ve
.PP
Run \fIscript/test.pl\fR or \fItest.pl\fR from \fIfoo.par\fR:
.PP
.Vb 1
\&    % perl \-MPAR foo.par test.pl        # only when $0 ends in \*(Aq.par\*(Aq
.Ve
.PP
However, if the \fI.par\fR archive contains either \fIscript/main.pl\fR or
\&\fImain.pl\fR, then it is used instead:
.PP
.Vb 1
\&    % perl \-MPAR foo.par test.pl        # runs main.pl; @ARGV is \*(Aqtest.pl\*(Aq
.Ve
.PP
Use in a program:
.PP
.Vb 2
\&    use PAR \*(Aqfoo.par\*(Aq;
\&    use Hello; # reads within foo.par
\&
\&    # PAR::read_file() returns a file inside any loaded PARs
\&    my $conf = PAR::read_file(\*(Aqdata/MyConfig.yaml\*(Aq);
\&
\&    # PAR::par_handle() returns an Archive::Zip handle
\&    my $zip = PAR::par_handle(\*(Aqfoo.par\*(Aq)
\&    my $src = $zip\->memberNamed(\*(Aqlib/Hello.pm\*(Aq)\->contents;
.Ve
.PP
You can also use wildcard characters:
.PP
.Vb 1
\&    use PAR \*(Aq/home/foo/*.par\*(Aq;  # loads all PAR files in that directory
.Ve
.PP
Since version 0.950, you can also use a different syntax for loading
\&\fI.par\fR archives:
.PP
.Vb 1
\&    use PAR { file => \*(Aqfoo.par\*(Aq }, { file => \*(Aqotherfile.par\*(Aq };
.Ve
.PP
Why? Because you can also do this:
.PP
.Vb 2
\&    use PAR { file => \*(Aqfoo.par, fallback => 1 };
\&    use Foo::Bar;
.Ve
.PP
Foo::Bar will be searched in the system libs first and loaded from \fIfoo.par\fR
if it wasn't found!
.PP
.Vb 1
\&    use PAR { file => \*(Aqfoo.par\*(Aq, run => \*(Aqmyscript\*(Aq };
.Ve
.PP
This will load \fIfoo.par\fR as usual and then execute the \fIscript/myscript\fR
file from the archive. Note that your program will not regain control. When
\&\fIscript/myscript\fR exits, so does your main program. To make this more useful,
you can defer this to runtime: (otherwise equivalent)
.PP
.Vb 2
\&    require PAR;
\&    PAR\->import( { file => \*(Aqfoo.par\*(Aq, run => \*(Aqmyscript\*(Aq } );
.Ve
.PP
If you have PAR::Repository::Client installed, you can do this:
.PP
.Vb 2
\&    use PAR { repository => \*(Aqhttp://foo/bar/\*(Aq };
\&    use Module; # not locally installed!
.Ve
.PP
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 \f(CW\*(C`install => 1\*(C'\fR option in the \f(CW\*(C`use PAR\*(C'\fR
line above, the distribution containing \f(CW\*(C`Module\*(C'\fR will be permanently
installed on your system. (\f(CW\*(C`use PAR { repository => \*(Aqhttp://foo/bar\*(Aq, install => 1 };\*(C'\fR)
.PP
Furthermore, there is an \f(CW\*(C`upgrade => 1\*(C'\fR 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.
.PP
Adding the \f(CW\*(C`dependencies => 1\*(C'\fR option will enable PAR::Repository::Client's
static dependency resolution (PAR::Repository::Client 0.23 and up).
.PP
Finally, you can combine the \f(CW\*(C`run\*(C'\fR and \f(CW\*(C`repository\*(C'\fR
options to run an application directly from a repository! (And you can add
the \f(CW\*(C`install\*(C'\fR option, too.)
.PP
.Vb 2
\&  use PAR { repository => \*(Aqhttp://foo/bar/\*(Aq, run => \*(Aqmy_app\*(Aq };
\&  # Will not reach this point as we executed my_app,
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module lets you use special zip files, called \fBP\fRerl \fBAr\fRchives, as
libraries from which Perl modules can be loaded.
.PP
It supports loading XS modules by overriding \fBDynaLoader\fR bootstrapping
methods; it writes shared object file to a temporary file at the time it
is needed.
.PP
A \fI.par\fR file is mostly a zip of the \fIblib/\fR directory after the build
process of a CPAN distribution. To generate a \fI.par\fR file yourself, all
you have to do is compress the modules under \fIarch/\fR and \fIlib/\fR, e.g.:
.PP
.Vb 4
\&    % perl Makefile.PL
\&    % make
\&    % cd blib
\&    % zip \-r mymodule.par arch/ lib/
.Ve
.PP
Afterward, you can just use \fImymodule.par\fR anywhere in your \f(CW@INC\fR,
use \fBPAR\fR, and it will Just Work. Support for generating \fI.par\fR files
is going to be in the next (beyond 0.2805) release of Module::Build.
.PP
For convenience, you can set the \f(CW\*(C`PERL5OPT\*(C'\fR environment variable to
\&\f(CW\*(C`\-MPAR\*(C'\fR to enable \f(CW\*(C`PAR\*(C'\fR processing globally (the overhead is small
if not used); setting it to \f(CW\*(C`\-MPAR=/path/to/mylib.par\*(C'\fR will load a
specific PAR file.  Alternatively, consider using the \fIpar.pl\fR utility
bundled with the PAR::Packer distribution, or using the
self-contained \fIparl\fR utility which is also distributed with PAR::Packer
on machines without PAR.pm installed.
.PP
Note that self-containing scripts and executables created with \fIpar.pl\fR
and \fIpp\fR may also be used as \fI.par\fR archives:
.PP
.Vb 3
\&    % 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
.Ve
.PP
Please see "SYNOPSIS" for most typical use cases.
.SH NOTES
.IX Header "NOTES"
Settings in \fIMETA.yml\fR packed inside the PAR file may affect PAR's
operation.  For example, \fIpp\fR provides the \f(CW\*(C`\-C\*(C'\fR (\f(CW\*(C`\-\-clean\*(C'\fR) option
to control the default behavior of temporary file creation.
.PP
Currently, \fIpp\fR\-generated PAR files may attach four PAR-specific
attributes in \fIMETA.yml\fR:
.PP
.Vb 5
\&    par:
\&      clean: 0          # default value of PAR_CLEAN
\&      signature: \*(Aq\*(Aq     # key ID of the SIGNATURE file
\&      verbatim: 0       # was packed prerequisite\*(Aqs PODs preserved?
\&      version: x.xx     # PAR.pm version that generated this PAR
.Ve
.PP
User-defined environment variables, like \fIPAR_GLOBAL_CLEAN\fR, always
overrides the ones set in \fIMETA.yml\fR.  The algorithm for generating
caching/temporary directory is as follows:
.IP \(bu 4
If \fIPAR_GLOBAL_TEMP\fR is specified, use it as the cache directory for
extracted libraries, and do not clean it up after execution.
.IP \(bu 4
If \fIPAR_GLOBAL_TEMP\fR is not set, but \fIPAR_GLOBAL_CLEAN\fR is specified, set
\&\fIPAR_GLOBAL_TEMP\fR to \f(CW\*(C`\fR\f(CITEMP\fR\f(CW/par\-\fR\f(CIUSERHEX\fR\f(CW/temp\-\fR\f(CIPID\fR\f(CW/\*(C'\fR, cleaning it
after execution.
.IP \(bu 4
If both are not set,  use \f(CW\*(C`\fR\f(CITEMP\fR\f(CW/par\-\fR\f(CIUSERHEX\fR\f(CW/cache\-\fR\f(CIHASH\fR\f(CW/\*(C'\fR as the
\&\fIPAR_GLOBAL_TEMP\fR, reusing any existing files inside.
.PP
Here is a description of the variables the previous paths.
.IP \(bu 4
\&\fITEMP\fR is a temporary directory, which can be set via
\&\f(CW$ENV{PAR_GLOBAL_TMPDIR}\fR,
\&\f(CW$ENV{TMPDIR}\fR, \f(CW$ENV{TEMPDIR}\fR, \f(CW$ENV{TEMP}\fR
or \f(CW$ENV{TMP}\fR, in that order of priority.
If none of those are set, \fIC:\eTEMP\fR, \fI/tmp\fR are checked.  If neither
of them exists, \fI.\fR is used.
.IP \(bu 4
\&\fIUSERHEX\fR is derived from the user name, or SYSTEM if none can be found.
On Win32, this is \f(CW$Win32::LoginName\fR.
On Unix, this is \f(CW$ENV{USERNAME}\fR or \f(CW$ENV{USER}\fR.
Encode the raw bytes of the user name each as two hex digits
to obtain \fIUSERHEX\fR.
.IP \(bu 4
\&\fIPID\fR is the process ID.  Forked children use the parent's PID.
.IP \(bu 4
\&\fIHASH\fR is a crypto-hash of the entire par file or executable,
calculated at creation time.  This value can be overloaded with \f(CW\*(C`pp\*(C'\fR's
\&\-\-tempdir parameter.
.PP
By default, PAR strips POD sections from bundled modules. In case
that causes trouble, you can turn this off by setting the
environment variable \f(CW\*(C`PAR_VERBATIM\*(C'\fR to \f(CW1\fR.
.SS "import options"
.IX Subsection "import options"
When you "use PAR {...}" or call PAR\->import({...}), the following
options are available.
.PP
.Vb 3
\&  PAR\->import({ file => \*(Aqfoo.par\*(Aq });
\&  # or
\&  PAR\->import({ repository => \*(Aqhttp://foo/bar/\*(Aq });
.Ve
.IP file 4
.IX Item "file"
The par filename.
.Sp
You must pass \fIone\fR option of either 'file' or 'repository'.
.IP repository 4
.IX Item "repository"
A par repository (exclusive of file)
.IP fallback 4
.IX Item "fallback"
Search the system \f(CW@INC\fR before the par.
.Sp
Off by default for loading \fI.par\fR files via \f(CW\*(C`file =\*(C'\fR ...>.
On by default for PAR repositories.
.Sp
To prefer loading modules from a repository over the locally
installed modules, you can load the repository as follows:
.Sp
.Vb 1
\&  use PAR { repository => \*(Aqhttp://foo/bar/\*(Aq, fallback => 0 };
.Ve
.IP run 4
.IX Item "run"
The name of a script to run in the par.  Exits when done.
.IP no_shlib_unpack 4
.IX Item "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 \f(CW$ENV\fR{PAR_TEMP} \fIbefore\fR 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..."
.SH "SEE ALSO"
.IX Header "SEE ALSO"
PAR::Tutorial, PAR::FAQ
.PP
The PAR::Packer distribution which contains the packaging utilities:
par.pl, parl, pp.
.PP
PAR::Dist for details on PAR distributions.
.PP
PAR::Repository::Client for details on accessing PAR repositories.
PAR::Repository for details on how to set up such a repository.
.PP
Archive::Zip, "require" in perlfunc
.PP
ex::lib::zip, Acme::use::strict::with::pride
.PP
Steffen Mueller has detailed slides on using PAR for application
deployment at <http://steffen\-mueller.net/talks/appdeployment/>.
.PP
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.
.SH ACKNOWLEDGMENTS
.IX Header "ACKNOWLEDGMENTS"
Nicholas Clark for pointing out the mad source filter hook within the
(also mad) coderef \f(CW@INC\fR hook, as well as (even madder) tricks one
can play with PerlIO to avoid source filtering.
.PP
Ton Hospel for convincing me to ditch the \f(CW\*(C`Filter::Simple\*(C'\fR
implementation.
.PP
Uri Guttman for suggesting \f(CW\*(C`read_file\*(C'\fR and \f(CW\*(C`par_handle\*(C'\fR interfaces.
.PP
Antti Lankila for making me implement the self-contained executable
options via \f(CW\*(C`par.pl \-O\*(C'\fR.
.PP
See the \fIAUTHORS\fR file in the distribution for a list of people who
have sent helpful patches, ideas or comments.
.SH AUTHORS
.IX Header "AUTHORS"
Audrey Tang <cpan@audreyt.org>
.PP
Steffen Mueller <smueller@cpan.org>
.PP
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.
Archives of the mailing list are available at
<https://www.mail\-archive.com/par@perl.org/> or <https://groups.google.com/g/perl.par>.
.PP
Please submit bug reports to <https://github.com/rschupp/PAR/issues>. If you need
support, however, joining the <par@perl.org> mailing list is
preferred.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2002\-2010 by Audrey Tang
<cpan@audreyt.org>.
Copyright 2005\-2010 by Steffen Mueller <smueller@cpan.org>
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See \fILICENSE\fR.