You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
185 lines
6.2 KiB
185 lines
6.2 KiB
=head1 NAME
|
|
|
|
perlutil - utilities packaged with the Perl distribution
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Along with the Perl interpreter itself, the Perl distribution installs a
|
|
range of utilities on your system. There are also several utilities
|
|
which are used by the Perl distribution itself as part of the install
|
|
process. This document exists to list all of these utilities, explain
|
|
what they are for and provide pointers to each module's documentation,
|
|
if appropriate.
|
|
|
|
=head2 DOCUMENTATION
|
|
|
|
=over 3
|
|
|
|
=item L<perldoc|perldoc>
|
|
|
|
The main interface to Perl's documentation is C<perldoc>, although
|
|
if you're reading this, it's more than likely that you've already found
|
|
it. F<perldoc> will extract and format the documentation from any file
|
|
in the current directory, any Perl module installed on the system, or
|
|
any of the standard documentation pages, such as this one. Use
|
|
C<perldoc E<lt>nameE<gt>> to get information on any of the utilities
|
|
described in this document.
|
|
|
|
=item L<pod2man|pod2man> and L<pod2text|pod2text>
|
|
|
|
If it's run from a terminal, F<perldoc> will usually call F<pod2man> to
|
|
translate POD (Plain Old Documentation - see L<perlpod> for an
|
|
explanation) into a man page, and then run F<man> to display it; if
|
|
F<man> isn't available, F<pod2text> will be used instead and the output
|
|
piped through your favourite pager.
|
|
|
|
=item L<pod2html|pod2html> and L<pod2latex|pod2latex>
|
|
|
|
As well as these two, there are two other converters: F<pod2html> will
|
|
produce HTML pages from POD, and F<pod2latex>, which produces LaTeX
|
|
files.
|
|
|
|
=item L<pod2usage|pod2usage>
|
|
|
|
If you just want to know how to use the utilities described here,
|
|
F<pod2usage> will just extract the "USAGE" section; some of
|
|
the utilities will automatically call F<pod2usage> on themselves when
|
|
you call them with C<-help>.
|
|
|
|
=item L<podselect|podselect>
|
|
|
|
F<pod2usage> is a special case of F<podselect>, a utility to extract
|
|
named sections from documents written in POD. For instance, while
|
|
utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS"
|
|
sections: C<podselect -s "SYNOPSIS" ...> will extract this section for
|
|
a given file.
|
|
|
|
=item L<podchecker|podchecker>
|
|
|
|
If you're writing your own documentation in POD, the F<podchecker>
|
|
utility will look for errors in your markup.
|
|
|
|
=item L<splain|splain>
|
|
|
|
F<splain> is an interface to L<perldiag> - paste in your error message
|
|
to it, and it'll explain it for you.
|
|
|
|
=item L<roffitall|roffitall>
|
|
|
|
The C<roffitall> utility is not installed on your system but lives in
|
|
the F<pod/> directory of your Perl source kit; it converts all the
|
|
documentation from the distribution to F<*roff> format, and produces a
|
|
typeset PostScript or text file of the whole lot.
|
|
|
|
=back
|
|
|
|
=head2 CONVERTORS
|
|
|
|
To help you convert legacy programs to Perl, we've included three
|
|
conversion filters:
|
|
|
|
=over 3
|
|
|
|
=item L<a2p|a2p>
|
|
|
|
F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:>
|
|
on the simple F<awk> script C<{print $2}> will produce a Perl program
|
|
based around this code:
|
|
|
|
while (<>) {
|
|
($Fld1,$Fld2) = split(/[:\n]/, $_, 9999);
|
|
print $Fld2;
|
|
}
|
|
|
|
=item L<s2p|s2p>
|
|
|
|
Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run
|
|
on C<s/foo/bar> will produce a Perl program based around this:
|
|
|
|
while (<>) {
|
|
chomp;
|
|
s/foo/bar/g;
|
|
print if $printit;
|
|
}
|
|
|
|
=item L<find2perl|find2perl>
|
|
|
|
Finally, F<find2perl> translates C<find> commands to Perl equivalents which
|
|
use the L<File::Find|File::Find> module. As an example,
|
|
C<find2perl . -user root -perm 4000 -print> produces the following callback
|
|
subroutine for C<File::Find>:
|
|
|
|
sub wanted {
|
|
my ($dev,$ino,$mode,$nlink,$uid,$gid);
|
|
(($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
|
|
$uid == $uid{'root'}) &&
|
|
(($mode & 0777) == 04000);
|
|
print("$name\n");
|
|
}
|
|
|
|
=back
|
|
|
|
As well as these filters for converting other languages, the
|
|
L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to
|
|
new-style Perl5 modules.
|
|
|
|
=head2 Development
|
|
|
|
There are a set of utilities which help you in developing Perl programs,
|
|
and in particular, extending Perl with C.
|
|
|
|
=over 3
|
|
|
|
=item L<perlbug|perlbug>
|
|
|
|
F<perlbug> is the recommended way to report bugs in the perl interpreter
|
|
itself or any of the standard library modules back to the developers;
|
|
please read through the documentation for F<perlbug> thoroughly before
|
|
using it to submit a bug report.
|
|
|
|
=item L<h2ph|h2ph>
|
|
|
|
Back before Perl had the XS system for connecting with C libraries,
|
|
programmers used to get library constants by reading through the C
|
|
header files. You may still see C<require 'syscall.ph'> or similar
|
|
around - the F<.ph> file should be created by running F<h2ph> on the
|
|
corresponding F<.h> file. See the F<h2ph> documentation for more on how
|
|
to convert a whole bunch of header files at ones.
|
|
|
|
=item L<c2ph|c2ph> and L<pstruct|pstruct>
|
|
|
|
F<c2ph> and F<pstruct>, which are actually the same program but behave
|
|
differently depending on how they are called, provide another way of
|
|
getting at C with Perl - they'll convert C structures and union declarations
|
|
to Perl code. This is deprecated in favour of F<h2xs> these days.
|
|
|
|
=item L<h2xs|h2xs>
|
|
|
|
F<h2xs> converts C header files into XS modules, and will try and write
|
|
as much glue between C libraries and Perl modules as it can. It's also
|
|
very useful for creating skeletons of pure Perl modules.
|
|
|
|
=item L<dprofpp|dprofpp>
|
|
|
|
Perl comes with a profiler, the F<Devel::Dprof> module. The
|
|
F<dprofpp> utility analyzes the output of this profiler and tells you
|
|
which subroutines are taking up the most run time. See L<Devel::Dprof>
|
|
for more information.
|
|
|
|
=item L<perlcc|perlcc>
|
|
|
|
F<perlcc> is the interface to the experimental Perl compiler suite.
|
|
|
|
=back
|
|
|
|
=head2 SEE ALSO
|
|
|
|
L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
|
|
L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>,
|
|
L<podchecker|podchecker>, L<splain|splain>, L<perldiag>,
|
|
L<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>,
|
|
L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>,
|
|
L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<dprofpp|dprofpp>,
|
|
L<Devel::Dprof>, L<perlcc|perlcc>
|
|
|
|
=cut
|