PAR::Dist(3) User Contributed Perl Documentation PAR::Dist(3)NAMEPAR::Dist - Create and manipulate PAR distributions
VERSION
This document describes version 0.25 of PAR::Dist, released Jul 29,
2007.
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
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
Several functions are exported by default. Unless otherwise noted,
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
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 and 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 "ExtU‐
tils::Install::install_default".
Valid parameters are:
dist
The .par file to install. The heuristics outlined in the FUNCTIONS
section above apply.
prefix
This string will be prepended to all installation paths. If it isn't
specified, the environment variable "PERL_INSTALL_ROOT" is used as a
prefix.
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 "packlist_write" parameter is used to control where the .packlist
file is written to. (Necessary for uninstallation.) The "pack‐
list_read" parameter specifies a .packlist file to merge in if it
exists.
Finally, you may specify a "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 .par archives contents to arbitrary
locations.
If only a single parameter is given, it is treated as the "dist" param‐
eter.
uninstall_par
Uninstalls all previously installed contents of a PAR distribution,
using "ExtUtils::Install::uninstall".
Takes almost the same parameters as "install_par", but naturally, the
installation target parameters do not apply. The only exception to this
is the "packlist_read" parameter which specifies the .packlist file to
read the list of installed files from. It defaults to "$Config::Con‐
fig{installsitearch}/auto/$name/.packlist".
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. Takes one named parame‐
ter: dist which should be the name (and path) of the PAR distribution
file. The calling conventions outlined in the "FUNCTIONS" section above
apply.
The PAR archive will be extracted, stripped of all "man\d?" and "html"
subdirectories and then repackaged into the original file.
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: dist. If only one parameter is passed, it is
treated as the dist parameter. (Have a look at the description in the
"FUNCTIONS" section above.)
Returns undef if no PAR archive or no META.yml within the archive were
found.
parse_dist_name
First argument must be a distribution file name. The file name is
parsed into distribution name, distribution version, architecture name,
and 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 "PAR::Dist" 0.22, versions con‐
taining a preceding "v" are parsed correctly.
This function is not exported by default.
generate_blib_stub
Creates a blib/lib subdirectory in the current directory and prepares a
META.yml with meta information for a new PAR distribution. First argu‐
ment should be the name of the PAR distribution in a format understood
by "parse_dist_name()". Alternatively, named arguments resembling
those of "blib_to_par" are accepted.
After running "generate_blib_stub" and injecting files into the blib
directory, you can create a PAR distribution using "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!
"generate_blib_stub" will not overwrite existing files.
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: dist. If only one parameter is passed, it is
treated as the dist parameter. (Have a look at the description in the
"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 other‐
wise.
SEE ALSO
PAR, ExtUtils::Install, Module::Signature, LWP::Simple
AUTHORS
Audrey Tang <cpan@audreyt.org> 2003-2007
Steffen Mueller <smueller@cpan.org> 2005-2007
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-2007 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>
perl v5.8.8 2007-07-29 PAR::Dist(3)
