| 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> and L<pod2latex|pod2latex> |
| 39 | |
| 40 | As well as these two, there are two other converters: F<pod2html> will |
| 41 | produce HTML pages from POD, and F<pod2latex>, which produces LaTeX |
| 42 | files. |
| 43 | |
| 44 | =item L<pod2usage|pod2usage> |
| 45 | |
| 46 | If you just want to know how to use the utilities described here, |
| 47 | F<pod2usage> will just extract the "USAGE" section; some of |
| 48 | the utilities will automatically call F<pod2usage> on themselves when |
| 49 | you call them with C<-help>. |
| 50 | |
| 51 | =item L<podselect|podselect> |
| 52 | |
| 53 | F<pod2usage> is a special case of F<podselect>, a utility to extract |
| 54 | named sections from documents written in POD. For instance, while |
| 55 | utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS" |
| 56 | sections: C<podselect -s "SYNOPSIS" ...> will extract this section for |
| 57 | a given file. |
| 58 | |
| 59 | =item L<podchecker|podchecker> |
| 60 | |
| 61 | If you're writing your own documentation in POD, the F<podchecker> |
| 62 | utility will look for errors in your markup. |
| 63 | |
| 64 | =item L<splain|splain> |
| 65 | |
| 66 | F<splain> is an interface to L<perldiag> - paste in your error message |
| 67 | to it, and it'll explain it for you. |
| 68 | |
| 69 | =item C<roffitall> |
| 70 | |
| 71 | The C<roffitall> utility is not installed on your system but lives in |
| 72 | the F<pod/> directory of your Perl source kit; it converts all the |
| 73 | documentation from the distribution to F<*roff> format, and produces a |
| 74 | typeset PostScript or text file of the whole lot. |
| 75 | |
| 76 | =back |
| 77 | |
| 78 | =head2 Converters |
| 79 | |
| 80 | To help you convert legacy programs to Perl, we've included three |
| 81 | conversion filters: |
| 82 | |
| 83 | =over 3 |
| 84 | |
| 85 | =item L<a2p|a2p> |
| 86 | |
| 87 | F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:> |
| 88 | on the simple F<awk> script C<{print $2}> will produce a Perl program |
| 89 | based around this code: |
| 90 | |
| 91 | while (<>) { |
| 92 | ($Fld1,$Fld2) = split(/[:\n]/, $_, -1); |
| 93 | print $Fld2; |
| 94 | } |
| 95 | |
| 96 | =item L<s2p|s2p> and L<psed> |
| 97 | |
| 98 | Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run |
| 99 | on C<s/foo/bar> will produce a Perl program based around this: |
| 100 | |
| 101 | while (<>) { |
| 102 | chomp; |
| 103 | s/foo/bar/g; |
| 104 | print if $printit; |
| 105 | } |
| 106 | |
| 107 | When invoked as F<psed>, it behaves as a F<sed> implementation, written in |
| 108 | Perl. |
| 109 | |
| 110 | =item L<find2perl|find2perl> |
| 111 | |
| 112 | Finally, F<find2perl> translates C<find> commands to Perl equivalents which |
| 113 | use the L<File::Find|File::Find> module. As an example, |
| 114 | C<find2perl . -user root -perm 4000 -print> produces the following callback |
| 115 | subroutine for C<File::Find>: |
| 116 | |
| 117 | sub wanted { |
| 118 | my ($dev,$ino,$mode,$nlink,$uid,$gid); |
| 119 | (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && |
| 120 | $uid == $uid{'root'}) && |
| 121 | (($mode & 0777) == 04000); |
| 122 | print("$name\n"); |
| 123 | } |
| 124 | |
| 125 | =back |
| 126 | |
| 127 | As well as these filters for converting other languages, the |
| 128 | L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to |
| 129 | new-style Perl5 modules. |
| 130 | |
| 131 | =head2 Administration |
| 132 | |
| 133 | =over 3 |
| 134 | |
| 135 | =item L<config_data|config_data> |
| 136 | |
| 137 | Query or change configuration of Perl modules that use Module::Build-based |
| 138 | configuration files for features and config data. |
| 139 | |
| 140 | =item L<libnetcfg|libnetcfg> |
| 141 | |
| 142 | To display and change the libnet configuration run the libnetcfg command. |
| 143 | |
| 144 | =item L<perlivp> |
| 145 | |
| 146 | The F<perlivp> program is set up at Perl source code build time to test |
| 147 | the Perl version it was built under. It can be used after running C<make |
| 148 | install> (or your platform's equivalent procedure) to verify that perl |
| 149 | and its libraries have been installed correctly. |
| 150 | |
| 151 | =back |
| 152 | |
| 153 | =head2 Development |
| 154 | |
| 155 | There are a set of utilities which help you in developing Perl programs, |
| 156 | and in particular, extending Perl with C. |
| 157 | |
| 158 | =over 3 |
| 159 | |
| 160 | =item L<perlbug|perlbug> |
| 161 | |
| 162 | F<perlbug> is the recommended way to report bugs in the perl interpreter |
| 163 | itself or any of the standard library modules back to the developers; |
| 164 | please read through the documentation for F<perlbug> thoroughly before |
| 165 | using it to submit a bug report. |
| 166 | |
| 167 | =item L<perlthanks|perlbug> |
| 168 | |
| 169 | This program provides an easy way to send a thank-you message back to the |
| 170 | authors and maintainers of perl. It's just F<perlbug> installed under |
| 171 | another name. |
| 172 | |
| 173 | =item L<h2ph|h2ph> |
| 174 | |
| 175 | Back before Perl had the XS system for connecting with C libraries, |
| 176 | programmers used to get library constants by reading through the C |
| 177 | header files. You may still see C<require 'syscall.ph'> or similar |
| 178 | around - the F<.ph> file should be created by running F<h2ph> on the |
| 179 | corresponding F<.h> file. See the F<h2ph> documentation for more on how |
| 180 | to convert a whole bunch of header files at once. |
| 181 | |
| 182 | =item L<c2ph|c2ph> and L<pstruct|pstruct> |
| 183 | |
| 184 | F<c2ph> and F<pstruct>, which are actually the same program but behave |
| 185 | differently depending on how they are called, provide another way of |
| 186 | getting at C with Perl - they'll convert C structures and union declarations |
| 187 | to Perl code. This is deprecated in favour of F<h2xs> these days. |
| 188 | |
| 189 | =item L<h2xs|h2xs> |
| 190 | |
| 191 | F<h2xs> converts C header files into XS modules, and will try and write |
| 192 | as much glue between C libraries and Perl modules as it can. It's also |
| 193 | very useful for creating skeletons of pure Perl modules. |
| 194 | |
| 195 | =item L<enc2xs> |
| 196 | |
| 197 | F<enc2xs> builds a Perl extension for use by Encode from either |
| 198 | Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc). |
| 199 | Besides being used internally during the build process of the Encode |
| 200 | module, you can use F<enc2xs> to add your own encoding to perl. |
| 201 | No knowledge of XS is necessary. |
| 202 | |
| 203 | =item L<xsubpp> |
| 204 | |
| 205 | F<xsubpp> is a compiler to convert Perl XS code into C code. |
| 206 | It is typically run by the makefiles created by L<ExtUtils::MakeMaker>. |
| 207 | |
| 208 | F<xsubpp> will compile XS code into C code by embedding the constructs |
| 209 | necessary to let C functions manipulate Perl values and creates the glue |
| 210 | necessary to let Perl access those functions. |
| 211 | |
| 212 | =item L<prove> |
| 213 | |
| 214 | F<prove> is a command-line interface to the test-running functionality |
| 215 | of F<Test::Harness>. It's an alternative to C<make test>. |
| 216 | |
| 217 | =item L<corelist> |
| 218 | |
| 219 | A command-line front-end to C<Module::CoreList>, to query what modules |
| 220 | were shipped with given versions of perl. |
| 221 | |
| 222 | =back |
| 223 | |
| 224 | =head2 General tools |
| 225 | |
| 226 | A few general-purpose tools are shipped with perl, mostly because they |
| 227 | came along modules included in the perl distribution. |
| 228 | |
| 229 | =over 3 |
| 230 | |
| 231 | =item L<piconv> |
| 232 | |
| 233 | B<piconv> is a Perl version of B<iconv>, a character encoding converter |
| 234 | widely available for various Unixen today. This script was primarily a |
| 235 | technology demonstrator for Perl v5.8.0, but you can use piconv in the |
| 236 | place of iconv for virtually any case. |
| 237 | |
| 238 | =item L<ptar> |
| 239 | |
| 240 | F<ptar> is a tar-like program, written in pure Perl. |
| 241 | |
| 242 | =item L<ptardiff> |
| 243 | |
| 244 | F<ptardiff> is a small utility that produces a diff between an extracted |
| 245 | archive and an unextracted one. (Note that this utility requires the |
| 246 | C<Text::Diff> module to function properly; this module isn't distributed |
| 247 | with perl, but is available from the CPAN.) |
| 248 | |
| 249 | =item L<ptargrep> |
| 250 | |
| 251 | F<ptargrep> is a utility to apply pattern matching to the contents of files |
| 252 | in a tar archive. |
| 253 | |
| 254 | =item L<shasum> |
| 255 | |
| 256 | This utility, that comes with the C<Digest::SHA> module, is used to print |
| 257 | or verify SHA checksums. |
| 258 | |
| 259 | =item L<zipdetails> |
| 260 | |
| 261 | L<zipdetails> displays information about the internal record structure of the zip file. |
| 262 | It is not concerned with displaying any details of the compressed data stored in the zip file. |
| 263 | |
| 264 | =back |
| 265 | |
| 266 | =head2 Installation |
| 267 | |
| 268 | These utilities help manage extra Perl modules that don't come with the perl |
| 269 | distribution. |
| 270 | |
| 271 | =over 3 |
| 272 | |
| 273 | =item L<cpan> |
| 274 | |
| 275 | F<cpan> is a command-line interface to CPAN.pm. It allows you to install |
| 276 | modules or distributions from CPAN, or just get information about them, and |
| 277 | a lot more. It is similar to the command line mode of the L<CPAN> module, |
| 278 | |
| 279 | perl -MCPAN -e shell |
| 280 | |
| 281 | =item L<cpanp> |
| 282 | |
| 283 | F<cpanp> is, like F<cpan>, a command-line interface to the CPAN, using |
| 284 | the C<CPANPLUS> module as a back-end. It can be used interactively or |
| 285 | imperatively. |
| 286 | |
| 287 | =item L<cpan2dist> |
| 288 | |
| 289 | F<cpan2dist> is a tool to create distributions (or packages) from CPAN |
| 290 | modules, then suitable for your package manager of choice. Support for |
| 291 | specific formats are available from CPAN as C<CPANPLUS::Dist::*> modules. |
| 292 | |
| 293 | =item L<instmodsh> |
| 294 | |
| 295 | A little interface to ExtUtils::Installed to examine installed modules, |
| 296 | validate your packlists and even create a tarball from an installed module. |
| 297 | |
| 298 | =back |
| 299 | |
| 300 | =head1 SEE ALSO |
| 301 | |
| 302 | L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, |
| 303 | L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, |
| 304 | L<podchecker|podchecker>, L<splain|splain>, L<perldiag>, |
| 305 | C<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>, |
| 306 | L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>, |
| 307 | L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>, |
| 308 | L<cpan>, L<cpanp>, L<cpan2dist>, L<instmodsh>, L<piconv>, L<prove>, |
| 309 | L<corelist>, L<ptar>, L<ptardiff>, L<shasum>, L<zipdetails> |
| 310 | |
| 311 | =cut |