Dist(3)

NAME

       PAR::Dist - Create and manipulate PAR distributions

VERSION

       This document describes version 0.07 of PAR::Dist, released January 1,
       2004.

SYNOPSIS

       As a shell command:

           % perl -MPAR::Dist -eblib_to_par

       In programs:

           use PAR::Dist;

           my $dist = blib_to_par();   # make a PAR file using ./blib/
           install_par($dist);         # install it into the system
           uninstall_par($dist);       # uninstall it from the system
           sign_par($dist);            # sign it using Module::Signature
           verify_par($dist);          # verify it using Module::Signature

           install_par("http://foo.com/DBI-1.37-MSWin32-5.8.0.par"); # works too
           install_par("http://foo.com/DBI-1.37"); # auto-appends archname + perlver
           install_par("cpan://AUTRIJUS/PAR-0.73"); # uses CPAN author directory

DESCRIPTION

       This module creates and manipulates PAR distributions.  They are archi-
       tecture-specific PAR files, containing everything under blib/ of CPAN
       distributions after their "make" or "Build" stage, a META.yml describ-
       ing metadata of the original CPAN distribution, and a MANIFEST detail-
       ing all files within it.  Digitally signed PAR distributions will also
       contain a SIGNATURE file.

       The naming convention for such distributions is:

           $NAME-$VERSION-$ARCH-$PERL_VERSION.par

       For example, "PAR-Dist-0.01-i386-freebsd-5.8.0.par" corresponds to the
       0.01 release of "PAR-Dist" on CPAN, built for perl 5.8.0 running on
       "i386-freebsd".

FUNCTIONS

       Five functions are exported by default.  They can take either a hash of
       named arguments, a single argument (taken as $path by "blib_to_par" and
       $dist by other functions), or no arguments (in which case the first PAR
       file in the current directory is used).

       Therefore, under a directory containing only a single test.par, all
       invocations below are equivalent:

           % perl -MPAR::Dist -e"install_par( dist => 'test.par' )"
           % perl -MPAR::Dist -e"install_par( 'test.par' )"
           % perl -MPAR::Dist -einstall_par;

       If $dist resembles a URL, "LWP::Simple::mirror" is called to mirror it
       locally under $ENV{PAR_TEMP} (or "$TEMP/par/" if unspecified), and the
       function will act on the fetched local file instead.  If the URL begins
       with "cpan://AUTHOR/", it will be expanded automatically to the
       author's CPAN directory (e.g. "http://www.cpan.org/mod-
       ules/by-authors/id/A/AU/AUTHOR/").

       If $dist does not have a file extension beginning with a letter or
       underscore, a dash and $suffix ($ARCH-$PERL_VERSION.par by default)
       will be appended to it.

       blib_to_par

       Builds a PAR distribution from the blib/ subdirectory under $path, or
       under the current directory if unspecified.  If blib/ does not exist,
       it automatically runs Build, make, Build.PL or Makefile.PL to create
       it.

       Returns the filename or the generated PAR distribution.

       install_par

       Installs a PAR distribution into the system, using "ExtU-
       tils::Install::install_default".

       uninstall_par

       Uninstalls all previously installed contents of a PAR distribution,
       using "ExtUtils::Install::uninstall".

       sign_par

       Digitally sign a PAR distribution using "gpg" or Crypt::OpenPGP, via
       Module::Signature.

       verify_par

       Verify the digital signature of a PAR distribution using "gpg" or
       Crypt::OpenPGP, via Module::Signature.

       Returns a boolean value indicating whether verification passed; $!  is
       set to the return code of "Module::Signature::verify".

SEE ALSO

       PAR, ExtUtils::Install, Module::Signature, LWP::Simple

AUTHORS

       Autrijus Tang <autrijus@autrijus.org>

       PAR has a mailing list, <par@perl.org>, that you can write to; send an
       empty mail to <par-subscribe@perl.org> to join the list and participate
       in the discussion.

       Please send bug reports to <bug-par@rt.cpan.org>.

COPYRIGHT

       Copyright 2003, 2004 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>

perl v5.8.6                       2003-12-31                      PAR::Dist(3)