X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/bb4e916294fdfa799a0a8b106d12e462bbe2a427..a2c6bb3c2ea3dd75c5b5617ba65ba208f7ff1079:/pod/perlutil.pod diff --git a/pod/perlutil.pod b/pod/perlutil.pod index 5da4860..859b66f 100644 --- a/pod/perlutil.pod +++ b/pod/perlutil.pod @@ -11,7 +11,9 @@ 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 +=head1 LIST OF UTILITIES + +=head2 Documentation =over 3 @@ -33,11 +35,10 @@ explanation) into a manpage, and then run F to display it; if F isn't available, F will be used instead and the output piped through your favourite pager. -=item L and L +=item L -As well as these two, there are two other converters: F will -produce HTML pages from POD, and F, which produces LaTeX -files. +As well as these two, there is another converter: F will +produce HTML pages from POD. =item L @@ -46,14 +47,6 @@ F will just extract the "USAGE" section; some of the utilities will automatically call F on themselves when you call them with C<-help>. -=item L - -F is a special case of F, 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 will extract this section for -a given file. - =item L If you're writing your own documentation in POD, the F @@ -64,7 +57,7 @@ utility will look for errors in your markup. F is an interface to L - paste in your error message to it, and it'll explain it for you. -=item L +=item C The C utility is not installed on your system but lives in the F directory of your Perl source kit; it converts all the @@ -73,55 +66,11 @@ 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 - -F converts F scripts to Perl programs; for example, C -on the simple F script C<{print $2}> will produce a Perl program -based around this code: - - while (<>) { - ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999); - print $Fld2; - } - -=item L - -Similarly, F converts F scripts to Perl programs. F run -on C will produce a Perl program based around this: - - while (<>) { - chomp; - s/foo/bar/g; - print if $printit; - } - -=item L - -Finally, F translates C commands to Perl equivalents which -use the L module. As an example, -C produces the following callback -subroutine for C: +=head2 Converters - 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 utility will help you convert old-style Perl 4 libraries to -new-style Perl5 modules. +To help you convert legacy programs to more modern Perl, the +L utility will help you convert old-style Perl 4 libraries +to new-style Perl5 modules. =head2 Administration @@ -131,10 +80,12 @@ new-style Perl5 modules. To display and change the libnet configuration run the libnetcfg command. -=item L +=item L -Query or change configuration of Perl modules that use Module::Build-based -configuration files for features and config data. +The F program is set up at Perl source code build time to test +the Perl version it was built under. It can be used after running C (or your platform's equivalent procedure) to verify that perl +and its libraries have been installed correctly. =back @@ -152,6 +103,12 @@ itself or any of the standard library modules back to the developers; please read through the documentation for F thoroughly before using it to submit a bug report. +=item L + +This program provides an easy way to send a thank-you message back to the +authors and maintainers of perl. It's just F installed under +another name. + =item L Back before Perl had the XS system for connecting with C libraries, @@ -161,40 +118,113 @@ around - the F<.ph> file should be created by running F on the corresponding F<.h> file. See the F documentation for more on how to convert a whole bunch of header files at once. -=item L and L - -F and F, 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 these days. - =item L F 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 +=item L + +F builds a Perl extension for use by Encode from either +Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). +Besides being used internally during the build process of the Encode +module, you can use F to add your own encoding to perl. +No knowledge of XS is necessary. + +=item L + +F is a compiler to convert Perl XS code into C code. +It is typically run by the makefiles created by L. + +F will compile XS code into C code by embedding the constructs +necessary to let C functions manipulate Perl values and creates the glue +necessary to let Perl access those functions. + +=item L + +F is a command-line interface to the test-running functionality +of F. It's an alternative to C. + +=item L + +A command-line front-end to C, to query what modules +were shipped with given versions of perl. + +=back + +=head2 General tools + +A few general-purpose tools are shipped with perl, mostly because they +came along modules included in the perl distribution. + +=over 3 + +=item L + +B is a Perl version of B, a character encoding converter +widely available for various Unixen today. This script was primarily a +technology demonstrator for Perl v5.8.0, but you can use piconv in the +place of iconv for virtually any case. + +=item L + +F is a tar-like program, written in pure Perl. + +=item L + +F is a small utility that produces a diff between an extracted +archive and an unextracted one. (Note that this utility requires the +C module to function properly; this module isn't distributed +with perl, but is available from the CPAN.) + +=item L + +F is a utility to apply pattern matching to the contents of files +in a tar archive. + +=item L + +This utility, that comes with the C module, is used to print +or verify SHA checksums. + +=item L + +L displays information about the internal record structure of the zip file. +It is not concerned with displaying any details of the compressed data stored in the zip file. + +=back + +=head2 Installation + +These utilities help manage extra Perl modules that don't come with the perl +distribution. + +=over 3 + +=item L + +F is a command-line interface to CPAN.pm. It allows you to install +modules or distributions from CPAN, or just get information about them, and +a lot more. It is similar to the command line mode of the L module, -Perl comes with a profiler, the F module. The -F utility analyzes the output of this profiler and tells you -which subroutines are taking up the most run time. See L -for more information. + perl -MCPAN -e shell -=item L +=item L -F is the interface to the experimental Perl compiler suite. +A little interface to ExtUtils::Installed to examine installed modules, +validate your packlists and even create a tarball from an installed module. =back -=head2 SEE ALSO +=head1 SEE ALSO L, L, L, -L, L, L, +L, L, L, L, L, -L, L, L, L, -L, L, L, -L, L, L, L, -L, L +C, L, L, +L, L, L, L, +L, L, L, L, L, L, L, +L, L, L =cut