☺唐鳳☻ > PAR > PAR

Download:
PAR-0.90.tar.gz

Dependencies

Annotate this POD (1)

CPAN RT

New  7
Open  13
Stalled  3
View/Report Bugs
Module Version: 0.90   Source   Latest Release: PAR-1.007

NAME ^

PAR - Perl Archive Toolkit

VERSION ^

This document describes version 0.90 of PAR, released November 25, 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 specific PAR file. Alternatively, consider using the par.pl utility bundled 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 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_CLEAN, always overrides the ones set in META.yml. The algorithm for generating caching/temporary directory is as follows:

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 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 ^

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-subscribe@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@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

syntax highlighting: