NAME

PAR::Dist - Create and manipulate PAR distributions

VERSION

This document describes version 0.11 of PAR::Dist, released Jul 21, 2006.

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://SMUELLER/PAR-0.91"); # uses CPAN author directory

DESCRIPTION

This module creates and manipulates PAR distributions. They are architecture-specific PAR files, containing everything under blib/ of CPAN distributions after their make or Build stage, a META.yml describing metadata of the original CPAN distribution, and a MANIFEST detailing 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/modules/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

Takes key/value pairs as parameters or a single parameter indicating the path that contains the blib/ subdirectory.

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.

Valid parameters are:

path

Sets the path which contains the blib/ subdirectory from which the PAR distribution will be generated.

name, version, suffix

These attributes set the name, version platform specific suffix of the distribution. Name and version can be automatically determined from the distributions META.yml or Makefile.PL files.

The suffix is generated from your architecture name and your version of perl by default.

dist

The output filename for the PAR distribution.

install_par

Installs a PAR distribution into the system, using ExtUtils::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.

merge_par

Merge two or more PAR distributions into one. First argument must be the name of the distribution you want to merge all others into. Any following arguments will be interpreted as the file names of further PAR distributions to merge into the first one.

  merge_par('foo.par', 'bar.par', 'baz.par')

This will merge the distributions foo.par, bar.par and baz.par into the distribution foo.par. foo.par will be overwritten! The original META.yml of foo.par is retained.

remove_man

Remove the man pages from a PAR distribution. First argument must be the name (and path) of the PAR distribution file. It will be extracted, stripped of all man\d? and html subdirectories and then repackaged into the original file.

SEE ALSO

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

AUTHORS

Audrey Tang <cpan@audreyt.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, 2006 by Audrey 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

cpanm PAR::Dist

perl -MCPAN -e shell
install PAR::Dist