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 | ||
ad68f4fd | 38 | =item L<pod2html|pod2html> |
497711e7 | 39 | |
ad68f4fd CBW |
40 | As well as these two, there is another converter: F<pod2html> will |
41 | produce HTML pages from POD. | |
497711e7 GS |
42 | |
43 | =item L<pod2usage|pod2usage> | |
44 | ||
45 | If you just want to know how to use the utilities described here, | |
46 | F<pod2usage> will just extract the "USAGE" section; some of | |
47 | the utilities will automatically call F<pod2usage> on themselves when | |
48 | you call them with C<-help>. | |
49 | ||
50 | =item L<podselect|podselect> | |
51 | ||
52 | F<pod2usage> is a special case of F<podselect>, a utility to extract | |
53 | named sections from documents written in POD. For instance, while | |
54 | utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS" | |
55 | sections: C<podselect -s "SYNOPSIS" ...> will extract this section for | |
56 | a given file. | |
57 | ||
58 | =item L<podchecker|podchecker> | |
59 | ||
60 | If you're writing your own documentation in POD, the F<podchecker> | |
61 | utility will look for errors in your markup. | |
62 | ||
63 | =item L<splain|splain> | |
64 | ||
65 | F<splain> is an interface to L<perldiag> - paste in your error message | |
66 | to it, and it'll explain it for you. | |
67 | ||
a24e5063 | 68 | =item C<roffitall> |
497711e7 GS |
69 | |
70 | The C<roffitall> utility is not installed on your system but lives in | |
71 | the F<pod/> directory of your Perl source kit; it converts all the | |
72 | documentation from the distribution to F<*roff> format, and produces a | |
73 | typeset PostScript or text file of the whole lot. | |
74 | ||
75 | =back | |
76 | ||
b6538e4f | 77 | =head2 Converters |
497711e7 | 78 | |
e5a8a0fb LT |
79 | To help you convert legacy programs to more modern Perl, the |
80 | L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries | |
81 | to new-style Perl5 modules. | |
497711e7 | 82 | |
a6fb92f1 JH |
83 | =head2 Administration |
84 | ||
85 | =over 3 | |
86 | ||
87 | =item L<libnetcfg|libnetcfg> | |
88 | ||
89 | To display and change the libnet configuration run the libnetcfg command. | |
90 | ||
baf0caad | 91 | =item L<perlivp> |
bb4e9162 | 92 | |
baf0caad RGS |
93 | The F<perlivp> program is set up at Perl source code build time to test |
94 | the Perl version it was built under. It can be used after running C<make | |
95 | install> (or your platform's equivalent procedure) to verify that perl | |
96 | and its libraries have been installed correctly. | |
bb4e9162 | 97 | |
a6fb92f1 JH |
98 | =back |
99 | ||
497711e7 GS |
100 | =head2 Development |
101 | ||
102 | There are a set of utilities which help you in developing Perl programs, | |
103 | and in particular, extending Perl with C. | |
104 | ||
105 | =over 3 | |
106 | ||
107 | =item L<perlbug|perlbug> | |
108 | ||
109 | F<perlbug> is the recommended way to report bugs in the perl interpreter | |
110 | itself or any of the standard library modules back to the developers; | |
111 | please read through the documentation for F<perlbug> thoroughly before | |
112 | using it to submit a bug report. | |
113 | ||
f9615397 | 114 | =item L<perlthanks|perlbug> |
03f3e794 RGS |
115 | |
116 | This program provides an easy way to send a thank-you message back to the | |
117 | authors and maintainers of perl. It's just F<perlbug> installed under | |
118 | another name. | |
119 | ||
497711e7 GS |
120 | =item L<h2ph|h2ph> |
121 | ||
122 | Back before Perl had the XS system for connecting with C libraries, | |
123 | programmers used to get library constants by reading through the C | |
124 | header files. You may still see C<require 'syscall.ph'> or similar | |
125 | around - the F<.ph> file should be created by running F<h2ph> on the | |
126 | corresponding F<.h> file. See the F<h2ph> documentation for more on how | |
c06dc7de | 127 | to convert a whole bunch of header files at once. |
497711e7 GS |
128 | |
129 | =item L<c2ph|c2ph> and L<pstruct|pstruct> | |
130 | ||
131 | F<c2ph> and F<pstruct>, which are actually the same program but behave | |
132 | differently depending on how they are called, provide another way of | |
133 | getting at C with Perl - they'll convert C structures and union declarations | |
134 | to Perl code. This is deprecated in favour of F<h2xs> these days. | |
135 | ||
136 | =item L<h2xs|h2xs> | |
137 | ||
138 | F<h2xs> converts C header files into XS modules, and will try and write | |
139 | as much glue between C libraries and Perl modules as it can. It's also | |
140 | very useful for creating skeletons of pure Perl modules. | |
141 | ||
baf0caad RGS |
142 | =item L<enc2xs> |
143 | ||
144 | F<enc2xs> builds a Perl extension for use by Encode from either | |
145 | Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). | |
146 | Besides being used internally during the build process of the Encode | |
147 | module, you can use F<enc2xs> to add your own encoding to perl. | |
148 | No knowledge of XS is necessary. | |
149 | ||
150 | =item L<xsubpp> | |
151 | ||
152 | F<xsubpp> is a compiler to convert Perl XS code into C code. | |
153 | It is typically run by the makefiles created by L<ExtUtils::MakeMaker>. | |
154 | ||
155 | F<xsubpp> will compile XS code into C code by embedding the constructs | |
156 | necessary to let C functions manipulate Perl values and creates the glue | |
157 | necessary to let Perl access those functions. | |
158 | ||
baf0caad RGS |
159 | =item L<prove> |
160 | ||
e1020413 | 161 | F<prove> is a command-line interface to the test-running functionality |
baf0caad RGS |
162 | of F<Test::Harness>. It's an alternative to C<make test>. |
163 | ||
164 | =item L<corelist> | |
165 | ||
166 | A command-line front-end to C<Module::CoreList>, to query what modules | |
167 | were shipped with given versions of perl. | |
168 | ||
169 | =back | |
170 | ||
171 | =head2 General tools | |
172 | ||
173 | A few general-purpose tools are shipped with perl, mostly because they | |
174 | came along modules included in the perl distribution. | |
175 | ||
176 | =over 3 | |
177 | ||
178 | =item L<piconv> | |
179 | ||
180 | B<piconv> is a Perl version of B<iconv>, a character encoding converter | |
181 | widely available for various Unixen today. This script was primarily a | |
7c2e2b3a | 182 | technology demonstrator for Perl v5.8.0, but you can use piconv in the |
baf0caad RGS |
183 | place of iconv for virtually any case. |
184 | ||
185 | =item L<ptar> | |
186 | ||
187 | F<ptar> is a tar-like program, written in pure Perl. | |
188 | ||
189 | =item L<ptardiff> | |
190 | ||
191 | F<ptardiff> is a small utility that produces a diff between an extracted | |
634d76cd RGS |
192 | archive and an unextracted one. (Note that this utility requires the |
193 | C<Text::Diff> module to function properly; this module isn't distributed | |
194 | with perl, but is available from the CPAN.) | |
baf0caad | 195 | |
deabda19 CBW |
196 | =item L<ptargrep> |
197 | ||
198 | F<ptargrep> is a utility to apply pattern matching to the contents of files | |
199 | in a tar archive. | |
200 | ||
baf0caad RGS |
201 | =item L<shasum> |
202 | ||
203 | This utility, that comes with the C<Digest::SHA> module, is used to print | |
204 | or verify SHA checksums. | |
205 | ||
08ad9465 CBW |
206 | =item L<zipdetails> |
207 | ||
208 | L<zipdetails> displays information about the internal record structure of the zip file. | |
209 | It is not concerned with displaying any details of the compressed data stored in the zip file. | |
210 | ||
baf0caad RGS |
211 | =back |
212 | ||
213 | =head2 Installation | |
214 | ||
215 | These utilities help manage extra Perl modules that don't come with the perl | |
216 | distribution. | |
217 | ||
218 | =over 3 | |
219 | ||
220 | =item L<cpan> | |
221 | ||
222 | F<cpan> is a command-line interface to CPAN.pm. It allows you to install | |
223 | modules or distributions from CPAN, or just get information about them, and | |
224 | a lot more. It is similar to the command line mode of the L<CPAN> module, | |
225 | ||
226 | perl -MCPAN -e shell | |
227 | ||
228 | =item L<instmodsh> | |
229 | ||
230 | A little interface to ExtUtils::Installed to examine installed modules, | |
231 | validate your packlists and even create a tarball from an installed module. | |
232 | ||
497711e7 GS |
233 | =back |
234 | ||
baf0caad | 235 | =head1 SEE ALSO |
497711e7 GS |
236 | |
237 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, | |
238 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, | |
239 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>, | |
e5a8a0fb LT |
240 | C<roffitall|roffitall>, L<File::Find|File::Find>, L<pl2pm|pl2pm>, |
241 | L<perlbug|perlbug>, L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, | |
242 | L<xsubpp>, L<cpan>, L<instmodsh>, L<piconv>, L<prove>, L<corelist>, L<ptar>, | |
243 | L<ptardiff>, L<shasum>, L<zipdetails> | |
497711e7 GS |
244 | |
245 | =cut |