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 manpage, 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 |
|
---|
38 | As well as these two, there are two other converters: F<pod2html> will
|
---|
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 | chomp;
|
---|
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 Administration
|
---|
127 |
|
---|
128 | =over 3
|
---|
129 |
|
---|
130 | =item L<libnetcfg|libnetcfg>
|
---|
131 |
|
---|
132 | To display and change the libnet configuration run the libnetcfg command.
|
---|
133 |
|
---|
134 | =back
|
---|
135 |
|
---|
136 | =head2 Development
|
---|
137 |
|
---|
138 | There are a set of utilities which help you in developing Perl programs,
|
---|
139 | and in particular, extending Perl with C.
|
---|
140 |
|
---|
141 | =over 3
|
---|
142 |
|
---|
143 | =item L<perlbug|perlbug>
|
---|
144 |
|
---|
145 | F<perlbug> is the recommended way to report bugs in the perl interpreter
|
---|
146 | itself or any of the standard library modules back to the developers;
|
---|
147 | please read through the documentation for F<perlbug> thoroughly before
|
---|
148 | using it to submit a bug report.
|
---|
149 |
|
---|
150 | =item L<h2ph|h2ph>
|
---|
151 |
|
---|
152 | Back before Perl had the XS system for connecting with C libraries,
|
---|
153 | programmers used to get library constants by reading through the C
|
---|
154 | header files. You may still see C<require 'syscall.ph'> or similar
|
---|
155 | around - the F<.ph> file should be created by running F<h2ph> on the
|
---|
156 | corresponding F<.h> file. See the F<h2ph> documentation for more on how
|
---|
157 | to convert a whole bunch of header files at once.
|
---|
158 |
|
---|
159 | =item L<c2ph|c2ph> and L<pstruct|pstruct>
|
---|
160 |
|
---|
161 | F<c2ph> and F<pstruct>, which are actually the same program but behave
|
---|
162 | differently depending on how they are called, provide another way of
|
---|
163 | getting at C with Perl - they'll convert C structures and union declarations
|
---|
164 | to Perl code. This is deprecated in favour of F<h2xs> these days.
|
---|
165 |
|
---|
166 | =item L<h2xs|h2xs>
|
---|
167 |
|
---|
168 | F<h2xs> converts C header files into XS modules, and will try and write
|
---|
169 | as much glue between C libraries and Perl modules as it can. It's also
|
---|
170 | very useful for creating skeletons of pure Perl modules.
|
---|
171 |
|
---|
172 | =item L<dprofpp|dprofpp>
|
---|
173 |
|
---|
174 | Perl comes with a profiler, the F<Devel::DProf> module. The
|
---|
175 | F<dprofpp> utility analyzes the output of this profiler and tells you
|
---|
176 | which subroutines are taking up the most run time. See L<Devel::DProf>
|
---|
177 | for more information.
|
---|
178 |
|
---|
179 | =item L<perlcc|perlcc>
|
---|
180 |
|
---|
181 | F<perlcc> is the interface to the experimental Perl compiler suite.
|
---|
182 |
|
---|
183 | =back
|
---|
184 |
|
---|
185 | =head2 SEE ALSO
|
---|
186 |
|
---|
187 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
|
---|
188 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>,
|
---|
189 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>,
|
---|
190 | L<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>,
|
---|
191 | L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>,
|
---|
192 | L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<dprofpp|dprofpp>,
|
---|
193 | L<Devel::DProf>, L<perlcc|perlcc>
|
---|
194 |
|
---|
195 | =cut
|
---|