PAR::Dist - Create and manipulate PAR distributions

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

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

This module creates and manipulates PAR distributions. They are architecture-specific PAR files, containing everything under blib/ of CPAN distributions after their CWmake or CWBuild 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, CWPAR-Dist-0.01-i386-freebsd-5.8.0.par corresponds to the 0.01 release of CWPAR-Dist on CPAN, built for perl 5.8.0 running on CWi386-freebsd.

Five functions are exported by default. They can take either a hash of named arguments, a single argument (taken as CW$path by CWblib_to_par and CW$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 CW$dist resembles a URL, CWLWP::Simple::mirror is called to mirror it locally under CW$ENV{PAR_TEMP} (or CW$TEMP/par/ if unspecified), and the function will act on the fetched local file instead. If the URL begins with CWcpan://AUTHOR/, it will be expanded automatically to the author's CPAN directory (e.g. CWhttp://www.cpan.org/modules/by-authors/id/A/AU/AUTHOR/).

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

Builds a PAR distribution from the blib/ subdirectory under CW$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.

Installs a PAR distribution into the system, using CWExtUtils::Install::install_default.

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

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

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

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

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

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