Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PAR::Dist(3)	      User Contributed Perl Documentation	  PAR::Dist(3)

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.

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

perl v5.24.1			  2012-10-14			  PAR::Dist(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | FUNCTIONS | SEE ALSO | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PAR::Dist&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help