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