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 GS |
78 | |
79 | To help you convert legacy programs to Perl, we've included three | |
80 | conversion filters: | |
81 | ||
82 | =over 3 | |
83 | ||
84 | =item L<a2p|a2p> | |
85 | ||
86 | F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:> | |
87 | on the simple F<awk> script C<{print $2}> will produce a Perl program | |
88 | based around this code: | |
89 | ||
90 | while (<>) { | |
944d48f7 | 91 | ($Fld1,$Fld2) = split(/[:\n]/, $_, -1); |
497711e7 GS |
92 | print $Fld2; |
93 | } | |
94 | ||
baf0caad | 95 | =item L<s2p|s2p> and L<psed> |
497711e7 GS |
96 | |
97 | Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run | |
98 | on C<s/foo/bar> will produce a Perl program based around this: | |
99 | ||
100 | while (<>) { | |
5b3eff12 | 101 | chomp; |
497711e7 GS |
102 | s/foo/bar/g; |
103 | print if $printit; | |
104 | } | |
105 | ||
baf0caad RGS |
106 | When invoked as F<psed>, it behaves as a F<sed> implementation, written in |
107 | Perl. | |
108 | ||
497711e7 GS |
109 | =item L<find2perl|find2perl> |
110 | ||
111 | Finally, F<find2perl> translates C<find> commands to Perl equivalents which | |
112 | use the L<File::Find|File::Find> module. As an example, | |
113 | C<find2perl . -user root -perm 4000 -print> produces the following callback | |
114 | subroutine for C<File::Find>: | |
115 | ||
116 | sub wanted { | |
117 | my ($dev,$ino,$mode,$nlink,$uid,$gid); | |
118 | (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && | |
119 | $uid == $uid{'root'}) && | |
120 | (($mode & 0777) == 04000); | |
121 | print("$name\n"); | |
122 | } | |
123 | ||
124 | =back | |
125 | ||
126 | As well as these filters for converting other languages, the | |
127 | L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to | |
128 | new-style Perl5 modules. | |
129 | ||
a6fb92f1 JH |
130 | =head2 Administration |
131 | ||
132 | =over 3 | |
133 | ||
baf0caad RGS |
134 | =item L<config_data|config_data> |
135 | ||
136 | Query or change configuration of Perl modules that use Module::Build-based | |
137 | configuration files for features and config data. | |
138 | ||
a6fb92f1 JH |
139 | =item L<libnetcfg|libnetcfg> |
140 | ||
141 | To display and change the libnet configuration run the libnetcfg command. | |
142 | ||
baf0caad | 143 | =item L<perlivp> |
bb4e9162 | 144 | |
baf0caad RGS |
145 | The F<perlivp> program is set up at Perl source code build time to test |
146 | the Perl version it was built under. It can be used after running C<make | |
147 | install> (or your platform's equivalent procedure) to verify that perl | |
148 | and its libraries have been installed correctly. | |
bb4e9162 | 149 | |
a6fb92f1 JH |
150 | =back |
151 | ||
497711e7 GS |
152 | =head2 Development |
153 | ||
154 | There are a set of utilities which help you in developing Perl programs, | |
155 | and in particular, extending Perl with C. | |
156 | ||
157 | =over 3 | |
158 | ||
159 | =item L<perlbug|perlbug> | |
160 | ||
161 | F<perlbug> is the recommended way to report bugs in the perl interpreter | |
162 | itself or any of the standard library modules back to the developers; | |
163 | please read through the documentation for F<perlbug> thoroughly before | |
164 | using it to submit a bug report. | |
165 | ||
f9615397 | 166 | =item L<perlthanks|perlbug> |
03f3e794 RGS |
167 | |
168 | This program provides an easy way to send a thank-you message back to the | |
169 | authors and maintainers of perl. It's just F<perlbug> installed under | |
170 | another name. | |
171 | ||
497711e7 GS |
172 | =item L<h2ph|h2ph> |
173 | ||
174 | Back before Perl had the XS system for connecting with C libraries, | |
175 | programmers used to get library constants by reading through the C | |
176 | header files. You may still see C<require 'syscall.ph'> or similar | |
177 | around - the F<.ph> file should be created by running F<h2ph> on the | |
178 | corresponding F<.h> file. See the F<h2ph> documentation for more on how | |
c06dc7de | 179 | to convert a whole bunch of header files at once. |
497711e7 GS |
180 | |
181 | =item L<c2ph|c2ph> and L<pstruct|pstruct> | |
182 | ||
183 | F<c2ph> and F<pstruct>, which are actually the same program but behave | |
184 | differently depending on how they are called, provide another way of | |
185 | getting at C with Perl - they'll convert C structures and union declarations | |
186 | to Perl code. This is deprecated in favour of F<h2xs> these days. | |
187 | ||
188 | =item L<h2xs|h2xs> | |
189 | ||
190 | F<h2xs> converts C header files into XS modules, and will try and write | |
191 | as much glue between C libraries and Perl modules as it can. It's also | |
192 | very useful for creating skeletons of pure Perl modules. | |
193 | ||
baf0caad RGS |
194 | =item L<enc2xs> |
195 | ||
196 | F<enc2xs> builds a Perl extension for use by Encode from either | |
197 | Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). | |
198 | Besides being used internally during the build process of the Encode | |
199 | module, you can use F<enc2xs> to add your own encoding to perl. | |
200 | No knowledge of XS is necessary. | |
201 | ||
202 | =item L<xsubpp> | |
203 | ||
204 | F<xsubpp> is a compiler to convert Perl XS code into C code. | |
205 | It is typically run by the makefiles created by L<ExtUtils::MakeMaker>. | |
206 | ||
207 | F<xsubpp> will compile XS code into C code by embedding the constructs | |
208 | necessary to let C functions manipulate Perl values and creates the glue | |
209 | necessary to let Perl access those functions. | |
210 | ||
baf0caad RGS |
211 | =item L<prove> |
212 | ||
e1020413 | 213 | F<prove> is a command-line interface to the test-running functionality |
baf0caad RGS |
214 | of F<Test::Harness>. It's an alternative to C<make test>. |
215 | ||
216 | =item L<corelist> | |
217 | ||
218 | A command-line front-end to C<Module::CoreList>, to query what modules | |
219 | were shipped with given versions of perl. | |
220 | ||
221 | =back | |
222 | ||
223 | =head2 General tools | |
224 | ||
225 | A few general-purpose tools are shipped with perl, mostly because they | |
226 | came along modules included in the perl distribution. | |
227 | ||
228 | =over 3 | |
229 | ||
230 | =item L<piconv> | |
231 | ||
232 | B<piconv> is a Perl version of B<iconv>, a character encoding converter | |
233 | widely available for various Unixen today. This script was primarily a | |
7c2e2b3a | 234 | technology demonstrator for Perl v5.8.0, but you can use piconv in the |
baf0caad RGS |
235 | place of iconv for virtually any case. |
236 | ||
237 | =item L<ptar> | |
238 | ||
239 | F<ptar> is a tar-like program, written in pure Perl. | |
240 | ||
241 | =item L<ptardiff> | |
242 | ||
243 | F<ptardiff> is a small utility that produces a diff between an extracted | |
634d76cd RGS |
244 | archive and an unextracted one. (Note that this utility requires the |
245 | C<Text::Diff> module to function properly; this module isn't distributed | |
246 | with perl, but is available from the CPAN.) | |
baf0caad | 247 | |
deabda19 CBW |
248 | =item L<ptargrep> |
249 | ||
250 | F<ptargrep> is a utility to apply pattern matching to the contents of files | |
251 | in a tar archive. | |
252 | ||
baf0caad RGS |
253 | =item L<shasum> |
254 | ||
255 | This utility, that comes with the C<Digest::SHA> module, is used to print | |
256 | or verify SHA checksums. | |
257 | ||
08ad9465 CBW |
258 | =item L<zipdetails> |
259 | ||
260 | L<zipdetails> displays information about the internal record structure of the zip file. | |
261 | It is not concerned with displaying any details of the compressed data stored in the zip file. | |
262 | ||
baf0caad RGS |
263 | =back |
264 | ||
265 | =head2 Installation | |
266 | ||
267 | These utilities help manage extra Perl modules that don't come with the perl | |
268 | distribution. | |
269 | ||
270 | =over 3 | |
271 | ||
272 | =item L<cpan> | |
273 | ||
274 | F<cpan> is a command-line interface to CPAN.pm. It allows you to install | |
275 | modules or distributions from CPAN, or just get information about them, and | |
276 | a lot more. It is similar to the command line mode of the L<CPAN> module, | |
277 | ||
278 | perl -MCPAN -e shell | |
279 | ||
280 | =item L<instmodsh> | |
281 | ||
282 | A little interface to ExtUtils::Installed to examine installed modules, | |
283 | validate your packlists and even create a tarball from an installed module. | |
284 | ||
497711e7 GS |
285 | =back |
286 | ||
baf0caad | 287 | =head1 SEE ALSO |
497711e7 GS |
288 | |
289 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, | |
290 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, | |
291 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>, | |
f9615397 | 292 | C<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>, |
497711e7 | 293 | L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>, |
c9dab4e9 | 294 | L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>, |
fb598ba5 | 295 | L<cpan>, L<instmodsh>, L<piconv>, L<prove>, |
08ad9465 | 296 | L<corelist>, L<ptar>, L<ptardiff>, L<shasum>, L<zipdetails> |
497711e7 GS |
297 | |
298 | =cut |