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 | ||
43f856ba | 20 | =item L<perldoc> |
497711e7 | 21 | |
43f856ba | 22 | The main interface to Perl's documentation is F<perldoc>, although |
497711e7 GS |
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 | ||
43f856ba DB |
30 | =item L<pod2man> |
31 | ||
32 | =item L<pod2text> | |
497711e7 GS |
33 | |
34 | If it's run from a terminal, F<perldoc> will usually call F<pod2man> to | |
35 | translate POD (Plain Old Documentation - see L<perlpod> for an | |
3958b146 | 36 | explanation) into a manpage, and then run F<man> to display it; if |
497711e7 GS |
37 | F<man> isn't available, F<pod2text> will be used instead and the output |
38 | piped through your favourite pager. | |
39 | ||
43f856ba | 40 | =item L<pod2html> |
497711e7 | 41 | |
ad68f4fd CBW |
42 | As well as these two, there is another converter: F<pod2html> will |
43 | produce HTML pages from POD. | |
497711e7 | 44 | |
43f856ba | 45 | =item L<pod2usage> |
497711e7 GS |
46 | |
47 | If you just want to know how to use the utilities described here, | |
48 | F<pod2usage> will just extract the "USAGE" section; some of | |
49 | the utilities will automatically call F<pod2usage> on themselves when | |
50 | you call them with C<-help>. | |
51 | ||
43f856ba | 52 | =item L<podchecker> |
497711e7 GS |
53 | |
54 | If you're writing your own documentation in POD, the F<podchecker> | |
55 | utility will look for errors in your markup. | |
56 | ||
43f856ba | 57 | =item L<splain> |
497711e7 GS |
58 | |
59 | F<splain> is an interface to L<perldiag> - paste in your error message | |
60 | to it, and it'll explain it for you. | |
61 | ||
43f856ba | 62 | =item F<roffitall> |
497711e7 | 63 | |
43f856ba | 64 | The F<roffitall> utility is not installed on your system but lives in |
497711e7 GS |
65 | the F<pod/> directory of your Perl source kit; it converts all the |
66 | documentation from the distribution to F<*roff> format, and produces a | |
67 | typeset PostScript or text file of the whole lot. | |
68 | ||
69 | =back | |
70 | ||
b6538e4f | 71 | =head2 Converters |
497711e7 | 72 | |
43f856ba DB |
73 | =over 3 |
74 | ||
75 | =item L<pl2pm> | |
76 | ||
e5a8a0fb | 77 | To help you convert legacy programs to more modern Perl, the |
43f856ba | 78 | F<pl2pm> utility will help you convert old-style Perl 4 libraries |
e5a8a0fb | 79 | to new-style Perl5 modules. |
497711e7 | 80 | |
43f856ba DB |
81 | =back |
82 | ||
a6fb92f1 JH |
83 | =head2 Administration |
84 | ||
85 | =over 3 | |
86 | ||
43f856ba | 87 | =item L<libnetcfg> |
a6fb92f1 JH |
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 | ||
43f856ba | 107 | =item L<perlbug> |
497711e7 | 108 | |
8166b4e0 DB |
109 | F<perlbug> used to be the recommended way to report bugs in the perl |
110 | interpreter itself or any of the standard library modules back to the | |
111 | developers; bug reports and patches should now be submitted to | |
112 | L<https://github.com/Perl/perl5/issues>. | |
497711e7 | 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 | ||
43f856ba | 120 | =item L<h2ph> |
497711e7 GS |
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 | 128 | |
43f856ba | 129 | =item L<h2xs> |
497711e7 GS |
130 | |
131 | F<h2xs> converts C header files into XS modules, and will try and write | |
132 | as much glue between C libraries and Perl modules as it can. It's also | |
133 | very useful for creating skeletons of pure Perl modules. | |
134 | ||
baf0caad RGS |
135 | =item L<enc2xs> |
136 | ||
137 | F<enc2xs> builds a Perl extension for use by Encode from either | |
138 | Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). | |
139 | Besides being used internally during the build process of the Encode | |
140 | module, you can use F<enc2xs> to add your own encoding to perl. | |
141 | No knowledge of XS is necessary. | |
142 | ||
143 | =item L<xsubpp> | |
144 | ||
145 | F<xsubpp> is a compiler to convert Perl XS code into C code. | |
146 | It is typically run by the makefiles created by L<ExtUtils::MakeMaker>. | |
147 | ||
148 | F<xsubpp> will compile XS code into C code by embedding the constructs | |
149 | necessary to let C functions manipulate Perl values and creates the glue | |
150 | necessary to let Perl access those functions. | |
151 | ||
baf0caad RGS |
152 | =item L<prove> |
153 | ||
e1020413 | 154 | F<prove> is a command-line interface to the test-running functionality |
43f856ba | 155 | of L<Test::Harness>. It's an alternative to C<make test>. |
baf0caad RGS |
156 | |
157 | =item L<corelist> | |
158 | ||
43f856ba | 159 | A command-line front-end to L<Module::CoreList>, to query what modules |
baf0caad RGS |
160 | were shipped with given versions of perl. |
161 | ||
162 | =back | |
163 | ||
164 | =head2 General tools | |
165 | ||
166 | A few general-purpose tools are shipped with perl, mostly because they | |
167 | came along modules included in the perl distribution. | |
168 | ||
169 | =over 3 | |
170 | ||
43f856ba DB |
171 | =item L<encguess> |
172 | ||
173 | F<encguess> will attempt to guess the character encoding of files. | |
174 | ||
175 | =item L<json_pp> | |
176 | ||
177 | F<json_pp> is a pure Perl JSON converter and formatter. | |
178 | ||
baf0caad RGS |
179 | =item L<piconv> |
180 | ||
43f856ba | 181 | F<piconv> is a Perl version of L<iconv(1)>, a character encoding converter |
baf0caad | 182 | widely available for various Unixen today. This script was primarily a |
7c2e2b3a | 183 | technology demonstrator for Perl v5.8.0, but you can use piconv in the |
baf0caad RGS |
184 | place of iconv for virtually any case. |
185 | ||
186 | =item L<ptar> | |
187 | ||
188 | F<ptar> is a tar-like program, written in pure Perl. | |
189 | ||
190 | =item L<ptardiff> | |
191 | ||
192 | F<ptardiff> is a small utility that produces a diff between an extracted | |
634d76cd | 193 | archive and an unextracted one. (Note that this utility requires the |
43f856ba | 194 | L<Text::Diff> module to function properly; this module isn't distributed |
634d76cd | 195 | with perl, but is available from the CPAN.) |
baf0caad | 196 | |
deabda19 CBW |
197 | =item L<ptargrep> |
198 | ||
199 | F<ptargrep> is a utility to apply pattern matching to the contents of files | |
200 | in a tar archive. | |
201 | ||
baf0caad RGS |
202 | =item L<shasum> |
203 | ||
43f856ba | 204 | This utility, that comes with the L<Digest::SHA> module, is used to print |
baf0caad RGS |
205 | or verify SHA checksums. |
206 | ||
43f856ba DB |
207 | =item L<streamzip> |
208 | ||
209 | F<streamzip> compresses data streamed to STDIN into a streamed zip container. | |
210 | ||
08ad9465 CBW |
211 | =item L<zipdetails> |
212 | ||
43f856ba | 213 | F<zipdetails> displays information about the internal record structure of the zip file. |
08ad9465 CBW |
214 | It is not concerned with displaying any details of the compressed data stored in the zip file. |
215 | ||
baf0caad RGS |
216 | =back |
217 | ||
218 | =head2 Installation | |
219 | ||
220 | These utilities help manage extra Perl modules that don't come with the perl | |
221 | distribution. | |
222 | ||
223 | =over 3 | |
224 | ||
225 | =item L<cpan> | |
226 | ||
227 | F<cpan> is a command-line interface to CPAN.pm. It allows you to install | |
228 | modules or distributions from CPAN, or just get information about them, and | |
229 | a lot more. It is similar to the command line mode of the L<CPAN> module, | |
230 | ||
231 | perl -MCPAN -e shell | |
232 | ||
233 | =item L<instmodsh> | |
234 | ||
43f856ba | 235 | A little interface to L<ExtUtils::Installed> to examine installed modules, |
baf0caad RGS |
236 | validate your packlists and even create a tarball from an installed module. |
237 | ||
497711e7 GS |
238 | =back |
239 | ||
baf0caad | 240 | =head1 SEE ALSO |
497711e7 | 241 | |
43f856ba DB |
242 | L<perldoc>, L<pod2man>, L<pod2text>, L<pod2html>, L<pod2usage>, |
243 | L<podchecker>, L<splain>, L<pl2pm>, | |
244 | L<perlbug>, L<h2ph>, L<h2xs>, L<enc2xs>, | |
245 | L<xsubpp>, L<cpan>, L<encguess>, L<instmodsh>, L<json_pp>, | |
246 | L<piconv>, L<prove>, L<corelist>, L<ptar>, | |
247 | L<ptardiff>, L<shasum>, L<streamzip>, L<zipdetails> | |
497711e7 GS |
248 | |
249 | =cut |