Commit | Line | Data |
---|---|---|
497711e7 GS |
1 | =head1 NAME |
2 | ||
3 | perlutil - utilities packaged with the Perl distribution | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | Along with the Perl interpreter itself, the Perl distribution installs a | |
8 | range of utilities on your system. There are also several utilities | |
9 | which are used by the Perl distribution itself as part of the install | |
10 | process. This document exists to list all of these utilities, explain | |
11 | what they are for and provide pointers to each module's documentation, | |
12 | if appropriate. | |
13 | ||
baf0caad RGS |
14 | =head1 LIST OF UTILITIES |
15 | ||
16 | =head2 Documentation | |
497711e7 GS |
17 | |
18 | =over 3 | |
19 | ||
20 | =item L<perldoc|perldoc> | |
21 | ||
22 | The main interface to Perl's documentation is C<perldoc>, although | |
23 | if you're reading this, it's more than likely that you've already found | |
24 | it. F<perldoc> will extract and format the documentation from any file | |
25 | in the current directory, any Perl module installed on the system, or | |
26 | any of the standard documentation pages, such as this one. Use | |
27 | C<perldoc E<lt>nameE<gt>> to get information on any of the utilities | |
28 | described in this document. | |
29 | ||
30 | =item L<pod2man|pod2man> and L<pod2text|pod2text> | |
31 | ||
32 | If it's run from a terminal, F<perldoc> will usually call F<pod2man> to | |
33 | translate POD (Plain Old Documentation - see L<perlpod> for an | |
3958b146 | 34 | explanation) into a manpage, and then run F<man> to display it; if |
497711e7 GS |
35 | F<man> isn't available, F<pod2text> will be used instead and the output |
36 | piped through your favourite pager. | |
37 | ||
38 | =item L<pod2html|pod2html> and L<pod2latex|pod2latex> | |
39 | ||
a31a806a | 40 | As well as these two, there are two other converters: F<pod2html> will |
497711e7 GS |
41 | produce HTML pages from POD, and F<pod2latex>, which produces LaTeX |
42 | files. | |
43 | ||
44 | =item L<pod2usage|pod2usage> | |
45 | ||
46 | If you just want to know how to use the utilities described here, | |
47 | F<pod2usage> will just extract the "USAGE" section; some of | |
48 | the utilities will automatically call F<pod2usage> on themselves when | |
49 | you call them with C<-help>. | |
50 | ||
51 | =item L<podselect|podselect> | |
52 | ||
53 | F<pod2usage> is a special case of F<podselect>, a utility to extract | |
54 | named sections from documents written in POD. For instance, while | |
55 | utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS" | |
56 | sections: C<podselect -s "SYNOPSIS" ...> will extract this section for | |
57 | a given file. | |
58 | ||
59 | =item L<podchecker|podchecker> | |
60 | ||
61 | If you're writing your own documentation in POD, the F<podchecker> | |
62 | utility will look for errors in your markup. | |
63 | ||
64 | =item L<splain|splain> | |
65 | ||
66 | F<splain> is an interface to L<perldiag> - paste in your error message | |
67 | to it, and it'll explain it for you. | |
68 | ||
a24e5063 | 69 | =item C<roffitall> |
497711e7 GS |
70 | |
71 | The C<roffitall> utility is not installed on your system but lives in | |
72 | the F<pod/> directory of your Perl source kit; it converts all the | |
73 | documentation from the distribution to F<*roff> format, and produces a | |
74 | typeset PostScript or text file of the whole lot. | |
75 | ||
76 | =back | |
77 | ||
b6538e4f | 78 | =head2 Converters |
497711e7 GS |
79 | |
80 | To help you convert legacy programs to Perl, we've included three | |
81 | conversion filters: | |
82 | ||
83 | =over 3 | |
84 | ||
85 | =item L<a2p|a2p> | |
86 | ||
87 | F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:> | |
88 | on the simple F<awk> script C<{print $2}> will produce a Perl program | |
89 | based around this code: | |
90 | ||
91 | while (<>) { | |
944d48f7 | 92 | ($Fld1,$Fld2) = split(/[:\n]/, $_, -1); |
497711e7 GS |
93 | print $Fld2; |
94 | } | |
95 | ||
baf0caad | 96 | =item L<s2p|s2p> and L<psed> |
497711e7 GS |
97 | |
98 | Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run | |
99 | on C<s/foo/bar> will produce a Perl program based around this: | |
100 | ||
101 | while (<>) { | |
5b3eff12 | 102 | chomp; |
497711e7 GS |
103 | s/foo/bar/g; |
104 | print if $printit; | |
105 | } | |
106 | ||
baf0caad RGS |
107 | When invoked as F<psed>, it behaves as a F<sed> implementation, written in |
108 | Perl. | |
109 | ||
497711e7 GS |
110 | =item L<find2perl|find2perl> |
111 | ||
112 | Finally, F<find2perl> translates C<find> commands to Perl equivalents which | |
113 | use the L<File::Find|File::Find> module. As an example, | |
114 | C<find2perl . -user root -perm 4000 -print> produces the following callback | |
115 | subroutine for C<File::Find>: | |
116 | ||
117 | sub wanted { | |
118 | my ($dev,$ino,$mode,$nlink,$uid,$gid); | |
119 | (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && | |
120 | $uid == $uid{'root'}) && | |
121 | (($mode & 0777) == 04000); | |
122 | print("$name\n"); | |
123 | } | |
124 | ||
125 | =back | |
126 | ||
127 | As well as these filters for converting other languages, the | |
128 | L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to | |
129 | new-style Perl5 modules. | |
130 | ||
a6fb92f1 JH |
131 | =head2 Administration |
132 | ||
133 | =over 3 | |
134 | ||
baf0caad RGS |
135 | =item L<config_data|config_data> |
136 | ||
137 | Query or change configuration of Perl modules that use Module::Build-based | |
138 | configuration files for features and config data. | |
139 | ||
a6fb92f1 JH |
140 | =item L<libnetcfg|libnetcfg> |
141 | ||
142 | To display and change the libnet configuration run the libnetcfg command. | |
143 | ||
baf0caad | 144 | =item L<perlivp> |
bb4e9162 | 145 | |
baf0caad RGS |
146 | The F<perlivp> program is set up at Perl source code build time to test |
147 | the Perl version it was built under. It can be used after running C<make | |
148 | install> (or your platform's equivalent procedure) to verify that perl | |
149 | and its libraries have been installed correctly. | |
bb4e9162 | 150 | |
a6fb92f1 JH |
151 | =back |
152 | ||
497711e7 GS |
153 | =head2 Development |
154 | ||
155 | There are a set of utilities which help you in developing Perl programs, | |
156 | and in particular, extending Perl with C. | |
157 | ||
158 | =over 3 | |
159 | ||
160 | =item L<perlbug|perlbug> | |
161 | ||
162 | F<perlbug> is the recommended way to report bugs in the perl interpreter | |
163 | itself or any of the standard library modules back to the developers; | |
164 | please read through the documentation for F<perlbug> thoroughly before | |
165 | using it to submit a bug report. | |
166 | ||
f9615397 | 167 | =item L<perlthanks|perlbug> |
03f3e794 RGS |
168 | |
169 | This program provides an easy way to send a thank-you message back to the | |
170 | authors and maintainers of perl. It's just F<perlbug> installed under | |
171 | another name. | |
172 | ||
497711e7 GS |
173 | =item L<h2ph|h2ph> |
174 | ||
175 | Back before Perl had the XS system for connecting with C libraries, | |
176 | programmers used to get library constants by reading through the C | |
177 | header files. You may still see C<require 'syscall.ph'> or similar | |
178 | around - the F<.ph> file should be created by running F<h2ph> on the | |
179 | corresponding F<.h> file. See the F<h2ph> documentation for more on how | |
c06dc7de | 180 | to convert a whole bunch of header files at once. |
497711e7 GS |
181 | |
182 | =item L<c2ph|c2ph> and L<pstruct|pstruct> | |
183 | ||
184 | F<c2ph> and F<pstruct>, which are actually the same program but behave | |
185 | differently depending on how they are called, provide another way of | |
186 | getting at C with Perl - they'll convert C structures and union declarations | |
187 | to Perl code. This is deprecated in favour of F<h2xs> these days. | |
188 | ||
189 | =item L<h2xs|h2xs> | |
190 | ||
191 | F<h2xs> converts C header files into XS modules, and will try and write | |
192 | as much glue between C libraries and Perl modules as it can. It's also | |
193 | very useful for creating skeletons of pure Perl modules. | |
194 | ||
baf0caad RGS |
195 | =item L<enc2xs> |
196 | ||
197 | F<enc2xs> builds a Perl extension for use by Encode from either | |
198 | Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). | |
199 | Besides being used internally during the build process of the Encode | |
200 | module, you can use F<enc2xs> to add your own encoding to perl. | |
201 | No knowledge of XS is necessary. | |
202 | ||
203 | =item L<xsubpp> | |
204 | ||
205 | F<xsubpp> is a compiler to convert Perl XS code into C code. | |
206 | It is typically run by the makefiles created by L<ExtUtils::MakeMaker>. | |
207 | ||
208 | F<xsubpp> will compile XS code into C code by embedding the constructs | |
209 | necessary to let C functions manipulate Perl values and creates the glue | |
210 | necessary to let Perl access those functions. | |
211 | ||
baf0caad RGS |
212 | =item L<prove> |
213 | ||
e1020413 | 214 | F<prove> is a command-line interface to the test-running functionality |
baf0caad RGS |
215 | of F<Test::Harness>. It's an alternative to C<make test>. |
216 | ||
217 | =item L<corelist> | |
218 | ||
219 | A command-line front-end to C<Module::CoreList>, to query what modules | |
220 | were shipped with given versions of perl. | |
221 | ||
222 | =back | |
223 | ||
224 | =head2 General tools | |
225 | ||
226 | A few general-purpose tools are shipped with perl, mostly because they | |
227 | came along modules included in the perl distribution. | |
228 | ||
229 | =over 3 | |
230 | ||
231 | =item L<piconv> | |
232 | ||
233 | B<piconv> is a Perl version of B<iconv>, a character encoding converter | |
234 | widely available for various Unixen today. This script was primarily a | |
7c2e2b3a | 235 | technology demonstrator for Perl v5.8.0, but you can use piconv in the |
baf0caad RGS |
236 | place of iconv for virtually any case. |
237 | ||
238 | =item L<ptar> | |
239 | ||
240 | F<ptar> is a tar-like program, written in pure Perl. | |
241 | ||
242 | =item L<ptardiff> | |
243 | ||
244 | F<ptardiff> is a small utility that produces a diff between an extracted | |
634d76cd RGS |
245 | archive and an unextracted one. (Note that this utility requires the |
246 | C<Text::Diff> module to function properly; this module isn't distributed | |
247 | with perl, but is available from the CPAN.) | |
baf0caad | 248 | |
deabda19 CBW |
249 | =item L<ptargrep> |
250 | ||
251 | F<ptargrep> is a utility to apply pattern matching to the contents of files | |
252 | in a tar archive. | |
253 | ||
baf0caad RGS |
254 | =item L<shasum> |
255 | ||
256 | This utility, that comes with the C<Digest::SHA> module, is used to print | |
257 | or verify SHA checksums. | |
258 | ||
08ad9465 CBW |
259 | =item L<zipdetails> |
260 | ||
261 | L<zipdetails> displays information about the internal record structure of the zip file. | |
262 | It is not concerned with displaying any details of the compressed data stored in the zip file. | |
263 | ||
baf0caad RGS |
264 | =back |
265 | ||
266 | =head2 Installation | |
267 | ||
268 | These utilities help manage extra Perl modules that don't come with the perl | |
269 | distribution. | |
270 | ||
271 | =over 3 | |
272 | ||
273 | =item L<cpan> | |
274 | ||
275 | F<cpan> is a command-line interface to CPAN.pm. It allows you to install | |
276 | modules or distributions from CPAN, or just get information about them, and | |
277 | a lot more. It is similar to the command line mode of the L<CPAN> module, | |
278 | ||
279 | perl -MCPAN -e shell | |
280 | ||
8a499140 RGS |
281 | =item L<cpanp> |
282 | ||
283 | F<cpanp> is, like F<cpan>, a command-line interface to the CPAN, using | |
284 | the C<CPANPLUS> module as a back-end. It can be used interactively or | |
285 | imperatively. | |
286 | ||
287 | =item L<cpan2dist> | |
288 | ||
289 | F<cpan2dist> is a tool to create distributions (or packages) from CPAN | |
290 | modules, then suitable for your package manager of choice. Support for | |
291 | specific formats are available from CPAN as C<CPANPLUS::Dist::*> modules. | |
292 | ||
baf0caad RGS |
293 | =item L<instmodsh> |
294 | ||
295 | A little interface to ExtUtils::Installed to examine installed modules, | |
296 | validate your packlists and even create a tarball from an installed module. | |
297 | ||
497711e7 GS |
298 | =back |
299 | ||
baf0caad | 300 | =head1 SEE ALSO |
497711e7 GS |
301 | |
302 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, | |
303 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, | |
304 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>, | |
f9615397 | 305 | C<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>, |
497711e7 | 306 | L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>, |
c9dab4e9 FR |
307 | L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>, |
308 | L<cpan>, L<cpanp>, L<cpan2dist>, L<instmodsh>, L<piconv>, L<prove>, | |
08ad9465 | 309 | L<corelist>, L<ptar>, L<ptardiff>, L<shasum>, L<zipdetails> |
497711e7 GS |
310 | |
311 | =cut |