.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PAR::Dist 3pm" .TH PAR::Dist 3pm "2011-11-05" "perl v5.12.4" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PAR::Dist \- Create and manipulate PAR distributions .SH "VERSION" .IX Header "VERSION" This document describes version 0.47 of PAR::Dist, released November 29, 2009. .SH "SYNOPSIS" .IX Header "SYNOPSIS" As a shell command: .PP .Vb 1 \& % perl \-MPAR::Dist \-eblib_to_par .Ve .PP In programs: .PP .Vb 1 \& 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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module creates and manipulates \fI\s-1PAR\s0 distributions\fR. They are architecture-specific \fB\s-1PAR\s0\fR files, containing everything under \fIblib/\fR of \s-1CPAN\s0 distributions after their \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`Build\*(C'\fR stage, a \&\fI\s-1META\s0.yml\fR describing metadata of the original \s-1CPAN\s0 distribution, and a \fI\s-1MANIFEST\s0\fR detailing all files within it. Digitally signed \s-1PAR\s0 distributions will also contain a \fI\s-1SIGNATURE\s0\fR file. .PP The naming convention for such distributions is: .PP .Vb 1 \& $NAME\-$VERSION\-$ARCH\-$PERL_VERSION.par .Ve .PP For example, \f(CW\*(C`PAR\-Dist\-0.01\-i386\-freebsd\-5.8.0.par\*(C'\fR corresponds to the 0.01 release of \f(CW\*(C`PAR\-Dist\*(C'\fR on \s-1CPAN\s0, built for perl 5.8.0 running on \&\f(CW\*(C`i386\-freebsd\*(C'\fR. .SH "FUNCTIONS" .IX Header "FUNCTIONS" Several functions are exported by default. Unless otherwise noted, they can take either a hash of named arguments, a single argument (taken as \f(CW$path\fR by \f(CW\*(C`blib_to_par\*(C'\fR and \f(CW$dist\fR by other functions), or no arguments (in which case the first \s-1PAR\s0 file in the current directory is used). .PP Therefore, under a directory containing only a single \fItest.par\fR, all invocations below are equivalent: .PP .Vb 3 \& % perl \-MPAR::Dist \-e"install_par( dist => \*(Aqtest.par\*(Aq )" \& % perl \-MPAR::Dist \-e"install_par( \*(Aqtest.par\*(Aq )" \& % perl \-MPAR::Dist \-einstall_par; .Ve .PP If \f(CW$dist\fR resembles a \s-1URL\s0, \f(CW\*(C`LWP::Simple::mirror\*(C'\fR is called to mirror it locally under \f(CW$ENV{PAR_TEMP}\fR (or \f(CW\*(C`$TEMP/par/\*(C'\fR if unspecified), and the function will act on the fetched local file instead. If the \s-1URL\s0 begins with \f(CW\*(C`cpan://AUTHOR/\*(C'\fR, it will be expanded automatically to the author's \s-1CPAN\s0 directory (e.g. \f(CW\*(C`http://www.cpan.org/modules/by\-authors/id/A/AU/AUTHOR/\*(C'\fR). .PP If \f(CW$dist\fR does not have a file extension beginning with a letter or underscore, a dash and \f(CW$suffix\fR ($ARCH\-$PERL_VERSION.par by default) will be appended to it. .SS "blib_to_par" .IX Subsection "blib_to_par" Takes key/value pairs as parameters or a single parameter indicating the path that contains the \fIblib/\fR subdirectory. .PP Builds a \s-1PAR\s0 distribution from the \fIblib/\fR subdirectory under \f(CW\*(C`path\*(C'\fR, or under the current directory if unspecified. If \fIblib/\fR does not exist, it automatically runs \fIBuild\fR, \fImake\fR, \fIBuild.PL\fR or \fIMakefile.PL\fR to create it. .PP Returns the filename of the generated \s-1PAR\s0 distribution. .PP Valid parameters are: .IP "path" 2 .IX Item "path" Sets the path which contains the \fIblib/\fR subdirectory from which the \s-1PAR\s0 distribution will be generated. .IP "name, version, suffix" 2 .IX Item "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 \fI\s-1META\s0.yml\fR or \fIMakefile.PL\fR files. .Sp The suffix is generated from your architecture name and your version of perl by default. .IP "dist" 2 .IX Item "dist" The output filename for the \s-1PAR\s0 distribution. .IP "quiet" 2 .IX Item "quiet" Set to true to suppress as much output as possible. .SS "install_par" .IX Subsection "install_par" Installs a \s-1PAR\s0 distribution into the system, using \&\f(CW\*(C`ExtUtils::Install::install_default\*(C'\fR. .PP If only a single parameter is given, it is treated as the value for the \&\f(CW\*(C`dist\*(C'\fR parameter. .PP Valid named parameters are: .IP "dist" 2 .IX Item "dist" The .par file to install. The heuristics outlined in the \fB\s-1FUNCTIONS\s0\fR section above apply. .IP "prefix" 2 .IX Item "prefix" This string will be prepended to all installation paths. If it isn't specified, the environment variable \&\f(CW\*(C`PERL_INSTALL_ROOT\*(C'\fR is used as a prefix. .IP "uninstall_shadows" 2 .IX Item "uninstall_shadows" This corresponds to the \f(CW\*(C`uninstall_shadows\*(C'\fR option of ExtUtils::Install. Quoting its manual: If \f(CW\*(C`uninstall_shadows\*(C'\fR is set to true, any differing versions throughout \f(CW@INC\fR will be uninstalled. This is \f(CW\*(C`make install UNINST=1\*(C'\fR. .IP "verbose" 2 .IX Item "verbose" This corresponds to the \f(CW\*(C`verbose\*(C'\fR option of ExtUtils::Install. According to its manual: If \f(CW\*(C`verbose\*(C'\fR is true, will print out each file removed. This is \f(CW\*(C`make install VERBINST=1\*(C'\fR. \&\f(CW\*(C`verbose\*(C'\fR values going up to 5 show increasingly more diagnostics output. .Sp Default verbosity for PAR::Dist is 1. .PP If you're just going to install into the running perl like everything else, you can stop reading the rest of this section now. .PP 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: .PP .Vb 9 \& 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 .Ve .PP The \f(CW\*(C`packlist_write\*(C'\fR parameter is used to control where the \fI.packlist\fR file is written to. (Necessary for uninstallation.) The \f(CW\*(C`packlist_read\*(C'\fR parameter specifies a .packlist file to merge in if it exists. By setting any of the above installation targets to \f(CW\*(C`undef\*(C'\fR, you can remove that target altogether. For example, passing \&\f(CW\*(C`inst_man1dir => undef, inst_man3dir => undef\*(C'\fR means that the contained manual pages won't be installed. This is not available for the packlists. .PP Again, the defaults will be the normal \fIsite\fR paths from \f(CW%Config\fR. .PP (*) If the \f(CW\*(C`.par\*(C'\fR's \fIinst_archlib\fR section (normally \f(CW\*(C`blib/arch\*(C'\fR) isn't empty, the code in \fIinst_lib\fR (normally \f(CW\*(C`blib/lib\*(C'\fR) is also installed into the \fIinst_archlib\fR path. This makes sense for \s-1XS\s0 modules. If, however, you override \f(CW\*(C`inst_lib\*(C'\fR, this automatic conversion is also overridden! You can use the named parameter \&\f(CW\*(C`auto_inst_lib_conversion => 1\*(C'\fR to re-enable the conversion for custom \fIinst_lib\fR's. .PP Finally, you may specify a \f(CW\*(C`custom_targets\*(C'\fR parameter. Its value should be a reference to a hash of custom installation targets such as .PP .Vb 1 \& custom_targets => { \*(Aqblib/my_data\*(Aq => \*(Aq/some/path/my_data\*(Aq } .Ve .PP You can use this to install the \fI.par\fR archives contents to arbitrary locations. .SS "uninstall_par" .IX Subsection "uninstall_par" Uninstalls all previously installed contents of a \s-1PAR\s0 distribution, using \f(CW\*(C`ExtUtils::Install::uninstall\*(C'\fR. .PP Takes almost the same parameters as \f(CW\*(C`install_par\*(C'\fR, but naturally, the installation target parameters do not apply. The only exception to this is the \f(CW\*(C`packlist_read\*(C'\fR parameter which specifies the \&\fI.packlist\fR file to read the list of installed files from. It defaults to \f(CW\*(C`$Config::Config{installsitearch}/auto/$name/.packlist\*(C'\fR. .PP Additionally, the \f(CW\*(C`uninstall_shadows\*(C'\fR parameter of \f(CW\*(C`install_par\*(C'\fR isn't available. .SS "sign_par" .IX Subsection "sign_par" Digitally sign a \s-1PAR\s0 distribution using \f(CW\*(C`gpg\*(C'\fR or \fBCrypt::OpenPGP\fR, via \fBModule::Signature\fR. .SS "verify_par" .IX Subsection "verify_par" Verify the digital signature of a \s-1PAR\s0 distribution using \f(CW\*(C`gpg\*(C'\fR or \&\fBCrypt::OpenPGP\fR, via \fBModule::Signature\fR. .PP Returns a boolean value indicating whether verification passed; \f(CW$!\fR is set to the return code of \f(CW\*(C`Module::Signature::verify\*(C'\fR. .SS "merge_par" .IX Subsection "merge_par" \&\fINote:\fR Since version 0.32 of PAR::Dist, this function requires a \s-1YAML\s0 reader. The order of precedence is: .PP .Vb 1 \& YAML:XS YAML YAML::Syck YAML::Tiny .Ve .PP Merges two or more \s-1PAR\s0 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 \s-1PAR\s0 distributions to merge into the first one. .PP .Vb 1 \& merge_par(\*(Aqfoo.par\*(Aq, \*(Aqbar.par\*(Aq, \*(Aqbaz.par\*(Aq) .Ve .PP This will merge the distributions \f(CW\*(C`foo.par\*(C'\fR, \f(CW\*(C`bar.par\*(C'\fR and \f(CW\*(C`baz.par\*(C'\fR into the distribution \f(CW\*(C`foo.par\*(C'\fR. \f(CW\*(C`foo.par\*(C'\fR will be overwritten! .PP The original \s-1META\s0.yml of \f(CW\*(C`foo.par\*(C'\fR is retained, but augmented with any \&\f(CW\*(C`provides\*(C'\fR, \f(CW\*(C`requires\*(C'\fR, \f(CW\*(C`recommends\*(C'\fR, \f(CW\*(C`build_requires\*(C'\fR, and \&\f(CW\*(C`configure_requires\*(C'\fR sections from the other \f(CW\*(C`.par\*(C'\fR files. .SS "remove_man" .IX Subsection "remove_man" Remove the man pages from a \s-1PAR\s0 distribution. Takes one named parameter: \fIdist\fR which should be the name (and path) of the \&\s-1PAR\s0 distribution file. The calling conventions outlined in the \f(CW\*(C`FUNCTIONS\*(C'\fR section above apply. .PP The \s-1PAR\s0 archive will be extracted, stripped of all \f(CW\*(C`man\ed?\*(C'\fR and \f(CW\*(C`html\*(C'\fR subdirectories and then repackaged into the original file. .SS "get_meta" .IX Subsection "get_meta" Opens a \s-1PAR\s0 archive and extracts the contained \s-1META\s0.yml file. Returns the \s-1META\s0.yml file as a string. .PP Takes one named parameter: \fIdist\fR. If only one parameter is passed, it is treated as the \fIdist\fR parameter. (Have a look at the description in the \f(CW\*(C`FUNCTIONS\*(C'\fR section above.) .PP Returns undef if no \s-1PAR\s0 archive or no \s-1META\s0.yml within the archive were found. .SS "parse_dist_name" .IX Subsection "parse_dist_name" First argument must be a distribution file name. The file name is parsed into \fIdistribution name\fR, \fIdistribution version\fR, \&\fIarchitecture name\fR, and \fIperl version\fR. .PP 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. .PP Supported formats are: .PP Math\-Symbolic\-0.502\-x86_64\-linux\-gnu\-thread\-multi\-5.8.7 .PP Math\-Symbolic\-0.502 .PP The \*(L".tar.gz\*(R" or \*(L".par\*(R" extensions as well as any preceding paths are stripped before parsing. Starting with \f(CW\*(C`PAR::Dist\*(C'\fR 0.22, versions containing a preceding \f(CW\*(C`v\*(C'\fR are parsed correctly. .PP This function is not exported by default. .SS "generate_blib_stub" .IX Subsection "generate_blib_stub" Creates a \fIblib/lib\fR subdirectory in the current directory and prepares a \fI\s-1META\s0.yml\fR with meta information for a new \s-1PAR\s0 distribution. First argument should be the name of the \&\s-1PAR\s0 distribution in a format understood by \f(CW\*(C`parse_dist_name()\*(C'\fR. Alternatively, named arguments resembling those of \&\f(CW\*(C`blib_to_par\*(C'\fR are accepted. .PP After running \f(CW\*(C`generate_blib_stub\*(C'\fR and injecting files into the \fIblib\fR directory, you can create a \s-1PAR\s0 distribution using \f(CW\*(C`blib_to_par\*(C'\fR. This function is useful for creating custom \s-1PAR\s0 distributions from scratch. (I.e. not from an unpacked \s-1CPAN\s0 distribution) Example: .PP .Vb 2 \& use PAR::Dist; \& use File::Copy \*(Aqcopy\*(Aq; \& \& generate_blib_stub( \& name => \*(AqMyApp\*(Aq, version => \*(Aq1.00\*(Aq \& ); \& copy(\*(AqMyApp.pm\*(Aq, \*(Aqblib/lib/MyApp.pm\*(Aq); \& blib_to_par(); # generates the .par file! .Ve .PP \&\f(CW\*(C`generate_blib_stub\*(C'\fR will not overwrite existing files. .SS "contains_binaries" .IX Subsection "contains_binaries" This function is not exported by default. .PP Opens a \s-1PAR\s0 archive tries to determine whether that archive contains platform-specific binary code. .PP Takes one named parameter: \fIdist\fR. If only one parameter is passed, it is treated as the \fIdist\fR parameter. (Have a look at the description in the \f(CW\*(C`FUNCTIONS\*(C'\fR section above.) .PP Throws a fatal error if the \s-1PAR\s0 archive could not be found. .PP Returns one if the \s-1PAR\s0 was found to contain binary code and zero otherwise. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1PAR\s0, ExtUtils::Install, Module::Signature, LWP::Simple .SH "AUTHORS" .IX Header "AUTHORS" Audrey Tang 2003\-2007 .PP Steffen Mueller 2005\-2011 .PP \&\s-1PAR\s0 has a mailing list, , that you can write to; send an empty mail to to join the list and participate in the discussion. .PP Please send bug reports to . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2003\-2011 by Audrey Tang . .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See