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 | ||
14 | =head2 DOCUMENTATION | |
15 | ||
16 | =over 3 | |
17 | ||
18 | =item L<perldoc|perldoc> | |
19 | ||
20 | The main interface to Perl's documentation is C<perldoc>, although | |
21 | if you're reading this, it's more than likely that you've already found | |
22 | it. F<perldoc> will extract and format the documentation from any file | |
23 | in the current directory, any Perl module installed on the system, or | |
24 | any of the standard documentation pages, such as this one. Use | |
25 | C<perldoc E<lt>nameE<gt>> to get information on any of the utilities | |
26 | described in this document. | |
27 | ||
28 | =item L<pod2man|pod2man> and L<pod2text|pod2text> | |
29 | ||
30 | If it's run from a terminal, F<perldoc> will usually call F<pod2man> to | |
31 | translate POD (Plain Old Documentation - see L<perlpod> for an | |
32 | explanation) into a man page, and then run F<man> to display it; if | |
33 | F<man> isn't available, F<pod2text> will be used instead and the output | |
34 | piped through your favourite pager. | |
35 | ||
36 | =item L<pod2html|pod2html> and L<pod2latex|pod2latex> | |
37 | ||
a31a806a | 38 | As well as these two, there are two other converters: F<pod2html> will |
497711e7 GS |
39 | produce HTML pages from POD, and F<pod2latex>, which produces LaTeX |
40 | files. | |
41 | ||
42 | =item L<pod2usage|pod2usage> | |
43 | ||
44 | If you just want to know how to use the utilities described here, | |
45 | F<pod2usage> will just extract the "USAGE" section; some of | |
46 | the utilities will automatically call F<pod2usage> on themselves when | |
47 | you call them with C<-help>. | |
48 | ||
49 | =item L<podselect|podselect> | |
50 | ||
51 | F<pod2usage> is a special case of F<podselect>, a utility to extract | |
52 | named sections from documents written in POD. For instance, while | |
53 | utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS" | |
54 | sections: C<podselect -s "SYNOPSIS" ...> will extract this section for | |
55 | a given file. | |
56 | ||
57 | =item L<podchecker|podchecker> | |
58 | ||
59 | If you're writing your own documentation in POD, the F<podchecker> | |
60 | utility will look for errors in your markup. | |
61 | ||
62 | =item L<splain|splain> | |
63 | ||
64 | F<splain> is an interface to L<perldiag> - paste in your error message | |
65 | to it, and it'll explain it for you. | |
66 | ||
67 | =item L<roffitall|roffitall> | |
68 | ||
69 | The C<roffitall> utility is not installed on your system but lives in | |
70 | the F<pod/> directory of your Perl source kit; it converts all the | |
71 | documentation from the distribution to F<*roff> format, and produces a | |
72 | typeset PostScript or text file of the whole lot. | |
73 | ||
74 | =back | |
75 | ||
76 | =head2 CONVERTORS | |
77 | ||
78 | To help you convert legacy programs to Perl, we've included three | |
79 | conversion filters: | |
80 | ||
81 | =over 3 | |
82 | ||
83 | =item L<a2p|a2p> | |
84 | ||
85 | F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:> | |
86 | on the simple F<awk> script C<{print $2}> will produce a Perl program | |
87 | based around this code: | |
88 | ||
89 | while (<>) { | |
90 | ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999); | |
91 | print $Fld2; | |
92 | } | |
93 | ||
94 | =item L<s2p|s2p> | |
95 | ||
96 | Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run | |
97 | on C<s/foo/bar> will produce a Perl program based around this: | |
98 | ||
99 | while (<>) { | |
100 | chop; | |
101 | s/foo/bar/g; | |
102 | print if $printit; | |
103 | } | |
104 | ||
105 | =item L<find2perl|find2perl> | |
106 | ||
107 | Finally, F<find2perl> translates C<find> commands to Perl equivalents which | |
108 | use the L<File::Find|File::Find> module. As an example, | |
109 | C<find2perl . -user root -perm 4000 -print> produces the following callback | |
110 | subroutine for C<File::Find>: | |
111 | ||
112 | sub wanted { | |
113 | my ($dev,$ino,$mode,$nlink,$uid,$gid); | |
114 | (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && | |
115 | $uid == $uid{'root'}) && | |
116 | (($mode & 0777) == 04000); | |
117 | print("$name\n"); | |
118 | } | |
119 | ||
120 | =back | |
121 | ||
122 | As well as these filters for converting other languages, the | |
123 | L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to | |
124 | new-style Perl5 modules. | |
125 | ||
126 | =head2 Development | |
127 | ||
128 | There are a set of utilities which help you in developing Perl programs, | |
129 | and in particular, extending Perl with C. | |
130 | ||
131 | =over 3 | |
132 | ||
133 | =item L<perlbug|perlbug> | |
134 | ||
135 | F<perlbug> is the recommended way to report bugs in the perl interpreter | |
136 | itself or any of the standard library modules back to the developers; | |
137 | please read through the documentation for F<perlbug> thoroughly before | |
138 | using it to submit a bug report. | |
139 | ||
140 | =item L<h2ph|h2ph> | |
141 | ||
142 | Back before Perl had the XS system for connecting with C libraries, | |
143 | programmers used to get library constants by reading through the C | |
144 | header files. You may still see C<require 'syscall.ph'> or similar | |
145 | around - the F<.ph> file should be created by running F<h2ph> on the | |
146 | corresponding F<.h> file. See the F<h2ph> documentation for more on how | |
147 | to convert a whole bunch of header files at ones. | |
148 | ||
149 | =item L<c2ph|c2ph> and L<pstruct|pstruct> | |
150 | ||
151 | F<c2ph> and F<pstruct>, which are actually the same program but behave | |
152 | differently depending on how they are called, provide another way of | |
153 | getting at C with Perl - they'll convert C structures and union declarations | |
154 | to Perl code. This is deprecated in favour of F<h2xs> these days. | |
155 | ||
156 | =item L<h2xs|h2xs> | |
157 | ||
158 | F<h2xs> converts C header files into XS modules, and will try and write | |
159 | as much glue between C libraries and Perl modules as it can. It's also | |
160 | very useful for creating skeletons of pure Perl modules. | |
161 | ||
162 | =item L<dprofpp|dprofpp> | |
163 | ||
164 | Perl comes with a profiler, the F<Devel::Dprof> module. The | |
165 | F<dprofpp> utility analyzes the output of this profiler and tells you | |
166 | which subroutines are taking up the most run time. See L<Devel::Dprof> | |
167 | for more information. | |
168 | ||
169 | =item L<perlcc|perlcc> | |
170 | ||
171 | F<perlcc> is the interface to the experimental Perl compiler suite. | |
172 | ||
173 | =back | |
174 | ||
175 | =head2 SEE ALSO | |
176 | ||
177 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, | |
178 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, | |
179 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>, | |
180 | L<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>, | |
181 | L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>, | |
182 | L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<dprofpp|dprofpp>, | |
cdf0af66 | 183 | L<Devel::Dprof>, L<perlcc|perlcc> |
497711e7 GS |
184 | |
185 | =cut |