1PAR::Dist(3)          User Contributed Perl Documentation         PAR::Dist(3)
2
3
4

NAME

6       PAR::Dist - Create and manipulate PAR distributions
7

VERSION

9       This document describes version 0.47 of PAR::Dist, released November
10       29, 2009.
11

SYNOPSIS

13       As a shell command:
14
15           % perl -MPAR::Dist -eblib_to_par
16
17       In programs:
18
19           use PAR::Dist;
20
21           my $dist = blib_to_par(); # make a PAR file using ./blib/
22           install_par($dist);       # install it into the system
23           uninstall_par($dist);     # uninstall it from the system
24           sign_par($dist);          # sign it using Module::Signature
25           verify_par($dist);        # verify it using Module::Signature
26
27           install_par("http://foo.com/DBI-1.37-MSWin32-5.8.0.par"); # works too
28           install_par("http://foo.com/DBI-1.37"); # auto-appends archname + perlver
29           install_par("cpan://SMUELLER/PAR-Packer-0.975"); # uses CPAN author directory
30

DESCRIPTION

32       This module creates and manipulates PAR distributions.  They are
33       architecture-specific PAR files, containing everything under blib/ of
34       CPAN distributions after their "make" or "Build" stage, a META.yml
35       describing metadata of the original CPAN distribution, and a MANIFEST
36       detailing all files within it.  Digitally signed PAR distributions will
37       also contain a SIGNATURE file.
38
39       The naming convention for such distributions is:
40
41           $NAME-$VERSION-$ARCH-$PERL_VERSION.par
42
43       For example, "PAR-Dist-0.01-i386-freebsd-5.8.0.par" corresponds to the
44       0.01 release of "PAR-Dist" on CPAN, built for perl 5.8.0 running on
45       "i386-freebsd".
46

FUNCTIONS

