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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

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

SEE ALSO

299       PAR, ExtUtils::Install, Module::Signature, LWP::Simple
300

AUTHORS

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