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