48       Several functions are exported by default.  Unless otherwise noted,
49       they can take either a hash of named arguments, a single argument
50       (taken as $path by "blib_to_par" and $dist by other functions), or no
51       arguments (in which case the first PAR file in the current directory is
52       used).
53
54       Therefore, under a directory containing only a single test.par, all
55       invocations below are equivalent:
56
57           % perl -MPAR::Dist -e"install_par( dist => 'test.par' )"
58           % perl -MPAR::Dist -e"install_par( 'test.par' )"
59           % perl -MPAR::Dist -einstall_par;
60
61       If $dist resembles a URL, "LWP::Simple::mirror" is called to mirror it
62       locally under $ENV{PAR_TEMP} (or "$TEMP/par/" if unspecified), and the
63       function will act on the fetched local file instead.  If the URL begins
64       with "cpan://AUTHOR/", it will be expanded automatically to the
65       author's CPAN directory (e.g.
66       "http://www.cpan.org/modules/by-authors/id/A/AU/AUTHOR/").
67
68       If $dist does not have a file extension beginning with a letter or
69       underscore, a dash and $suffix ($ARCH-$PERL_VERSION.par by default)
70       will be appended to it.
71
72   blib_to_par
73       Takes key/value pairs as parameters or a single parameter indicating
74       the path that contains the blib/ subdirectory.
75
76       Builds a PAR distribution from the blib/ subdirectory under "path", or
77       under the current directory if unspecified.  If blib/ does not exist,
78       it automatically runs Build, make, Build.PL or Makefile.PL to create
79       it.
80
81       Returns the filename of the generated PAR distribution.
82
83       Valid parameters are:
84
85       path
86         Sets the path which contains the blib/ subdirectory from which the
87         PAR distribution will be generated.
88
89       name, version, suffix
90         These attributes set the name, version and platform specific suffix
91         of the distribution. Name and version can be automatically determined
92         from the distributions META.yml or Makefile.PL files.
93
94         The suffix is generated from your architecture name and your version
95         of perl by default.
96
97       dist
98         The output filename for the PAR distribution.
99
100       quiet
101         Set to true to suppress as much output as possible.
102
103   install_par
104       Installs a PAR distribution into the system, using
105       "ExtUtils::Install::install_default".
106
107       If only a single parameter is given, it is treated as the value for the
108       "dist" parameter.
109
110       Valid named parameters are:
111
112       dist
113         The .par file to install. The heuristics outlined in the FUNCTIONS
114         section above apply.
115
116       prefix
117         This string will be prepended to all installation paths.  If it isn't
118         specified, the environment variable "PERL_INSTALL_ROOT" is used as a
119         prefix.
120
121       uninstall_shadows
122         This corresponds to the "uninstall_shadows" option of
123         ExtUtils::Install. Quoting its manual: If "uninstall_shadows" is set
124         to true, any differing versions throughout @INC will be uninstalled.
125         This is "make install UNINST=1".
126
127       verbose
128         This corresponds to the "verbose" option of ExtUtils::Install.
129         According to its manual: If "verbose" is true, will print out each
130         file removed. This is "make install VERBINST=1".  "verbose" values
131         going up to 5 show increasingly more diagnostics output.
132
133         Default verbosity for PAR::Dist is 1.
134
135       If you're just going to install into the running perl like everything
136       else, you can stop reading the rest of this section now.
137
138       Additionally, you can use several parameters to change the default
139       installation destinations. You don't usually have to worry about this
140       unless you are installing into a user-local directory.  The following
141       section outlines the parameter names and default settings:
142
143         Parameter         From          To
144         inst_lib          blib/lib      $Config{installsitelib} (*)
145         inst_archlib      blib/arch     $Config{installsitearch}
146         inst_script       blib/script   $Config{installscript}
147         inst_bin          blib/bin      $Config{installbin}
148         inst_man1dir      blib/man1     $Config{installman1dir}
149         inst_man3dir      blib/man3     $Config{installman3dir}
150         packlist_read                   $Config{sitearchexp}/auto/$name/.packlist
151         packlist_write                  $Config{installsitearch}/auto/$name/.packlist
152
153       The "packlist_write" parameter is used to control where the .packlist
154       file is written to. (Necessary for uninstallation.)  The
155       "packlist_read" parameter specifies a .packlist file to merge in if it
156       exists. By setting any of the above installation targets to "undef",
157       you can remove that target altogether. For example, passing
158       "inst_man1dir => undef, inst_man3dir => undef" means that the contained
159       manual pages won't be installed. This is not available for the
160       packlists.
161
162       Again, the defaults will be the normal site paths from %Config.
163
164       (*) If the ".par"'s inst_archlib section (normally "blib/arch") isn't
165       empty, the code in inst_lib (normally "blib/lib") is also installed
166       into the inst_archlib path. This makes sense for XS modules.  If,
167       however, you override "inst_lib", this automatic conversion is also
168       overridden! You can use the named parameter "auto_inst_lib_conversion
169       => 1" to re-enable the conversion for custom inst_lib's.
170
171       Finally, you may specify a "custom_targets" parameter. Its value should
172       be a reference to a hash of custom installation targets such as
173
174         custom_targets => { 'blib/my_data' => '/some/path/my_data' }
175
176       You can use this to install the .par archives contents to arbitrary
177       locations.
178
179   uninstall_par
180       Uninstalls all previously installed contents of a PAR distribution,
181       using "ExtUtils::Install::uninstall".
182
183       Takes almost the same parameters as "install_par", but naturally, the
184       installation target parameters do not apply. The only exception to this
185       is the "packlist_read" parameter which specifies the .packlist file to
186       read the list of installed files from.  It defaults to
187       "$Config::Config{installsitearch}/auto/$name/.packlist".
188
189       Additionally, the "uninstall_shadows" parameter of "install_par" isn't
190       available.
191
192   sign_par
193       Digitally sign a PAR distribution using "gpg" or Crypt::OpenPGP, via
194       Module::Signature.
195
196   verify_par
197       Verify the digital signature of a PAR distribution using "gpg" or
198       Crypt::OpenPGP, via Module::Signature.
199
200       Returns a boolean value indicating whether verification passed; $!  is
201       set to the return code of "Module::Signature::verify".
202
203   merge_par
204       Note: Since version 0.32 of PAR::Dist, this function requires a YAML
205       reader. The order of precedence is:
206
207         YAML:XS YAML YAML::Syck YAML::Tiny
208
209       Merges two or more PAR distributions into one. First argument must be
210       the name of the distribution you want to merge all others into.  Any
211       following arguments will be interpreted as the file names of further
212       PAR distributions to merge into the first one.
213
214         merge_par('foo.par', 'bar.par', 'baz.par')
215
216       This will merge the distributions "foo.par", "bar.par" and "baz.par"
217       into the distribution "foo.par". "foo.par" will be overwritten!
218
219       The original META.yml of "foo.par" is retained, but augmented with any
220       "provides", "requires", "recommends", "build_requires", and
221       "configure_requires" sections from the other ".par" files.
222
223   remove_man
224       Remove the man pages from a PAR distribution. Takes one named
225       parameter: dist which should be the name (and path) of the PAR
226       distribution file. The calling conventions outlined in the "FUNCTIONS"
227       section above apply.
228
229       The PAR archive will be extracted, stripped of all "man\d?" and "html"
230       subdirectories and then repackaged into the original file.
231
232   get_meta
233       Opens a PAR archive and extracts the contained META.yml file.  Returns
234       the META.yml file as a string.
235
236       Takes one named parameter: dist. If only one parameter is passed, it is
237       treated as the dist parameter. (Have a look at the description in the
238       "FUNCTIONS" section above.)
239
240       Returns undef if no PAR archive or no META.yml within the archive were
241       found.
242
243   parse_dist_name
244       First argument must be a distribution file name. The file name is
245       parsed into distribution name, distribution version, architecture name,
246       and perl version.
247
248       Returns the results as a list in the above order.  If any or all of the
249       above cannot be determined, returns undef instead of the undetermined
250       elements.
251
252       Supported formats are:
253
254       Math-Symbolic-0.502-x86_64-linux-gnu-thread-multi-5.8.7
255
256       Math-Symbolic-0.502
257
258       The ".tar.gz" or ".par" extensions as well as any preceding paths are
259       stripped before parsing. Starting with "PAR::Dist" 0.22, versions
260       containing a preceding "v" are parsed correctly.
261
262       This function is not exported by default.
263
264   generate_blib_stub
265       Creates a blib/lib subdirectory in the current directory and prepares a
266       META.yml with meta information for a new PAR distribution. First
267       argument should be the name of the PAR distribution in a format
268       understood by "parse_dist_name()".  Alternatively, named arguments
269       resembling those of "blib_to_par" are accepted.
270
271       After running "generate_blib_stub" and injecting files into the blib
272       directory, you can create a PAR distribution using "blib_to_par".  This
273       function is useful for creating custom PAR distributions from scratch.
274       (I.e. not from an unpacked CPAN distribution) Example:
275
276         use PAR::Dist;
277         use File::Copy 'copy';
278
279         generate_blib_stub(
280           name => 'MyApp', version => '1.00'
281         );
282         copy('MyApp.pm', 'blib/lib/MyApp.pm');
283         blib_to_par(); # generates the .par file!
284
285       "generate_blib_stub" will not overwrite existing files.
286
287   contains_binaries
288       This function is not exported by default.
289
290       Opens a PAR archive tries to determine whether that archive contains
291       platform-specific binary code.
292
293       Takes one named parameter: dist. If only one parameter is passed, it is
294       treated as the dist parameter. (Have a look at the description in the
295       "FUNCTIONS" section above.)
296
297       Throws a fatal error if the PAR archive could not be found.
298
299       Returns one if the PAR was found to contain binary code and zero
300       otherwise.
301

SEE ALSO

303       PAR, ExtUtils::Install, Module::Signature, LWP::Simple
304

AUTHORS

306       Audrey Tang <cpan@audreyt.org> 2003-2007
307
308       Steffen Mueller <smueller@cpan.org> 2005-2011
309
310       PAR has a mailing list, <par@perl.org>, that you can write to; send an
311       empty mail to <par-subscribe@perl.org> to join the list and participate
312       in the discussion.
313
314       Please send bug reports to <bug-par@rt.cpan.org>.
315
317       Copyright 2003-2011 by Audrey Tang <autrijus@autrijus.org>.
318
319       This program is free software; you can redistribute it and/or modify it
320       under the same terms as Perl itself.
321
322       See <http://www.perl.com/perl/misc/Artistic.html>
323
324
325
326perl v5.16.3                      2012-10-14                      PAR::Dist(3)
Impressum