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.20 of PAR::Dist, released Oct 11,
10 2006.
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-0.91"); # uses CPAN author directory
30
32 This module creates and manipulates PAR distributions. They are archi‐
33 tecture-specific PAR files, containing everything under blib/ of CPAN
34 distributions after their "make" or "Build" stage, a META.yml describ‐
35 ing metadata of the original CPAN distribution, and a MANIFEST detail‐
36 ing all files within it. Digitally signed PAR distributions will also
37 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. "http://www.cpan.org/mod‐
66 ules/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
75 the path that contains the blib/ subdirectory.
76 Builds a PAR distribution from the blib/ subdirectory under "path", or
78 under the current directory if unspecified. If blib/ does not exist,
79 it automatically runs Build, make, Build.PL or Makefile.PL to create
80 it.
81 Returns the filename or the generated PAR distribution.
83 Valid parameters are:
85 path
87 Sets the path which contains the blib/ subdirectory from which the
88 PAR distribution will be generated.
89 name, version, suffix
91 These attributes set the name, version and platform specific suffix
92 of the distribution. Name and version can be automatically determined
93 from the distributions META.yml or Makefile.PL files.
94 The suffix is generated from your architecture name and your version
96 of perl by default.
97 dist
99 The output filename for the PAR distribution.
100 install_par
102 Installs a PAR distribution into the system, using "ExtU‐
104 tils::Install::install_default".
105 Valid 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 Additionally, you can use several parameters to change the default
118 installation destinations. You don't usually have to worry about this
119 unless you are installing into a user-local directory. The following
120 section outlines the parameter names and default settings:
121 Parameter From To
123 inst_lib blib/lib $Config{installsitelib} (*)
124 inst_archlib blib/arch $Config{installsitearch}
125 inst_script blib/script $Config{installscript}
126 inst_bin blib/bin $Config{installbin}
127 inst_man1dir blib/man1 $Config{installman1dir}
128 inst_man3dir blib/man3 $Config{installman3dir}
129 packlist_read $Config{sitearchexp}/auto/$name/.packlist
130 packlist_write $Config{installsitearch}/auto/$name/.packlist
131 The "packlist_write" parameter is used to control where the .packlist
133 file is written to. (Necessary for uninstallation.) The "pack‐
134 list_read" parameter specifies a .packlist file to merge in if it
135 exists.
136 Finally, you may specify a "custom_targets" parameter. Its value should
138 be a reference to a hash of custom installation targets such as
139 custom_targets => { 'blib/my_data' => '/some/path/my_data' }
141 You can use this to install the .par archives contents to arbitrary
143 locations.
144 If only a single parameter is given, it is treated as the "dist" param‐
146 eter.
147 uninstall_par
149 Uninstalls all previously installed contents of a PAR distribution,
151 using "ExtUtils::Install::uninstall".
152 Takes almost the same parameters as "install_par", but naturally, the
154 installation target parameters do not apply. The only exception to this
155 is the "packlist_read" parameter which specifies the .packlist file to
156 read the list of installed files from. It defaults to "$Config::Con‐
157 fig{installsitearch}/auto/$name/.packlist".
158 sign_par
160 Digitally sign a PAR distribution using "gpg" or Crypt::OpenPGP, via
162 Module::Signature.
163 verify_par
165 Verify the digital signature of a PAR distribution using "gpg" or
167 Crypt::OpenPGP, via Module::Signature.
168 Returns a boolean value indicating whether verification passed; $! is
170 set to the return code of "Module::Signature::verify".
171 merge_par
173 Merge two or more PAR distributions into one. First argument must be
175 the name of the distribution you want to merge all others into. Any
176 following arguments will be interpreted as the file names of further
177 PAR distributions to merge into the first one.
178 merge_par('foo.par', 'bar.par', 'baz.par')
180 This will merge the distributions "foo.par", "bar.par" and "baz.par"
182 into the distribution "foo.par". "foo.par" will be overwritten! The
183 original META.yml of "foo.par" is retained.
184 remove_man
186 Remove the man pages from a PAR distribution. Takes one named parame‐
188 ter: dist which should be the name (and path) of the PAR distribution
189 file. The calling conventions outlined in the "FUNCTIONS" section above
190 apply.
191 The PAR archive will be extracted, stripped of all "man\d?" and "html"
193 subdirectories and then repackaged into the original file.
194 get_meta
196 Opens a PAR archive and extracts the contained META.yml file. Returns
198 the META.yml file as a string.
199 Takes one named parameter: dist. If only one parameter is passed, it is
201 treated as the dist parameter. (Have a look at the description in the
202 "FUNCTIONS" section above.)
203 Returns undef if no PAR archive or no META.yml within the archive were
205 found.
206 parse_dist_name
208 First argument must be a distribution file name. The file name is
210 parsed into distribution name, distribution version, architecture name,
211 and perl version.
212 Returns the results as a list in the above order. If any or all of the
214 above cannot be determined, returns undef instead of the undetermined
215 elements.
216 Supported formats are:
218 Math-Symbolic-0.502-x86_64-linux-gnu-thread-multi-5.8.7
220 Math-Symbolic-0.502
222 The ".tar.gz" or ".par" extensions as well as any preceding paths are
224 stripped before parsing.
225 This function is not exported by default.
227 generate_blib_stub
229 Creates a blib/lib subdirectory in the current directory and prepares a
231 META.yml with meta information for a new PAR distribution. First argu‐
232 ment should be the name of the PAR distribution in a format understood
233 by "parse_dist_name()". Alternatively, named arguments resembling
234 those of "blib_to_par" are accepted.
235 After running "generate_blib_stub" and injecting files into the blib
237 directory, you can create a PAR distribution using "blib_to_par". This
238 function is useful for creating custom PAR distributions from scratch.
239 (I.e. not from an unpacked CPAN distribution) Example:
240 use PAR::Dist;
242 use File::Copy 'copy';
243 generate_blib_stub(
245 name => 'MyApp', version => '1.00'
246 );
247 copy('MyApp.pm', 'blib/lib/MyApp.pm');
248 blib_to_par(); # generates the .par file!
249 "generate_blib_stub" will not overwrite existing files.
251
253 PAR, ExtUtils::Install, Module::Signature, LWP::Simple
254
256 Audrey Tang <cpan@audreyt.org> 2003-2006
257 Steffen Mueller <smueller@cpan.org> 2005-2006
259 PAR has a mailing list, <par@perl.org>, that you can write to; send an
261 empty mail to <par-subscribe@perl.org> to join the list and participate
262 in the discussion.
263 Please send bug reports to <bug-par@rt.cpan.org>.
265
267 Copyright 2003, 2004, 2006 by Audrey Tang <autrijus@autrijus.org>.
268 This program is free software; you can redistribute it and/or modify it
270 under the same terms as Perl itself.
271 See <http://www.perl.com/perl/misc/Artistic.html>
273perl v5.8.8 2006-10-12 PAR::Dist(3)