NAME
PAR::Dist - Create and manipulate PAR distributions
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("https://foo.com/DBI-1.37-MSWin32-5.8.0.par"); # works too
install_par("https://foo.com/DBI-1.37"); # auto-appends archname + perlver
install_par("cpan:https://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:https://AUTHOR/
, it will be expanded automatically to the author's CPAN directory (e.g. https://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: Ifuninstall_shadows
is set to true, any differing versions throughout@INC
will be uninstalled. This ismake install UNINST=1
. - verbose
-
This corresponds to the
verbose
option of ExtUtils::Install. According to its manual: Ifverbose
is true, will print out each file removed. This ismake 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.
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 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 <[email protected]> 2003-2007
Steffen Mueller <[email protected]> 2005-2011
PAR has a mailing list, <[email protected]>, that you can write to; send an empty mail to <[email protected]> to join the list and participate in the discussion. Archives of the mailing list are available at <https://www.mail-archive.com/[email protected]/> or <https://groups.google.com/g/perl.par>.
Please send bug reports to <https://github.com/rschupp/PAR-Dist/issues>.
COPYRIGHT
Copyright 2003-2011 by Audrey Tang <[email protected]>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.