1PAR::Dist(3) User Contributed Perl Documentation PAR::Dist(3)
2
6 PAR::Dist - Create and manipulate PAR distributions
7
9 As a shell command:
10 % perl -MPAR::Dist -eblib_to_par
12 In programs:
14 use PAR::Dist;
16 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 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
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 The naming convention for such distributions is:
36 $NAME-$VERSION-$ARCH-$PERL_VERSION.par
38 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
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 Therefore, under a directory containing only a single test.par, all
51 invocations below are equivalent:
52 % 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 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 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 blib_to_par
69 Takes key/value pairs as parameters or a single parameter indicating
70 the path that contains the blib/ subdirectory.
71 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 Returns the filename of the generated PAR distribution.
78 Valid parameters are:
80 path
82 Sets the path which contains the blib/ subdirectory from which the
83 PAR distribution will be generated.
84 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 The suffix is generated from your architecture name and your version
91 of perl by default.
92 dist
94 The output filename for the PAR distribution.
95 quiet
97 Set to true to suppress as much output as possible.
98 install_par
100 Installs a PAR distribution into the system, using
101 "ExtUtils::Install::install_default".
102 If only a single parameter is given, it is treated as the value for the
104 "dist" parameter.
105 Valid named parameters are:
107 dist
109 The .par file to install. The heuristics outlined in the FUNCTIONS
110 section above apply.
111 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 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 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 Default verbosity for PAR::Dist is 1.
130 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 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 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 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 Again, the defaults will be the normal site paths from %Config.
159 (*) 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 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 custom_targets => { 'blib/my_data' => '/some/path/my_data' }
171 You can use this to install the .par archives contents to arbitrary
173 locations.
174 uninstall_par
176 Uninstalls all previously installed contents of a PAR distribution,
177 using "ExtUtils::Install::uninstall".
178 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 Additionally, the "uninstall_shadows" parameter of "install_par" isn't
186 available.
187 sign_par
189 Digitally sign a PAR distribution using "gpg" or Crypt::OpenPGP, via
190 Module::Signature.
191 verify_par
193 Verify the digital signature of a PAR distribution using "gpg" or
194 Crypt::OpenPGP, via Module::Signature.
195 Returns a boolean value indicating whether verification passed; $! is
197 set to the return code of "Module::Signature::verify".
198 merge_par
200 Note: Since version 0.32 of PAR::Dist, this function requires a YAML
201 reader. The order of precedence is:
202 YAML:XS YAML YAML::Syck YAML::Tiny
204 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 merge_par('foo.par', 'bar.par', 'baz.par')
211 This will merge the distributions "foo.par", "bar.par" and "baz.par"
213 into the distribution "foo.par". "foo.par" will be overwritten!
214 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 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 The PAR archive will be extracted, stripped of all "man\d?" and "html"
226 subdirectories and then repackaged into the original file.
227 get_meta
229 Opens a PAR archive and extracts the contained META.yml file. Returns
230 the META.yml file as a string.
231 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 Returns undef if no PAR archive or no META.yml within the archive were
237 found.
238 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 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 Supported formats are:
249 Math-Symbolic-0.502-x86_64-linux-gnu-thread-multi-5.8.7
251 Math-Symbolic-0.502
253 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 This function is not exported by default.
259 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 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 use PAR::Dist;
273 use File::Copy 'copy';
274 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 "generate_blib_stub" will not overwrite existing files.
282 contains_binaries
284 This function is not exported by default.
285 Opens a PAR archive tries to determine whether that archive contains
287 platform-specific binary code.
288 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 Throws a fatal error if the PAR archive could not be found.
294 Returns one if the PAR was found to contain binary code and zero
296 otherwise.
297
299 PAR, ExtUtils::Install, Module::Signature, LWP::Simple
300
302 Audrey Tang <cpan@audreyt.org> 2003-2007
303 Steffen Mueller <smueller@cpan.org> 2005-2011
305 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 Please send bug reports to <bug-par@rt.cpan.org>.
311
313 Copyright 2003-2011 by Audrey Tang <autrijus@autrijus.org>.
314 This program is free software; you can redistribute it and/or modify it
316 under the same terms as Perl itself.
317 See <http://www.perl.com/perl/misc/Artistic.html>
319perl v5.38.0 2023-07-21 PAR::Dist(3)