| 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 | =head1 LIST OF UTILITIES |
| 15 | |
| 16 | =head2 Documentation |
| 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 |
| 34 | explanation) into a manpage, and then run F<man> to display it; if |
| 35 | F<man> isn't available, F<pod2text> will be used instead and the output |
| 36 | piped through your favourite pager. |
| 37 | |
| 38 | =item L<pod2html|pod2html> |
| 39 | |
| 40 | As well as these two, there is another converter: F<pod2html> will |
| 41 | produce HTML pages from POD. |
| 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 | |
| 68 | =item C<roffitall> |
| 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 | |
| 77 | =head2 Converters |
| 78 | |
| 79 | To help you convert legacy programs to more modern Perl, the |
| 80 | L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries |
| 81 | to new-style Perl5 modules. |
| 82 | |
| 83 | =head2 Administration |
| 84 | |
| 85 | =over 3 |
| 86 | |
| 87 | =item L<libnetcfg|libnetcfg> |
| 88 | |
| 89 | To display and change the libnet configuration run the libnetcfg command. |
| 90 | |
| 91 | =item L<perlivp> |
| 92 | |
| 93 | The F<perlivp> program is set up at Perl source code build time to test |
| 94 | the Perl version it was built under. It can be used after running C<make |
| 95 | install> (or your platform's equivalent procedure) to verify that perl |
| 96 | and its libraries have been installed correctly. |
| 97 | |
| 98 | =back |
| 99 | |
| 100 | =head2 Development |
| 101 | |
| 102 | There are a set of utilities which help you in developing Perl programs, |
| 103 | and in particular, extending Perl with C. |
| 104 | |
| 105 | =over 3 |
| 106 | |
| 107 | =item L<perlbug|perlbug> |
| 108 | |
| 109 | F<perlbug> is the recommended way to report bugs in the perl interpreter |
| 110 | itself or any of the standard library modules back to the developers; |
| 111 | please read through the documentation for F<perlbug> thoroughly before |
| 112 | using it to submit a bug report. |
| 113 | |
| 114 | =item L<perlthanks|perlbug> |
| 115 | |
| 116 | This program provides an easy way to send a thank-you message back to the |
| 117 | authors and maintainers of perl. It's just F<perlbug> installed under |
| 118 | another name. |
| 119 | |
| 120 | =item L<h2ph|h2ph> |
| 121 | |
| 122 | Back before Perl had the XS system for connecting with C libraries, |
| 123 | programmers used to get library constants by reading through the C |
| 124 | header files. You may still see C<require 'syscall.ph'> or similar |
| 125 | around - the F<.ph> file should be created by running F<h2ph> on the |
| 126 | corresponding F<.h> file. See the F<h2ph> documentation for more on how |
| 127 | to convert a whole bunch of header files at once. |
| 128 | |
| 129 | =item L<c2ph|c2ph> and L<pstruct|pstruct> |
| 130 | |
| 131 | F<c2ph> and F<pstruct>, which are actually the same program but behave |
| 132 | differently depending on how they are called, provide another way of |
| 133 | getting at C with Perl - they'll convert C structures and union declarations |
| 134 | to Perl code. This is deprecated in favour of F<h2xs> these days. |
| 135 | |
| 136 | =item L<h2xs|h2xs> |
| 137 | |
| 138 | F<h2xs> converts C header files into XS modules, and will try and write |
| 139 | as much glue between C libraries and Perl modules as it can. It's also |
| 140 | very useful for creating skeletons of pure Perl modules. |
| 141 | |
| 142 | =item L<enc2xs> |
| 143 | |
| 144 | F<enc2xs> builds a Perl extension for use by Encode from either |
| 145 | Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). |
| 146 | Besides being used internally during the build process of the Encode |
| 147 | module, you can use F<enc2xs> to add your own encoding to perl. |
| 148 | No knowledge of XS is necessary. |
| 149 | |
| 150 | =item L<xsubpp> |
| 151 | |
| 152 | F<xsubpp> is a compiler to convert Perl XS code into C code. |
| 153 | It is typically run by the makefiles created by L<ExtUtils::MakeMaker>. |
| 154 | |
| 155 | F<xsubpp> will compile XS code into C code by embedding the constructs |
| 156 | necessary to let C functions manipulate Perl values and creates the glue |
| 157 | necessary to let Perl access those functions. |
| 158 | |
| 159 | =item L<prove> |
| 160 | |
| 161 | F<prove> is a command-line interface to the test-running functionality |
| 162 | of F<Test::Harness>. It's an alternative to C<make test>. |
| 163 | |
| 164 | =item L<corelist> |
| 165 | |
| 166 | A command-line front-end to C<Module::CoreList>, to query what modules |
| 167 | were shipped with given versions of perl. |
| 168 | |
| 169 | =back |
| 170 | |
| 171 | =head2 General tools |
| 172 | |
| 173 | A few general-purpose tools are shipped with perl, mostly because they |
| 174 | came along modules included in the perl distribution. |
| 175 | |
| 176 | =over 3 |
| 177 | |
| 178 | =item L<piconv> |
| 179 | |
| 180 | B<piconv> is a Perl version of B<iconv>, a character encoding converter |
| 181 | widely available for various Unixen today. This script was primarily a |
| 182 | technology demonstrator for Perl v5.8.0, but you can use piconv in the |
| 183 | place of iconv for virtually any case. |
| 184 | |
| 185 | =item L<ptar> |
| 186 | |
| 187 | F<ptar> is a tar-like program, written in pure Perl. |
| 188 | |
| 189 | =item L<ptardiff> |
| 190 | |
| 191 | F<ptardiff> is a small utility that produces a diff between an extracted |
| 192 | archive and an unextracted one. (Note that this utility requires the |
| 193 | C<Text::Diff> module to function properly; this module isn't distributed |
| 194 | with perl, but is available from the CPAN.) |
| 195 | |
| 196 | =item L<ptargrep> |
| 197 | |
| 198 | F<ptargrep> is a utility to apply pattern matching to the contents of files |
| 199 | in a tar archive. |
| 200 | |
| 201 | =item L<shasum> |
| 202 | |
| 203 | This utility, that comes with the C<Digest::SHA> module, is used to print |
| 204 | or verify SHA checksums. |
| 205 | |
| 206 | =item L<zipdetails> |
| 207 | |
| 208 | L<zipdetails> displays information about the internal record structure of the zip file. |
| 209 | It is not concerned with displaying any details of the compressed data stored in the zip file. |
| 210 | |
| 211 | =back |
| 212 | |
| 213 | =head2 Installation |
| 214 | |
| 215 | These utilities help manage extra Perl modules that don't come with the perl |
| 216 | distribution. |
| 217 | |
| 218 | =over 3 |
| 219 | |
| 220 | =item L<cpan> |
| 221 | |
| 222 | F<cpan> is a command-line interface to CPAN.pm. It allows you to install |
| 223 | modules or distributions from CPAN, or just get information about them, and |
| 224 | a lot more. It is similar to the command line mode of the L<CPAN> module, |
| 225 | |
| 226 | perl -MCPAN -e shell |
| 227 | |
| 228 | =item L<instmodsh> |
| 229 | |
| 230 | A little interface to ExtUtils::Installed to examine installed modules, |
| 231 | validate your packlists and even create a tarball from an installed module. |
| 232 | |
| 233 | =back |
| 234 | |
| 235 | =head1 SEE ALSO |
| 236 | |
| 237 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, |
| 238 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, |
| 239 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>, |
| 240 | C<roffitall|roffitall>, L<File::Find|File::Find>, L<pl2pm|pl2pm>, |
| 241 | L<perlbug|perlbug>, L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, |
| 242 | L<xsubpp>, L<cpan>, L<instmodsh>, L<piconv>, L<prove>, L<corelist>, L<ptar>, |
| 243 | L<ptardiff>, L<shasum>, L<zipdetails> |
| 244 | |
| 245 | =cut |