=head1 NAME
PAR::Dist - Create and manipulate PAR distributions
=head1 VERSION
This document describes version 0.29 of PAR::Dist, released Feb  6, 2008.
=head1 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-Packer-0.975"); # uses CPAN author directory
=head1 DESCRIPTION
This module creates and manipulates I<PAR distributions>.  They are
architecture-specific B<PAR> files, containing everything under F<blib/>
of CPAN distributions after their C<make> or C<Build> stage, a
F<META.yml> describing metadata of the original CPAN distribution, 
and a F<MANIFEST> detailing all files within it.  Digitally signed PAR
distributions will also contain a F<SIGNATURE> file.
The naming convention for such distributions is:
$NAME-$VERSION-$ARCH-$PERL_VERSION.par
For example, C<PAR-Dist-0.01-i386-freebsd-5.8.0.par> corresponds to the
0.01 release of C<PAR-Dist> on CPAN, built for perl 5.8.0 running on
C<i386-freebsd>.
=head1 FUNCTIONS
Several functions are exported by default.  Unless otherwise noted,
they can take either a hash of
named arguments, a single argument (taken as C<$path> by C<blib_to_par>
and C<$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 F<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 C<$dist> resembles a URL, C<LWP::Simple::mirror> is called to mirror it
locally under C<$ENV{PAR_TEMP}> (or C<$TEMP/par/> if unspecified), and the
function will act on the fetched local file instead.  If the URL begins
with C<cpan://AUTHOR/>, it will be expanded automatically to the author's CPAN
directory (e.g. C<http://www.cpan.org/modules/by-authors/id/A/AU/AUTHOR/>).
If C<$dist> does not have a file extension beginning with a letter or
underscore, a dash and C<$suffix> ($ARCH-$PERL_VERSION.par by default)
will be appended to it.
=head2 blib_to_par
Takes key/value pairs as parameters or a single parameter indicating the
path that contains the F<blib/> subdirectory.
Builds a PAR distribution from the F<blib/> subdirectory under C<path>, or
under the current directory if unspecified.  If F<blib/> does not exist,
it automatically runs F<Build>, F<make>, F<Build.PL> or F<Makefile.PL> to
create it.
Returns the filename or the generated PAR distribution.
Valid parameters are:
=over 2
=item path
Sets the path which contains the F<blib/> subdirectory from which the PAR
distribution will be generated.
=item name, version, suffix
These attributes set the name, version and platform specific suffix
of the distribution. Name and version can be automatically
determined from the distributions F<META.yml> or F<Makefile.PL> files.
The suffix is generated from your architecture name and your version of
perl by default.
=item dist
The output filename for the PAR distribution.
=back
=cut
# don't use 'my $foo ... if ...' it creates a static variable!
# could not determine name or version. Error.
=head2 install_par
Installs a PAR distribution into the system, using
C<ExtUtils::Install::install_default>.
Valid parameters are:
=over 2
=item dist
The .par file to install. The heuristics outlined in the B<FUNCTIONS>
section above apply.
=item prefix
This string will be prepended to all installation paths.
If it isn't specified, the environment variable
C<PERL_INSTALL_ROOT> is used as a prefix.
=back
Additionally, you can use several parameters to change the default
installation destinations. You don't usually have to worry about this
unless you are installing into a user-local directory.
The following section outlines the parameter names and default settings:
Parameter         From          To
inst_lib          blib/lib      $Config{installsitelib} (*)
inst_archlib      blib/arch     $Config{installsitearch}
inst_script       blib/script   $Config{installscript}
inst_bin          blib/bin      $Config{installbin}
inst_man1dir      blib/man1     $Config{installman1dir}
inst_man3dir      blib/man3     $Config{installman3dir}
packlist_read                   $Config{sitearchexp}/auto/$name/.packlist
packlist_write                  $Config{installsitearch}/auto/$name/.packlist
The C<packlist_write> parameter is used to control where the F<.packlist>
file is written to. (Necessary for uninstallation.)
The C<packlist_read> parameter specifies a .packlist file to merge in if
it exists. By setting any of the above installation targets to C<undef>,
you can remove that target altogether. For example, passing
C<inst_man1dir => undef, inst_man3dir => undef> means that the contained
manual pages won't be installed. This is not available for the packlists.
Finally, you may specify a C<custom_targets> parameter. Its value should be
a reference to a hash of custom installation targets such as
custom_targets => { 'blib/my_data' => '/some/path/my_data' }
You can use this to install the F<.par> archives contents to arbitrary
locations.
If only a single parameter is given, it is treated as the C<dist>
parameter.
=cut
=head2 uninstall_par
Uninstalls all previously installed contents of a PAR distribution,
using C<ExtUtils::Install::uninstall>.
Takes almost the same parameters as C<install_par>, but naturally,
the installation target parameters do not apply. The only exception
to this is the C<packlist_read> parameter which specifies the
F<.packlist> file to read the list of installed files from.
It defaults to C<$Config::Config{installsitearch}/auto/$name/.packlist>.
=cut
# Returns the default installation target as used by
# ExtUtils::Install::install(). First parameter should be the base
# directory containing the blib/ we're installing from.
# Second parameter should be the name of the distribution for the packlist
# paths. Third parameter may be a hash reference with user defined keys for
# the target hash. In fact, any contents that do not start with 'inst_' are
# skipped.
# accepted sources (and user overrides)
# default targets
# Included for future support for ${flavour}perl external lib installation
#    if ($Config::Config{flavour_perl}) {
#        my $ext = File::Spec->catdir($dir, 'blib', 'ext');
#        # from => to
#        $sources{inst_external_lib}    = File::Spec->catdir($ext, 'lib');
#        $sources{inst_external_bin}    = File::Spec->catdir($ext, 'bin');
#        $sources{inst_external_include} = File::Spec->catdir($ext, 'include');
#        $sources{inst_external_src}    = File::Spec->catdir($ext, 'src');
#        $target->{ $sources{inst_external_lib} }     = $Config::Config{flavour_install_lib};
#        $target->{ $sources{inst_external_bin} }     = $Config::Config{flavour_install_bin};
#        $target->{ $sources{inst_external_include} } = $Config::Config{flavour_install_include};
#        $target->{ $sources{inst_external_src} }     = $Config::Config{flavour_install_src};
#    }
# insert user overrides
# undef means "remove"
# overwrite stuff, don't let the user create new entries
=head2 sign_par
Digitally sign a PAR distribution using C<gpg> or B<Crypt::OpenPGP>,
via B<Module::Signature>.
=cut
=head2 verify_par
Verify the digital signature of a PAR distribution using C<gpg> or
B<Crypt::OpenPGP>, via B<Module::Signature>.
Returns a boolean value indicating whether verification passed; C<$!>
is set to the return code of C<Module::Signature::verify>.
=cut
=head2 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 C<foo.par>, C<bar.par> and C<baz.par>
into the distribution C<foo.par>. C<foo.par> will be overwritten!
The original META.yml of C<foo.par> is retained.
=cut
# parameter checking
# The unzipping will change directories. Remember old dir.
# Unzip the base par to a temp. dir.
# move the META.yml to the (main) temp. dir.
# delete (incorrect) MANIFEST
# extract additional pars and merge    
# restore original directory because the par path
# might have been relative!
# I hate File::Find
# And I hate writing portable code, too.
# merge directory structure
# merge files
# delete (copied) MANIFEST and META.yml
=head2 remove_man
Remove the man pages from a PAR distribution. Takes one named
parameter: I<dist> which should be the name (and path) of the
PAR distribution file. The calling conventions outlined in
the C<FUNCTIONS> section above apply.
The PAR archive will be
extracted, stripped of all C<man\d?> and C<html> subdirectories
and then repackaged into the original file.
=cut
# parameter checking
# The unzipping will change directories. Remember old dir.
# Unzip the base par to a temp. dir.
# move the META.yml to the (main) temp. dir.
# delete (incorrect) MANIFEST
=head2 get_meta
Opens a PAR archive and extracts the contained META.yml file.
Returns the META.yml file as a string.
Takes one named parameter: I<dist>. If only one parameter is
passed, it is treated as the I<dist> parameter. (Have a look
at the description in the C<FUNCTIONS> section above.)
Returns undef if no PAR archive or no META.yml within the
archive were found.
=cut
# The unzipping will change directories. Remember old dir.
# Unzip the base par to a temp. dir.
# Try fast unzipping first
# Then slow unzipping
# Then fall back to the system
# This sub munges the arguments to most of the PAR::Dist functions
# into a hash. On the way, it downloads PAR archives as necessary, etc.
# default to the first .par in the CWD
# single argument => it's a distribution file name or URL
# If we are installing from an URL, we want to munge the
# distribution name so that it is in form "Module-Name"
# @elems is name, version, arch, perlversion
# append suffix if there is none
# download if it's an URL
# Download PAR archive, but only if necessary (mirror!)
=head2 parse_dist_name
First argument must be a distribution file name. The file name
is parsed into I<distribution name>, I<distribution version>,
I<architecture name>, and I<perl version>.
Returns the results as a list in the above order.
If any or all of the above cannot be determined, returns undef instead
of the undetermined elements.
Supported formats are:
Math-Symbolic-0.502-x86_64-linux-gnu-thread-multi-5.8.7
Math-Symbolic-0.502
The ".tar.gz" or ".par" extensions as well as any
preceding paths are stripped before parsing. Starting with C<PAR::Dist>
0.22, versions containing a preceding C<v> are parsed correctly.
This function is not exported by default.
=cut
# (assumes an arch string doesnt start with a version...)
=head2 generate_blib_stub
Creates a F<blib/lib> subdirectory in the current directory
and prepares a F<META.yml> with meta information for a
new PAR distribution. First argument should be the name of the
PAR distribution in a format understood by C<parse_dist_name()>.
Alternatively, named arguments resembling those of
C<blib_to_par> are accepted.
After running C<generate_blib_stub> and injecting files into
the F<blib> directory, you can create a PAR distribution
using C<blib_to_par>.
This function is useful for creating custom PAR distributions
from scratch. (I.e. not from an unpacked CPAN distribution)
Example:
use PAR::Dist;
use File::Copy 'copy';
generate_blib_stub(
name => 'MyApp', version => '1.00'
);
copy('MyApp.pm', 'blib/lib/MyApp.pm');
blib_to_par(); # generates the .par file!
C<generate_blib_stub> will not overwrite existing files.
=cut
=head2 contains_binaries
This function is not exported by default.
Opens a PAR archive tries to determine whether that archive
contains platform-specific binary code.
Takes one named parameter: I<dist>. If only one parameter is
passed, it is treated as the I<dist> parameter. (Have a look
at the description in the C<FUNCTIONS> section above.)
Throws a fatal error if the PAR archive could not be found.
Returns one if the PAR was found to contain binary code
and zero otherwise.
=cut
# The unzipping will change directories. Remember old dir.
# Unzip the base par to a temp. dir.
=head1 SEE ALSO
L<PAR>, L<ExtUtils::Install>, L<Module::Signature>, L<LWP::Simple>
=head1 AUTHORS
Audrey Tang E<lt>cpan@audreyt.orgE<gt> 2003-2007
Steffen Mueller E<lt>smueller@cpan.orgE<gt> 2005-2007
PAR has a mailing list, E<lt>par@perl.orgE<gt>, that you can write to;
send an empty mail to E<lt>par-subscribe@perl.orgE<gt> to join the list
and participate in the discussion.
Please send bug reports to E<lt>bug-par@rt.cpan.orgE<gt>.
=head1 COPYRIGHT
Copyright 2003-2007 by Audrey Tang E<lt>autrijus@autrijus.orgE<gt>.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See L<http://www.perl.com/perl/misc/Artistic.html>
=cut