Unix/Linux Go Back    


CentOS 7.0 - man page for par::dist (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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.16.3				    2012-10-14				     PAR::Dist(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:35 PM.