1PAR::Dist(3) User Contributed Perl Documentation PAR::Dist(3)
2
6 PAR::Dist - Create and manipulate PAR distributions
7
9 This document describes version 0.47 of PAR::Dist, released November
10 29, 2009.
11
13 As a shell command:
14 % perl -MPAR::Dist -eblib_to_par
16 In programs:
18 use PAR::Dist;
20 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 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
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 The naming convention for such distributions is:
40 $NAME-$VERSION-$ARCH-$PERL_VERSION.par
42 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
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 Therefore, under a directory containing only a single test.par, all
55 invocations below are equivalent:
56 % 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 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 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 blib_to_par
73 Takes key/value pairs as parameters or a single parameter indicating
74 the path that contains the blib/ subdirectory.
75 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 Returns the filename of the generated PAR distribution.
82 Valid parameters are:
84 path
86 Sets the path which contains the blib/ subdirectory from which the
87 PAR distribution will be generated.
88 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 The suffix is generated from your architecture name and your version
95 of perl by default.
96 dist
98 The output filename for the PAR distribution.
99 quiet
101 Set to true to suppress as much output as possible.
102 install_par
104 Installs a PAR distribution into the system, using
105 "ExtUtils::Install::install_default".
106 If only a single parameter is given, it is treated as the value for the
108 "dist" parameter.
109 Valid named parameters are:
111 dist
113 The .par file to install. The heuristics outlined in the FUNCTIONS
114 section above apply.
115 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 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 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 Default verbosity for PAR::Dist is 1.
134 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 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 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 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 Again, the defaults will be the normal site paths from %Config.
163 (*) 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 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 custom_targets => { 'blib/my_data' => '/some/path/my_data' }
175 You can use this to install the .par archives contents to arbitrary
177 locations.
178 uninstall_par
180 Uninstalls all previously installed contents of a PAR distribution,
181 using "ExtUtils::Install::uninstall".
182 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 Additionally, the "uninstall_shadows" parameter of "install_par" isn't
190 available.
191 sign_par
193 Digitally sign a PAR distribution using "gpg" or Crypt::OpenPGP, via
194 Module::Signature.
195 verify_par
197 Verify the digital signature of a PAR distribution using "gpg" or
198 Crypt::OpenPGP, via Module::Signature.
199 Returns a boolean value indicating whether verification passed; $! is
201 set to the return code of "Module::Signature::verify".
202 merge_par
204 Note: Since version 0.32 of PAR::Dist, this function requires a YAML
205 reader. The order of precedence is:
206 YAML:XS YAML YAML::Syck YAML::Tiny
208 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 merge_par('foo.par', 'bar.par', 'baz.par')
215 This will merge the distributions "foo.par", "bar.par" and "baz.par"
217 into the distribution "foo.par". "foo.par" will be overwritten!
218 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 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 The PAR archive will be extracted, stripped of all "man\d?" and "html"
230 subdirectories and then repackaged into the original file.
231 get_meta
233 Opens a PAR archive and extracts the contained META.yml file. Returns
234 the META.yml file as a string.
235 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 Returns undef if no PAR archive or no META.yml within the archive were
241 found.
242 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 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 Supported formats are:
253 Math-Symbolic-0.502-x86_64-linux-gnu-thread-multi-5.8.7
255 Math-Symbolic-0.502
257 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 This function is not exported by default.
263 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 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 use PAR::Dist;
277 use File::Copy 'copy';
278 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 "generate_blib_stub" will not overwrite existing files.
286 contains_binaries
288 This function is not exported by default.
289 Opens a PAR archive tries to determine whether that archive contains
291 platform-specific binary code.
292 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 Throws a fatal error if the PAR archive could not be found.
298 Returns one if the PAR was found to contain binary code and zero
300 otherwise.
301
303 PAR, ExtUtils::Install, Module::Signature, LWP::Simple
304
306 Audrey Tang <cpan@audreyt.org> 2003-2007
307 Steffen Mueller <smueller@cpan.org> 2005-2011
309 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 Please send bug reports to <bug-par@rt.cpan.org>.
315
317 Copyright 2003-2011 by Audrey Tang <autrijus@autrijus.org>.
318 This program is free software; you can redistribute it and/or modify it
320 under the same terms as Perl itself.
321 See <http://www.perl.com/perl/misc/Artistic.html>
323perl v5.16.3 2012-10-14 PAR::Dist(3)