NAME¶
PAR::Dist - Create and manipulate PAR distributions
VERSION¶
This document describes version 0.47 of PAR::Dist, released November 29, 2009.
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
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¶
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/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 of 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.
- quiet
- Set to true to suppress as much output as possible.
install_par¶
Installs a PAR distribution into the system, using
"ExtUtils::Install::install_default".
If only a single parameter is given, it is treated as the value for the
"dist" parameter.
Valid named 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.
- uninstall_shadows
- This corresponds to the "uninstall_shadows"
option of ExtUtils::Install. Quoting its manual: If
"uninstall_shadows" is set to true, any differing versions
throughout @INC will be uninstalled. This is "make install
UNINST=1".
- verbose
- This corresponds to the "verbose" option of
ExtUtils::Install. According to its manual: If "verbose" is
true, will print out each file removed. This is "make install
VERBINST=1". "verbose" values going up to 5 show
increasingly more diagnostics output.
Default verbosity for PAR::Dist is 1.
If you're just going to install into the running perl like everything else, you
can stop reading the rest of this section now.
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
"packlist_read" parameter specifies a .packlist file to merge in if
it exists. By setting any of the above installation targets to
"undef", you can remove that target altogether. For example, passing
"inst_man1dir => undef, inst_man3dir => undef" means that the
contained manual pages won't be installed. This is not available for the
packlists.
Again, the defaults will be the normal
site paths from %Config.
(*) If the ".par"'s
inst_archlib section (normally
"blib/arch") isn't empty, the code in
inst_lib (normally
"blib/lib") is also installed into the
inst_archlib path.
This makes sense for XS modules. If, however, you override
"inst_lib", this automatic conversion is also overridden! You can
use the named parameter "auto_inst_lib_conversion => 1" to
re-enable the conversion for custom
inst_lib's.
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.
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::Config{installsitearch}/auto/$name/.packlist".
Additionally, the "uninstall_shadows" parameter of
"install_par" isn't available.
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¶
Note: Since version 0.32 of PAR::Dist, this function requires a YAML
reader. The order of precedence is:
YAML:XS YAML YAML::Syck YAML::Tiny
Merges 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, but augmented with any
"provides", "requires", "recommends",
"build_requires", and "configure_requires" sections from
the other ".par" files.
remove_man¶
Remove the man pages from a PAR distribution. Takes one named parameter:
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.
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 containing 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
argument 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 otherwise.
SEE ALSO¶
PAR, ExtUtils::Install, Module::Signature, LWP::Simple
AUTHORS¶
Audrey Tang <cpan@audreyt.org> 2003-2007
Steffen Mueller <smueller@cpan.org> 2005-2011
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-2011 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>