Ubuntu Manpage: PAR - Perl Archive Toolkit

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 @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_GLOBAL_CLEAN is specified, set PAR_GLOBAL_TEMP to
"TEMP/par-USERHEX/temp-PID/", cleaning it after execution.

• If both are not set, use "TEMP/par-USERHEX/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.

• USERHEX is derived from 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}. Encode the raw bytes of the user
name each as two hex digits to obtain USERHEX.

• 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..."

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>

       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 LICENSE.

perl v5.36.0                                       2023-11-02                                           PAR(3pm)