Hash::Util tests should check if Hash::Util has been built, not
[perl.git] / pod / perlfaq3.pod
1 =head1 NAME
2
3 perlfaq3 - Programming Tools ($Revision: 1.56 $, $Date: 2005/12/31 00:54:37 $)
4
5 =head1 DESCRIPTION
6
7 This section of the FAQ answers questions related to programmer tools
8 and programming support.
9
10 =head2 How do I do (anything)?
11
12 Have you looked at CPAN (see L<perlfaq2>)?  The chances are that
13 someone has already written a module that can solve your problem.
14 Have you read the appropriate manpages?  Here's a brief index:
15
16         Basics          perldata, perlvar, perlsyn, perlop, perlsub
17         Execution       perlrun, perldebug
18         Functions       perlfunc
19         Objects         perlref, perlmod, perlobj, perltie
20         Data Structures perlref, perllol, perldsc
21         Modules         perlmod, perlmodlib, perlsub
22         Regexes         perlre, perlfunc, perlop, perllocale
23         Moving to perl5 perltrap, perl
24         Linking w/C     perlxstut, perlxs, perlcall, perlguts, perlembed
25         Various         http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz
26                         (not a man-page but still useful, a collection
27                          of various essays on Perl techniques)
28
29 A crude table of contents for the Perl manpage set is found in L<perltoc>.
30
31 =head2 How can I use Perl interactively?
32
33 The typical approach uses the Perl debugger, described in the
34 perldebug(1) manpage, on an "empty" program, like this:
35
36     perl -de 42
37
38 Now just type in any legal Perl code, and it will be immediately
39 evaluated.  You can also examine the symbol table, get stack
40 backtraces, check variable values, set breakpoints, and other
41 operations typically found in symbolic debuggers.
42
43 =head2 Is there a Perl shell?
44
45 The psh (Perl sh) is currently at version 1.8. The Perl Shell is a shell
46 that combines the interactive nature of a Unix shell with the power of
47 Perl. The goal is a full featured shell that behaves as expected for
48 normal shell activity and uses Perl syntax and functionality for
49 control-flow statements and other things. You can get psh at
50 http://sourceforge.net/projects/psh/ .
51
52 Zoidberg is a similar project and provides a shell written in perl,
53 configured in perl and operated in perl. It is intended as a login shell
54 and development environment. It can be found at http://zoidberg.sf.net/
55 or your local CPAN mirror.
56
57 The Shell.pm module (distributed with Perl) makes Perl try commands
58 which aren't part of the Perl language as shell commands.  perlsh from
59 the source distribution is simplistic and uninteresting, but may still
60 be what you want.
61
62 =head2 How do I find which modules are installed on my system?
63
64 You can use the ExtUtils::Installed module to show all installed
65 distributions, although it can take awhile to do its magic.  The
66 standard library which comes with Perl just shows up as "Perl" (although
67 you can get those with Module::CoreList).
68
69         use ExtUtils::Installed;
70
71         my $inst    = ExtUtils::Installed->new();
72         my @modules = $inst->modules();
73
74 If you want a list of all of the Perl module filenames, you
75 can use File::Find::Rule.
76
77         use File::Find::Rule;
78
79         my @files = File::Find::Rule->file()->name( '*.pm' )->in( @INC );
80
81 If you do not have that module, you can do the same thing
82 with File::Find which is part of the standard library.
83
84     use File::Find;
85     my @files;
86
87     find(
88       sub {
89         push @files, $File::Find::name
90                 if -f $File::Find::name && /\.pm$/
91         },
92
93       @INC
94       );
95
96         print join "\n", @files;
97
98 If you simply need to quickly check to see if a module is
99 available, you can check for its documentation.  If you can
100 read the documentation the module is most likely installed.
101 If you cannot read the documentation, the module might not
102 have any (in rare cases).
103
104         prompt% perldoc Module::Name
105
106 You can also try to include the module in a one-liner to see if
107 perl finds it.
108
109         perl -MModule::Name -e1
110
111 =head2 How do I debug my Perl programs?
112
113 Have you tried C<use warnings> or used C<-w>?  They enable warnings
114 to detect dubious practices.
115
116 Have you tried C<use strict>?  It prevents you from using symbolic
117 references, makes you predeclare any subroutines that you call as bare
118 words, and (probably most importantly) forces you to predeclare your
119 variables with C<my>, C<our>, or C<use vars>.
120
121 Did you check the return values of each and every system call?  The operating
122 system (and thus Perl) tells you whether they worked, and if not
123 why.
124
125   open(FH, "> /etc/cantwrite")
126     or die "Couldn't write to /etc/cantwrite: $!\n";
127
128 Did you read L<perltrap>?  It's full of gotchas for old and new Perl
129 programmers and even has sections for those of you who are upgrading
130 from languages like I<awk> and I<C>.
131
132 Have you tried the Perl debugger, described in L<perldebug>?  You can
133 step through your program and see what it's doing and thus work out
134 why what it's doing isn't what it should be doing.
135
136 =head2 How do I profile my Perl programs?
137
138 You should get the Devel::DProf module from the standard distribution
139 (or separately on CPAN) and also use Benchmark.pm from the standard
140 distribution.  The Benchmark module lets you time specific portions of
141 your code, while Devel::DProf gives detailed breakdowns of where your
142 code spends its time.
143
144 Here's a sample use of Benchmark:
145
146   use Benchmark;
147
148   @junk = `cat /etc/motd`;
149   $count = 10_000;
150
151   timethese($count, {
152             'map' => sub { my @a = @junk;
153                            map { s/a/b/ } @a;
154                            return @a },
155             'for' => sub { my @a = @junk;
156                            for (@a) { s/a/b/ };
157                            return @a },
158            });
159
160 This is what it prints (on one machine--your results will be dependent
161 on your hardware, operating system, and the load on your machine):
162
163   Benchmark: timing 10000 iterations of for, map...
164          for:  4 secs ( 3.97 usr  0.01 sys =  3.98 cpu)
165          map:  6 secs ( 4.97 usr  0.00 sys =  4.97 cpu)
166
167 Be aware that a good benchmark is very hard to write.  It only tests the
168 data you give it and proves little about the differing complexities
169 of contrasting algorithms.
170
171 =head2 How do I cross-reference my Perl programs?
172
173 The B::Xref module can be used to generate cross-reference reports
174 for Perl programs.
175
176     perl -MO=Xref[,OPTIONS] scriptname.plx
177
178 =head2 Is there a pretty-printer (formatter) for Perl?
179
180 Perltidy is a Perl script which indents and reformats Perl scripts
181 to make them easier to read by trying to follow the rules of the
182 L<perlstyle>. If you write Perl scripts, or spend much time reading
183 them, you will probably find it useful.  It is available at
184 http://perltidy.sourceforge.net
185
186 Of course, if you simply follow the guidelines in L<perlstyle>,
187 you shouldn't need to reformat.  The habit of formatting your code
188 as you write it will help prevent bugs.  Your editor can and should
189 help you with this.  The perl-mode or newer cperl-mode for emacs
190 can provide remarkable amounts of help with most (but not all)
191 code, and even less programmable editors can provide significant
192 assistance.  Tom Christiansen and many other VI users  swear by
193 the following settings in vi and its clones:
194
195     set ai sw=4
196     map! ^O {^M}^[O^T
197
198 Put that in your F<.exrc> file (replacing the caret characters
199 with control characters) and away you go.  In insert mode, ^T is
200 for indenting, ^D is for undenting, and ^O is for blockdenting--
201 as it were.  A more complete example, with comments, can be found at
202 http://www.cpan.org/authors/id/TOMC/scripts/toms.exrc.gz
203
204 The a2ps http://www-inf.enst.fr/%7Edemaille/a2ps/black+white.ps.gz does
205 lots of things related to generating nicely printed output of
206 documents, as does enscript at http://people.ssh.fi/mtr/genscript/ .
207
208 =head2 Is there a ctags for Perl?
209
210 (contributed by brian d foy)
211
212 Exuberent ctags supports Perl: http://ctags.sourceforge.net/
213
214 You might also try pltags: http://www.mscha.com/pltags.zip
215
216 =head2 Is there an IDE or Windows Perl Editor?
217
218 Perl programs are just plain text, so any editor will do.
219
220 If you're on Unix, you already have an IDE--Unix itself.  The UNIX
221 philosophy is the philosophy of several small tools that each do one
222 thing and do it well.  It's like a carpenter's toolbox.
223
224 If you want an IDE, check the following (in alphabetical order, not
225 order of preference):
226
227 =over 4
228
229 =item Eclipse
230
231 http://e-p-i-c.sf.net/
232
233 The Eclipse Perl Integration Project integrates Perl
234 editing/debugging with Eclipse.
235
236 =item Enginsite
237
238 http://www.enginsite.com/
239
240 Perl Editor by EngInSite is a complete integrated development
241 environment (IDE) for creating, testing, and  debugging  Perl scripts;
242 the tool runs on Windows 9x/NT/2000/XP or later.
243
244 =item Komodo
245
246 http://www.ActiveState.com/Products/Komodo/
247
248 ActiveState's cross-platform (as of October 2004, that's Windows, Linux,
249 and Solaris), multi-language IDE has Perl support, including a regular expression
250 debugger and remote debugging.
251
252 =item Open Perl IDE
253
254 http://open-perl-ide.sourceforge.net/
255
256 Open Perl IDE is an integrated development environment for writing
257 and debugging Perl scripts with ActiveState's ActivePerl distribution
258 under Windows 95/98/NT/2000.
259
260 =item OptiPerl
261
262 http://www.optiperl.com/
263
264 OptiPerl is a Windows IDE with simulated CGI environment, including
265 debugger and syntax highlighting editor.
266
267 =item PerlBuilder
268
269 http://www.solutionsoft.com/perl.htm
270
271 PerlBuidler is an integrated development environment for Windows that
272 supports Perl development.
273
274 =item visiPerl+
275
276 http://helpconsulting.net/visiperl/
277
278 From Help Consulting, for Windows.
279
280 =item Visual Perl
281
282 http://www.activestate.com/Products/Visual_Perl/
283
284 Visual Perl is a Visual Studio.NET plug-in from ActiveState.
285
286 =item Zeus
287
288 http://www.zeusedit.com/lookmain.html
289
290 Zeus for Window is another Win32 multi-language editor/IDE
291 that comes with support for Perl:
292
293 =back
294
295 For editors: if you're on Unix you probably have vi or a vi clone
296 already, and possibly an emacs too, so you may not need to download
297 anything. In any emacs the cperl-mode (M-x cperl-mode) gives you
298 perhaps the best available Perl editing mode in any editor.
299
300 If you are using Windows, you can use any editor that lets you work
301 with plain text, such as NotePad or WordPad.  Word processors, such as
302 Microsoft Word or WordPerfect, typically do not work since they insert
303 all sorts of behind-the-scenes information, although some allow you to
304 save files as "Text Only". You can also download text editors designed
305 specifically for programming, such as Textpad (
306 http://www.textpad.com/ ) and UltraEdit ( http://www.ultraedit.com/ ),
307 among others.
308
309 If you are using MacOS, the same concerns apply.  MacPerl (for Classic
310 environments) comes with a simple editor. Popular external editors are
311 BBEdit ( http://www.bbedit.com/ ) or Alpha (
312 http://www.his.com/~jguyer/Alpha/Alpha8.html ). MacOS X users can use
313 Unix editors as well. Neil Bowers (the man behind Geekcruises) has a
314 list of Mac editors that can handle Perl (
315 http://www.neilbowers.org/macperleditors.html ).
316
317 =over 4
318
319 =item GNU Emacs
320
321 http://www.gnu.org/software/emacs/windows/ntemacs.html
322
323 =item MicroEMACS
324
325 http://www.microemacs.de/
326
327 =item XEmacs
328
329 http://www.xemacs.org/Download/index.html
330
331 =item Jed
332
333 http://space.mit.edu/~davis/jed/
334
335 =back
336
337 or a vi clone such as
338
339 =over 4
340
341 =item Elvis
342
343 ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/
344
345 =item Vile
346
347 http://dickey.his.com/vile/vile.html
348
349 =item Vim
350
351 http://www.vim.org/
352
353 =back
354
355 For vi lovers in general, Windows or elsewhere:
356
357         http://www.thomer.com/thomer/vi/vi.html
358
359 nvi ( http://www.bostic.com/vi/ , available from CPAN in src/misc/) is
360 yet another vi clone, unfortunately not available for Windows, but in
361 UNIX platforms you might be interested in trying it out, firstly because
362 strictly speaking it is not a vi clone, it is the real vi, or the new
363 incarnation of it, and secondly because you can embed Perl inside it
364 to use Perl as the scripting language.  nvi is not alone in this,
365 though: at least also vim and vile offer an embedded Perl.
366
367 The following are Win32 multilanguage editor/IDESs that support Perl:
368
369 =over 4
370
371 =item Codewright
372
373 http://www.borland.com/codewright/
374
375 =item MultiEdit
376
377 http://www.MultiEdit.com/
378
379 =item SlickEdit
380
381 http://www.slickedit.com/
382
383 =back
384
385 There is also a toyedit Text widget based editor written in Perl
386 that is distributed with the Tk module on CPAN.  The ptkdb
387 ( http://world.std.com/~aep/ptkdb/ ) is a Perl/tk based debugger that
388 acts as a development environment of sorts.  Perl Composer
389 ( http://perlcomposer.sourceforge.net/ ) is an IDE for Perl/Tk
390 GUI creation.
391
392 In addition to an editor/IDE you might be interested in a more
393 powerful shell environment for Win32.  Your options include
394
395 =over 4
396
397 =item Bash
398
399 from the Cygwin package ( http://sources.redhat.com/cygwin/ )
400
401 =item Ksh
402
403 from the MKS Toolkit ( http://www.mks.com/ ), or the Bourne shell of
404 the U/WIN environment ( http://www.research.att.com/sw/tools/uwin/ )
405
406 =item Tcsh
407
408 ftp://ftp.astron.com/pub/tcsh/ , see also
409 http://www.primate.wisc.edu/software/csh-tcsh-book/
410
411 =item Zsh
412
413 ftp://ftp.blarg.net/users/amol/zsh/ , see also http://www.zsh.org/
414
415 =back
416
417 MKS and U/WIN are commercial (U/WIN is free for educational and
418 research purposes), Cygwin is covered by the GNU Public License (but
419 that shouldn't matter for Perl use).  The Cygwin, MKS, and U/WIN all
420 contain (in addition to the shells) a comprehensive set of standard
421 UNIX toolkit utilities.
422
423 If you're transferring text files between Unix and Windows using FTP
424 be sure to transfer them in ASCII mode so the ends of lines are
425 appropriately converted.
426
427 On Mac OS the MacPerl Application comes with a simple 32k text editor
428 that behaves like a rudimentary IDE.  In contrast to the MacPerl Application
429 the MPW Perl tool can make use of the MPW Shell itself as an editor (with
430 no 32k limit).
431
432 =over 4
433
434 =item Affrus
435
436 is a full Perl development environment with full debugger support
437 ( http://www.latenightsw.com ).
438
439 =item Alpha
440
441 is an editor, written and extensible in Tcl, that nonetheless has
442 built in support for several popular markup and programming languages
443 including Perl and HTML ( http://www.his.com/~jguyer/Alpha/Alpha8.html ).
444
445 =item BBEdit and BBEdit Lite
446
447 are text editors for Mac OS that have a Perl sensitivity mode
448 ( http://web.barebones.com/ ).
449
450
451 =back
452
453 Pepper and Pe are programming language sensitive text editors for Mac
454 OS X and BeOS respectively ( http://www.hekkelman.com/ ).
455
456 =head2 Where can I get Perl macros for vi?
457
458 For a complete version of Tom Christiansen's vi configuration file,
459 see http://www.cpan.org/authors/Tom_Christiansen/scripts/toms.exrc.gz ,
460 the standard benchmark file for vi emulators.  The file runs best with nvi,
461 the current version of vi out of Berkeley, which incidentally can be built
462 with an embedded Perl interpreter--see http://www.cpan.org/src/misc/ .
463
464 =head2 Where can I get perl-mode for emacs?
465
466 Since Emacs version 19 patchlevel 22 or so, there have been both a
467 perl-mode.el and support for the Perl debugger built in.  These should
468 come with the standard Emacs 19 distribution.
469
470 In the Perl source directory, you'll find a directory called "emacs",
471 which contains a cperl-mode that color-codes keywords, provides
472 context-sensitive help, and other nifty things.
473
474 Note that the perl-mode of emacs will have fits with C<"main'foo">
475 (single quote), and mess up the indentation and highlighting.  You
476 are probably using C<"main::foo"> in new Perl code anyway, so this
477 shouldn't be an issue.
478
479 =head2 How can I use curses with Perl?
480
481 The Curses module from CPAN provides a dynamically loadable object
482 module interface to a curses library.  A small demo can be found at the
483 directory http://www.cpan.org/authors/Tom_Christiansen/scripts/rep.gz ;
484 this program repeats a command and updates the screen as needed, rendering
485 B<rep ps axu> similar to B<top>.
486
487 =head2 How can I use X or Tk with Perl?
488
489 Tk is a completely Perl-based, object-oriented interface to the Tk toolkit
490 that doesn't force you to use Tcl just to get at Tk.  Sx is an interface
491 to the Athena Widget set.  Both are available from CPAN.  See the
492 directory http://www.cpan.org/modules/by-category/08_User_Interfaces/
493
494 Invaluable for Perl/Tk programming are the Perl/Tk FAQ at
495 http://phaseit.net/claird/comp.lang.perl.tk/ptkFAQ.html , the Perl/Tk Reference
496 Guide available at
497 http://www.cpan.org/authors/Stephen_O_Lidie/ , and the
498 online manpages at
499 http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html .
500
501 =head2 How can I make my Perl program run faster?
502
503 The best way to do this is to come up with a better algorithm.  This
504 can often make a dramatic difference.  Jon Bentley's book
505 I<Programming Pearls> (that's not a misspelling!)  has some good tips
506 on optimization, too.  Advice on benchmarking boils down to: benchmark
507 and profile to make sure you're optimizing the right part, look for
508 better algorithms instead of microtuning your code, and when all else
509 fails consider just buying faster hardware.  You will probably want to
510 read the answer to the earlier question "How do I profile my Perl
511 programs?" if you haven't done so already.
512
513 A different approach is to autoload seldom-used Perl code.  See the
514 AutoSplit and AutoLoader modules in the standard distribution for
515 that.  Or you could locate the bottleneck and think about writing just
516 that part in C, the way we used to take bottlenecks in C code and
517 write them in assembler.  Similar to rewriting in C, modules that have
518 critical sections can be written in C (for instance, the PDL module
519 from CPAN).
520
521 If you're currently linking your perl executable to a shared
522 I<libc.so>, you can often gain a 10-25% performance benefit by
523 rebuilding it to link with a static libc.a instead.  This will make a
524 bigger perl executable, but your Perl programs (and programmers) may
525 thank you for it.  See the F<INSTALL> file in the source distribution
526 for more information.
527
528 The undump program was an ancient attempt to speed up Perl program by
529 storing the already-compiled form to disk.  This is no longer a viable
530 option, as it only worked on a few architectures, and wasn't a good
531 solution anyway.
532
533 =head2 How can I make my Perl program take less memory?
534
535 When it comes to time-space tradeoffs, Perl nearly always prefers to
536 throw memory at a problem.  Scalars in Perl use more memory than
537 strings in C, arrays take more than that, and hashes use even more.  While
538 there's still a lot to be done, recent releases have been addressing
539 these issues.  For example, as of 5.004, duplicate hash keys are
540 shared amongst all hashes using them, so require no reallocation.
541
542 In some cases, using substr() or vec() to simulate arrays can be
543 highly beneficial.  For example, an array of a thousand booleans will
544 take at least 20,000 bytes of space, but it can be turned into one
545 125-byte bit vector--a considerable memory savings.  The standard
546 Tie::SubstrHash module can also help for certain types of data
547 structure.  If you're working with specialist data structures
548 (matrices, for instance) modules that implement these in C may use
549 less memory than equivalent Perl modules.
550
551 Another thing to try is learning whether your Perl was compiled with
552 the system malloc or with Perl's builtin malloc.  Whichever one it
553 is, try using the other one and see whether this makes a difference.
554 Information about malloc is in the F<INSTALL> file in the source
555 distribution.  You can find out whether you are using perl's malloc by
556 typing C<perl -V:usemymalloc>.
557
558 Of course, the best way to save memory is to not do anything to waste
559 it in the first place. Good programming practices can go a long way
560 toward this:
561
562 =over 4
563
564 =item * Don't slurp!
565
566 Don't read an entire file into memory if you can process it line
567 by line. Or more concretely, use a loop like this:
568
569         #
570         # Good Idea
571         #
572         while (<FILE>) {
573            # ...
574         }
575
576 instead of this:
577
578         #
579         # Bad Idea
580         #
581         @data = <FILE>;
582         foreach (@data) {
583             # ...
584         }
585
586 When the files you're processing are small, it doesn't much matter which
587 way you do it, but it makes a huge difference when they start getting
588 larger.
589
590 =item * Use map and grep selectively
591
592 Remember that both map and grep expect a LIST argument, so doing this:
593
594         @wanted = grep {/pattern/} <FILE>;
595
596 will cause the entire file to be slurped. For large files, it's better
597 to loop:
598
599         while (<FILE>) {
600                 push(@wanted, $_) if /pattern/;
601         }
602
603 =item * Avoid unnecessary quotes and stringification
604
605 Don't quote large strings unless absolutely necessary:
606
607         my $copy = "$large_string";
608
609 makes 2 copies of $large_string (one for $copy and another for the
610 quotes), whereas
611
612         my $copy = $large_string;
613
614 only makes one copy.
615
616 Ditto for stringifying large arrays:
617
618         {
619                 local $, = "\n";
620                 print @big_array;
621         }
622
623 is much more memory-efficient than either
624
625         print join "\n", @big_array;
626
627 or
628
629         {
630                 local $" = "\n";
631                 print "@big_array";
632         }
633
634
635 =item * Pass by reference
636
637 Pass arrays and hashes by reference, not by value. For one thing, it's
638 the only way to pass multiple lists or hashes (or both) in a single
639 call/return. It also avoids creating a copy of all the contents. This
640 requires some judgment, however, because any changes will be propagated
641 back to the original data. If you really want to mangle (er, modify) a
642 copy, you'll have to sacrifice the memory needed to make one.
643
644 =item * Tie large variables to disk.
645
646 For "big" data stores (i.e. ones that exceed available memory) consider
647 using one of the DB modules to store it on disk instead of in RAM. This
648 will incur a penalty in access time, but that's probably better than
649 causing your hard disk to thrash due to massive swapping.
650
651 =back
652
653 =head2 Is it safe to return a reference to local or lexical data?
654
655 Yes. Perl's garbage collection system takes care of this so
656 everything works out right.
657
658     sub makeone {
659         my @a = ( 1 .. 10 );
660         return \@a;
661     }
662
663     for ( 1 .. 10 ) {
664         push @many, makeone();
665     }
666
667     print $many[4][5], "\n";
668
669     print "@many\n";
670
671 =head2 How can I free an array or hash so my program shrinks?
672
673 (contributed by Michael Carman)
674
675 You usually can't. Memory allocated to lexicals (i.e. my() variables)
676 cannot be reclaimed or reused even if they go out of scope. It is
677 reserved in case the variables come back into scope. Memory allocated
678 to global variables can be reused (within your program) by using
679 undef()ing and/or delete().
680
681 On most operating systems, memory allocated to a program can never be
682 returned to the system. That's why long-running programs sometimes re-
683 exec themselves. Some operating systems (notably, systems that use
684 mmap(2) for allocating large chunks of memory) can reclaim memory that
685 is no longer used, but on such systems, perl must be configured and
686 compiled to use the OS's malloc, not perl's.
687
688 In general, memory allocation and de-allocation isn't something you can
689 or should be worrying about much in Perl.
690
691 See also "How can I make my Perl program take less memory?"
692
693 =head2 How can I make my CGI script more efficient?
694
695 Beyond the normal measures described to make general Perl programs
696 faster or smaller, a CGI program has additional issues.  It may be run
697 several times per second.  Given that each time it runs it will need
698 to be re-compiled and will often allocate a megabyte or more of system
699 memory, this can be a killer.  Compiling into C B<isn't going to help
700 you> because the process start-up overhead is where the bottleneck is.
701
702 There are two popular ways to avoid this overhead.  One solution
703 involves running the Apache HTTP server (available from
704 http://www.apache.org/ ) with either of the mod_perl or mod_fastcgi
705 plugin modules.
706
707 With mod_perl and the Apache::Registry module (distributed with
708 mod_perl), httpd will run with an embedded Perl interpreter which
709 pre-compiles your script and then executes it within the same address
710 space without forking.  The Apache extension also gives Perl access to
711 the internal server API, so modules written in Perl can do just about
712 anything a module written in C can.  For more on mod_perl, see
713 http://perl.apache.org/
714
715 With the FCGI module (from CPAN) and the mod_fastcgi
716 module (available from http://www.fastcgi.com/ ) each of your Perl
717 programs becomes a permanent CGI daemon process.
718
719 Both of these solutions can have far-reaching effects on your system
720 and on the way you write your CGI programs, so investigate them with
721 care.
722
723 See http://www.cpan.org/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ .
724
725 =head2 How can I hide the source for my Perl program?
726
727 Delete it. :-) Seriously, there are a number of (mostly
728 unsatisfactory) solutions with varying levels of "security".
729
730 First of all, however, you I<can't> take away read permission, because
731 the source code has to be readable in order to be compiled and
732 interpreted.  (That doesn't mean that a CGI script's source is
733 readable by people on the web, though--only by people with access to
734 the filesystem.)  So you have to leave the permissions at the socially
735 friendly 0755 level.
736
737 Some people regard this as a security problem.  If your program does
738 insecure things and relies on people not knowing how to exploit those
739 insecurities, it is not secure.  It is often possible for someone to
740 determine the insecure things and exploit them without viewing the
741 source.  Security through obscurity, the name for hiding your bugs
742 instead of fixing them, is little security indeed.
743
744 You can try using encryption via source filters (Starting from Perl
745 5.8 the Filter::Simple and Filter::Util::Call modules are included in
746 the standard distribution), but any decent programmer will be able to
747 decrypt it.  You can try using the byte code compiler and interpreter
748 described below, but the curious might still be able to de-compile it.
749 You can try using the native-code compiler described below, but
750 crackers might be able to disassemble it.  These pose varying degrees
751 of difficulty to people wanting to get at your code, but none can
752 definitively conceal it (true of every language, not just Perl).
753
754 It is very easy to recover the source of Perl programs.  You simply
755 feed the program to the perl interpreter and use the modules in
756 the B:: hierarchy.  The B::Deparse module should be able to
757 defeat most attempts to hide source.  Again, this is not
758 unique to Perl.
759
760 If you're concerned about people profiting from your code, then the
761 bottom line is that nothing but a restrictive license will give you
762 legal security.  License your software and pepper it with threatening
763 statements like "This is unpublished proprietary software of XYZ Corp.
764 Your access to it does not give you permission to use it blah blah
765 blah."  We are not lawyers, of course, so you should see a lawyer if
766 you want to be sure your license's wording will stand up in court.
767
768 =head2 How can I compile my Perl program into byte code or C?
769
770 (contributed by brian d foy)
771
772 In general, you can't do this.  There are some things that may work
773 for your situation though.  People usually ask this question
774 because they want to distribute their works without giving away
775 the source code, and most solutions trade disk space for convenience.
776 You probably won't see much of a speed increase either, since most
777 solutions simply bundle a Perl interpreter in the final product
778 (but see L<How can I make my Perl program run faster?>).
779
780 The Perl Archive Toolkit ( http://par.perl.org/index.cgi ) is Perl's
781 analog to Java's JAR.  It's freely available and on CPAN (
782 http://search.cpan.org/dist/PAR/ ).
783
784 The B::* namespace, often called "the Perl compiler", but is really a way
785 for Perl programs to peek at its innards rather than create pre-compiled
786 versions of your program.  However. the B::Bytecode module can turn your
787 script  into a bytecode format that could be loaded later by the
788 ByteLoader module and executed as a regular Perl script.
789
790 There are also some commercial products that may work for you, although
791 you have to buy a license for them.
792
793 The Perl Dev Kit ( http://www.activestate.com/Products/Perl_Dev_Kit/ )
794 from ActiveState can "Turn your Perl programs into ready-to-run
795 executables for HP-UX, Linux, Solaris and Windows."
796
797 Perl2Exe ( http://www.indigostar.com/perl2exe.htm ) is a command line
798 program for converting perl scripts to executable files.  It targets both
799 Windows and unix platforms.
800
801 =head2 How can I compile Perl into Java?
802
803 You can also integrate Java and Perl with the
804 Perl Resource Kit from O'Reilly Media.  See
805 http://www.oreilly.com/catalog/prkunix/ .
806
807 Perl 5.6 comes with Java Perl Lingo, or JPL.  JPL, still in
808 development, allows Perl code to be called from Java.  See jpl/README
809 in the Perl source tree.
810
811 =head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]?
812
813 For OS/2 just use
814
815     extproc perl -S -your_switches
816
817 as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's
818 "extproc" handling).  For DOS one should first invent a corresponding
819 batch file and codify it in C<ALTERNATE_SHEBANG> (see the
820 F<dosish.h> file in the source distribution for more information).
821
822 The Win95/NT installation, when using the ActiveState port of Perl,
823 will modify the Registry to associate the C<.pl> extension with the
824 perl interpreter.  If you install another port, perhaps even building
825 your own Win95/NT Perl from the standard sources by using a Windows port
826 of gcc (e.g., with cygwin or mingw32), then you'll have to modify
827 the Registry yourself.  In addition to associating C<.pl> with the
828 interpreter, NT people can use: C<SET PATHEXT=%PATHEXT%;.PL> to let them
829 run the program C<install-linux.pl> merely by typing C<install-linux>.
830
831 Under "Classic" MacOS, a perl program will have the appropriate Creator and
832 Type, so that double-clicking them will invoke the MacPerl application.
833 Under Mac OS X, clickable apps can be made from any C<#!> script using Wil
834 Sanchez' DropScript utility: http://www.wsanchez.net/software/ .
835
836 I<IMPORTANT!>: Whatever you do, PLEASE don't get frustrated, and just
837 throw the perl interpreter into your cgi-bin directory, in order to
838 get your programs working for a web server.  This is an EXTREMELY big
839 security risk.  Take the time to figure out how to do it correctly.
840
841 =head2 Can I write useful Perl programs on the command line?
842
843 Yes.  Read L<perlrun> for more information.  Some examples follow.
844 (These assume standard Unix shell quoting rules.)
845
846     # sum first and last fields
847     perl -lane 'print $F[0] + $F[-1]' *
848
849     # identify text files
850     perl -le 'for(@ARGV) {print if -f && -T _}' *
851
852     # remove (most) comments from C program
853     perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c
854
855     # make file a month younger than today, defeating reaper daemons
856     perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' *
857
858     # find first unused uid
859     perl -le '$i++ while getpwuid($i); print $i'
860
861     # display reasonable manpath
862     echo $PATH | perl -nl -072 -e '
863         s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}'
864
865 OK, the last one was actually an Obfuscated Perl Contest entry. :-)
866
867 =head2 Why don't Perl one-liners work on my DOS/Mac/VMS system?
868
869 The problem is usually that the command interpreters on those systems
870 have rather different ideas about quoting than the Unix shells under
871 which the one-liners were created.  On some systems, you may have to
872 change single-quotes to double ones, which you must I<NOT> do on Unix
873 or Plan9 systems.  You might also have to change a single % to a %%.
874
875 For example:
876
877     # Unix
878     perl -e 'print "Hello world\n"'
879
880     # DOS, etc.
881     perl -e "print \"Hello world\n\""
882
883     # Mac
884     print "Hello world\n"
885      (then Run "Myscript" or Shift-Command-R)
886
887     # MPW
888     perl -e 'print "Hello world\n"'
889
890     # VMS
891     perl -e "print ""Hello world\n"""
892
893 The problem is that none of these examples are reliable: they depend on the
894 command interpreter.  Under Unix, the first two often work. Under DOS,
895 it's entirely possible that neither works.  If 4DOS was the command shell,
896 you'd probably have better luck like this:
897
898   perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
899
900 Under the Mac, it depends which environment you are using.  The MacPerl
901 shell, or MPW, is much like Unix shells in its support for several
902 quoting variants, except that it makes free use of the Mac's non-ASCII
903 characters as control characters.
904
905 Using qq(), q(), and qx(), instead of "double quotes", 'single
906 quotes', and `backticks`, may make one-liners easier to write.
907
908 There is no general solution to all of this.  It is a mess.
909
910 [Some of this answer was contributed by Kenneth Albanowski.]
911
912 =head2 Where can I learn about CGI or Web programming in Perl?
913
914 For modules, get the CGI or LWP modules from CPAN.  For textbooks,
915 see the two especially dedicated to web stuff in the question on
916 books.  For problems and questions related to the web, like "Why
917 do I get 500 Errors" or "Why doesn't it run from the browser right
918 when it runs fine on the command line", see the troubleshooting
919 guides and references in L<perlfaq9> or in the CGI MetaFAQ:
920
921         http://www.perl.org/CGI_MetaFAQ.html
922
923 =head2 Where can I learn about object-oriented Perl programming?
924
925 A good place to start is L<perltoot>, and you can use L<perlobj>,
926 L<perlboot>, L<perltoot>, L<perltooc>, and L<perlbot> for reference.
927
928 A good book on OO on Perl is the "Object-Oriented Perl"
929 by Damian Conway from Manning Publications, or "Learning Perl
930 References, Objects, & Modules" by Randal Schwartz and Tom
931 Phoenix from O'Reilly Media.
932
933 =head2 Where can I learn about linking C with Perl?
934
935 If you want to call C from Perl, start with L<perlxstut>,
936 moving on to L<perlxs>, L<xsubpp>, and L<perlguts>.  If you want to
937 call Perl from C, then read L<perlembed>, L<perlcall>, and
938 L<perlguts>.  Don't forget that you can learn a lot from looking at
939 how the authors of existing extension modules wrote their code and
940 solved their problems.
941
942 You might not need all the power of XS. The Inline::C module lets
943 you put C code directly in your Perl source. It handles all the
944 magic to make it work. You still have to learn at least some of
945 the perl API but you won't have to deal with the complexity of the
946 XS support files.
947
948 =head2 I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
949
950 Download the ExtUtils::Embed kit from CPAN and run `make test'.  If
951 the tests pass, read the pods again and again and again.  If they
952 fail, see L<perlbug> and send a bug report with the output of
953 C<make test TEST_VERBOSE=1> along with C<perl -V>.
954
955 =head2 When I tried to run my script, I got this message. What does it mean?
956
957 A complete list of Perl's error messages and warnings with explanatory
958 text can be found in L<perldiag>. You can also use the splain program
959 (distributed with Perl) to explain the error messages:
960
961     perl program 2>diag.out
962     splain [-v] [-p] diag.out
963
964 or change your program to explain the messages for you:
965
966     use diagnostics;
967
968 or
969
970     use diagnostics -verbose;
971
972 =head2 What's MakeMaker?
973
974 This module (part of the standard Perl distribution) is designed to
975 write a Makefile for an extension module from a Makefile.PL.  For more
976 information, see L<ExtUtils::MakeMaker>.
977
978 =head1 AUTHOR AND COPYRIGHT
979
980 Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and
981 other authors as noted. All rights reserved.
982
983 This documentation is free; you can redistribute it and/or modify it
984 under the same terms as Perl itself.
985
986 Irrespective of its distribution, all code examples here are in the public
987 domain.  You are permitted and encouraged to use this code and any
988 derivatives thereof in your own programs for fun or for profit as you
989 see fit.  A simple comment in the code giving credit to the FAQ would
990 be courteous but is not required.