note strict/lax version requirements in documentation
[p5sagit/p5-mst-13.2.git] / pod / perlfaq2.pod
1 =head1 NAME
2
3 perlfaq2 - Obtaining and Learning about Perl
4
5 =head1 DESCRIPTION
6
7 This section of the FAQ answers questions about where to find
8 source and documentation for Perl, support, and
9 related matters.
10
11 =head2 What machines support perl?  Where do I get it?
12
13 The standard release of perl (the one maintained by the perl
14 development team) is distributed only in source code form.  You
15 can find the latest releases at http://www.cpan.org/src/README.html .
16
17 Perl builds and runs on a bewildering number of platforms.  Virtually
18 all known and current Unix derivatives are supported (perl's native
19 platform), as are other systems like VMS, DOS, OS/2, Windows,
20 QNX, BeOS, OS X, MPE/iX and the Amiga.
21
22 Binary distributions for some proprietary platforms can be found
23 http://www.cpan.org/ports/ directory. Because these are not part of
24 the standard distribution, they may and in fact do differ from the
25 base perl port in a variety of ways. You'll have to check their
26 respective release notes to see just what the differences are.  These
27 differences can be either positive (e.g. extensions for the features
28 of the particular platform that are not supported in the source
29 release of perl) or negative (e.g. might be based upon a less current
30 source release of perl).
31
32 =head2 How can I get a binary version of perl?
33
34 (contributed by brian d foy)
35
36 ActiveState: Windows, Linux, Mac OS X, Solaris, AIX and HP-UX
37
38         http://www.activestate.com/
39
40 Sunfreeware.com: Solaris 2.5 to Solaris 10 (SPARC and x86)
41
42         http://www.sunfreeware.com/
43
44 Strawberry Perl: Windows, Perl 5.8.8 and 5.10.0
45
46         http://www.strawberryperl.com
47         
48 IndigoPerl: Windows
49
50         http://indigostar.com/
51
52 =head2 I don't have a C compiler. How can I build my own Perl interpreter?
53
54 Since you don't have a C compiler, you're doomed and your vendor
55 should be sacrificed to the Sun gods.  But that doesn't help you.
56
57 What you need to do is get a binary version of C<gcc> for your system
58 first.  Consult the Usenet FAQs for your operating system for
59 information on where to get such a binary version.
60
61 You might look around the net for a pre-built binary of Perl (or a
62 C compiler!) that meets your needs, though:
63
64 For Windows, Vanilla Perl ( http://vanillaperl.com/ ) and Strawberry Perl
65 ( http://strawberryperl.com/ ) come with a
66 bundled C compiler. ActivePerl is a pre-compiled version of Perl
67 ready-to-use.
68
69 For Sun systems, SunFreeware.com provides binaries of most popular
70 applications, including compilers and Perl.
71
72 =head2 I copied the perl binary from one machine to another, but scripts don't work.
73
74 That's probably because you forgot libraries, or library paths differ.
75 You really should build the whole distribution on the machine it will
76 eventually live on, and then type C<make install>.  Most other
77 approaches are doomed to failure.
78
79 One simple way to check that things are in the right place is to print out
80 the hard-coded C<@INC> that perl looks through for libraries:
81
82     % perl -le 'print for @INC'
83
84 If this command lists any paths that don't exist on your system, then you
85 may need to move the appropriate libraries to these locations, or create
86 symbolic links, aliases, or shortcuts appropriately.  C<@INC> is also printed as
87 part of the output of
88
89     % perl -V
90
91 You might also want to check out
92 L<perlfaq8/"How do I keep my own module/library directory?">.
93
94 =head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed.  How do I make it work?
95
96 Read the F<INSTALL> file, which is part of the source distribution.
97 It describes in detail how to cope with most idiosyncrasies that the
98 C<Configure> script can't work around for any given system or
99 architecture.
100
101 =head2 What modules and extensions are available for Perl?  What is CPAN?  What does CPAN/src/... mean?
102
103 CPAN stands for Comprehensive Perl Archive Network, a multi-gigabyte
104 archive replicated on hundreds of machines all over the world. CPAN
105 contains source code, non-native ports, documentation, scripts, and
106 many third-party modules and extensions, designed for everything from
107 commercial database interfaces to keyboard/screen control to web
108 walking and CGI scripts. The master web site for CPAN is
109 http://www.cpan.org/ and there is the CPAN Multiplexer at
110 http://www.cpan.org/CPAN.html which will choose a mirror near you via
111 DNS.  See http://www.perl.com/CPAN (without a slash at the end) for
112 how this process works. Also, http://mirror.cpan.org/ has a nice
113 interface to the http://www.cpan.org/MIRRORED.BY mirror directory.
114
115 See the CPAN FAQ at http://www.cpan.org/misc/cpan-faq.html for answers
116 to the most frequently asked questions about CPAN including how to
117 become a mirror.
118
119 C<CPAN/path/...> is a naming convention for files available on CPAN
120 sites.  CPAN indicates the base directory of a CPAN mirror, and the
121 rest of the path is the path from that directory to the file. For
122 instance, if you're using ftp://ftp.funet.fi/pub/languages/perl/CPAN
123 as your CPAN site, the file C<CPAN/misc/japh> is downloadable as
124 ftp://ftp.funet.fi/pub/languages/perl/CPAN/misc/japh .
125
126 Considering that, as of 2006, there are over ten thousand existing
127 modules in the archive, one probably exists to do nearly anything you
128 can think of. Current categories under C<CPAN/modules/by-category/>
129 include Perl core modules; development support; operating system
130 interfaces; networking, devices, and interprocess communication; data
131 type utilities; database interfaces; user interfaces; interfaces to
132 other languages; filenames, file systems, and file locking;
133 internationalization and locale; world wide web support; server and
134 daemon utilities; archiving and compression; image manipulation; mail
135 and news; control flow utilities; filehandle and I/O; Microsoft
136 Windows modules; and miscellaneous modules.
137
138 See http://www.cpan.org/modules/00modlist.long.html or
139 http://search.cpan.org/ for a more complete list of modules by
140 category.
141
142 CPAN is a free service and is not affiliated with O'Reilly Media.
143
144 =head2 Is there an ISO or ANSI certified version of Perl?
145
146 Certainly not.  Larry expects that he'll be certified before Perl is.
147
148 =head2 Where can I get information on Perl?
149
150 The complete Perl documentation is available with the Perl distribution.
151 If you have Perl installed locally, you probably have the documentation
152 installed as well: type C<man perl> if you're on a system resembling Unix.
153 This will lead you to other important man pages, including how to set your
154 C<$MANPATH>.  If you're not on a Unix system, access to the documentation
155 will be different; for example, documentation might only be in HTML format.  All
156 proper perl installations have fully-accessible documentation.
157
158 You might also try C<perldoc perl> in case your system doesn't
159 have a proper C<man> command, or it's been misinstalled.  If that doesn't
160 work, try looking in C</usr/local/lib/perl5/pod> for documentation.
161
162 If all else fails, consult http://perldoc.perl.org/ which has the
163 complete documentation in HTML and PDF format.
164
165 Many good books have been written about Perl--see the section later in
166 L<perlfaq2> for more details.
167
168 Tutorial documents are included in current or upcoming Perl releases
169 include L<perltoot> for objects or L<perlboot> for a beginner's
170 approach to objects, L<perlopentut> for file opening semantics,
171 L<perlreftut> for managing references, L<perlretut> for regular
172 expressions, L<perlthrtut> for threads, L<perldebtut> for debugging,
173 and L<perlxstut> for linking C and Perl together.  There may be more
174 by the time you read this.  These URLs might also be useful:
175
176     http://perldoc.perl.org/
177     http://bookmarks.cpan.org/search.cgi?cat=Training%2FTutorials
178
179 =head2 What are the Perl newsgroups on Usenet?  Where do I post questions?
180
181 Several groups devoted to the Perl language are on Usenet:
182
183         comp.lang.perl.announce      Moderated announcement group
184         comp.lang.perl.misc          High traffic general Perl discussion
185         comp.lang.perl.moderated     Moderated discussion group
186         comp.lang.perl.modules       Use and development of Perl modules
187         comp.lang.perl.tk            Using Tk (and X) from Perl
188
189 Some years ago, comp.lang.perl was divided into those groups, and
190 comp.lang.perl itself officially removed.  While that group may still
191 be found on some news servers, it is unwise to use it, because
192 postings there will not appear on news servers which honour the
193 official list of group names.  Use comp.lang.perl.misc for topics
194 which do not have a more-appropriate specific group.
195
196 There is also a Usenet gateway to Perl mailing lists sponsored by
197 perl.org at nntp://nntp.perl.org , a web interface to the same lists
198 at http://nntp.perl.org/group/ and these lists are also available
199 under the C<perl.*> hierarchy at http://groups.google.com . Other
200 groups are listed at http://lists.perl.org/ ( also known as
201 http://lists.cpan.org/ ).
202
203 A nice place to ask questions is the PerlMonks site,
204 http://www.perlmonks.org/ , or the Perl Beginners mailing list
205 http://lists.perl.org/showlist.cgi?name=beginners .
206
207 Note that none of the above are supposed to write your code for you:
208 asking questions about particular problems or general advice is fine,
209 but asking someone to write your code for free is not very cool.
210
211 =head2 Where should I post source code?
212
213 You should post source code to whichever group is most appropriate, but
214 feel free to cross-post to comp.lang.perl.misc.  If you want to cross-post
215 to alt.sources, please make sure it follows their posting standards,
216 including setting the Followup-To header line to NOT include alt.sources;
217 see their FAQ ( http://www.faqs.org/faqs/alt-sources-intro/ ) for details.
218
219 If you're just looking for software, first use Google
220 ( http://www.google.com ), Google's Usenet search interface
221 ( http://groups.google.com ),  and CPAN Search ( http://search.cpan.org ).
222 This is faster and more productive than just posting a request.
223
224 =head2 Perl Books
225
226 A number of books on Perl and/or CGI programming are available.  A few
227 of these are good, some are OK, but many aren't worth your money.
228 There is a list of these books, some with extensive reviews, at
229 http://books.perl.org/ . If you don't see your book listed here, you
230 can write to perlfaq-workers@perl.org .
231
232 The incontestably definitive reference book on Perl, written by
233 the creator of Perl, is Programming Perl:
234
235         Programming Perl (the "Camel Book"):
236         by Larry Wall, Tom Christiansen, and Jon Orwant
237         ISBN 0-596-00027-8  [3rd edition July 2000]
238         http://www.oreilly.com/catalog/pperl3/
239         (English, translations to several languages are also available)
240
241 The companion volume to the Camel containing thousands
242 of real-world examples, mini-tutorials, and complete programs is:
243
244         The Perl Cookbook (the "Ram Book"):
245         by Tom Christiansen and Nathan Torkington,
246             with Foreword by Larry Wall
247         ISBN 0-596-00313-7 [2nd Edition August 2003]
248         http://www.oreilly.com/catalog/perlckbk2/
249
250 If you're already a seasoned programmer, then the Camel Book might
251 suffice for you to learn Perl.  If you're not, check out the
252 Llama book:
253
254         Learning Perl
255         by Randal L. Schwartz, Tom Phoenix, and brian d foy
256         ISBN 0-596-10105-8 [4th edition July 2005]
257         http://www.oreilly.com/catalog/learnperl4/
258
259 And for more advanced information on writing larger programs,
260 presented in the same style as the Llama book, continue your education
261 with the Alpaca book:
262
263         Intermediate Perl (the "Alpaca Book")
264         by Randal L. Schwartz and brian d foy, with Tom Phoenix (foreword by Damian Conway)
265         ISBN 0-596-10206-2 [1st edition March 2006]
266         http://www.oreilly.com/catalog/lrnperlorm/
267
268 Addison-Wesley ( http://www.awlonline.com/ ) and Manning
269 ( http://www.manning.com/ ) are also publishers of some fine Perl books
270 such as I<Object Oriented Programming with Perl> by Damian Conway and
271 I<Network Programming with Perl> by Lincoln Stein.
272
273 An excellent technical book discounter is Bookpool at
274 http://www.bookpool.com/ where a 30% discount or more is not unusual.
275
276 What follows is a list of the books that the FAQ authors found personally
277 useful.  Your mileage may (but, we hope, probably won't) vary.
278
279 Recommended books on (or mostly on) Perl follow.
280
281 =over 4
282
283 =item References
284
285         Programming Perl
286         by Larry Wall, Tom Christiansen, and Jon Orwant
287         ISBN 0-596-00027-8 [3rd edition July 2000]
288         http://www.oreilly.com/catalog/pperl3/
289
290         Perl 5 Pocket Reference
291         by Johan Vromans
292         ISBN 0-596-00374-9 [4th edition July 2002]
293         http://www.oreilly.com/catalog/perlpr4/
294
295 =item Tutorials
296
297         Beginning Perl
298         by James Lee
299         ISBN 1-59059-391-X [2nd edition August 2004]
300         http://apress.com/book/bookDisplay.html?bID=344
301
302         Elements of Programming with Perl
303         by Andrew L. Johnson
304         ISBN 1-884777-80-5 [1st edition October 1999]
305         http://www.manning.com/johnson/
306
307         Learning Perl
308         by Randal L. Schwartz, Tom Phoenix, and brian d foy
309         ISBN 0-596-52010-7 [5th edition June 2008]
310         http://oreilly.com/catalog/9780596520106/
311
312         Intermediate Perl (the "Alpaca Book")
313         by Randal L. Schwartz and brian d foy, with Tom Phoenix (foreword by Damian Conway)
314         ISBN 0-596-10206-2 [1st edition March 2006]
315         http://www.oreilly.com/catalog/intermediateperl/
316
317         Mastering Perl
318         by brian d foy
319         ISBN 0-596-52724-1 [1st edition July 2007]
320         http://www.oreilly.com/catalog/9780596527242/
321
322 =item Task-Oriented
323
324         Writing Perl Modules for CPAN
325         by Sam Tregar
326         ISBN 1-59059-018-X [1st edition August 2002]
327         http://apress.com/book/bookDisplay.html?bID=14
328
329         The Perl Cookbook
330         by Tom Christiansen and Nathan Torkington
331             with foreword by Larry Wall
332         ISBN 1-56592-243-3 [1st edition August 1998]
333         http://www.oreilly.com/catalog/cookbook/
334
335         Effective Perl Programming
336         by Joseph Hall
337         ISBN 0-201-41975-0 [1st edition 1998]
338         http://www.awl.com/
339
340         Real World SQL Server Administration with Perl
341         by Linchi Shea
342         ISBN 1-59059-097-X [1st edition July 2003]
343         http://apress.com/book/bookDisplay.html?bID=171
344
345 =item Special Topics
346
347         Perl Best Practices
348         by Damian Conway
349         ISBN: 0-596-00173-8 [1st edition July 2005]
350         http://www.oreilly.com/catalog/perlbp/
351
352         Higher Order Perl
353         by Mark-Jason Dominus
354         ISBN: 1558607013 [1st edition March 2005]
355         http://hop.perl.plover.com/
356
357         Perl 6 Now: The Core Ideas Illustrated with Perl 5
358         by Scott Walters
359         ISBN 1-59059-395-2 [1st edition December 2004]
360         http://apress.com/book/bookDisplay.html?bID=355
361
362         Mastering Regular Expressions
363         by Jeffrey E. F. Friedl
364         ISBN 0-596-00289-0 [2nd edition July 2002]
365         http://www.oreilly.com/catalog/regex2/
366
367         Network Programming with Perl
368         by Lincoln Stein
369         ISBN 0-201-61571-1 [1st edition 2001]
370         http://www.awlonline.com/
371
372         Object Oriented Perl
373         by Damian Conway
374             with foreword by Randal L. Schwartz
375         ISBN 1-884777-79-1 [1st edition August 1999]
376         http://www.manning.com/conway/
377
378         Data Munging with Perl
379         by Dave Cross
380         ISBN 1-930110-00-6 [1st edition 2001]
381         http://www.manning.com/cross
382
383         Mastering Perl/Tk
384         by Steve Lidie and Nancy Walsh
385         ISBN 1-56592-716-8 [1st edition January 2002]
386         http://www.oreilly.com/catalog/mastperltk/
387
388         Extending and Embedding Perl
389         by Tim Jenness and Simon Cozens
390         ISBN 1-930110-82-0 [1st edition August 2002]
391         http://www.manning.com/jenness
392
393         Perl Debugger Pocket Reference
394         by Richard Foley
395         ISBN 0-596-00503-2 [1st edition January 2004]
396         http://www.oreilly.com/catalog/perldebugpr/
397
398         Pro Perl Debugging
399         by Richard Foley with Andy Lester
400         ISBN 1-59059-454-1 [1st edition July 2005]
401         http://www.apress.com/book/view/1590594541
402
403 =back
404
405 =head2 Which magazines have Perl content?
406
407 I<The Perl Review> ( http://www.theperlreview.com ) focuses on Perl
408 almost completely (although it sometimes sneaks in an article about
409 another language). There's also I<$foo Magazin>, a german magazine
410 dedicated to Perl, at ( http://www.foo-magazin.de ).
411
412 The I<Perl-Zeitung> is a German-speaking magazine for Perl beginners
413 (see http://perl-zeitung.at.tf ).
414
415 Magazines that frequently carry quality articles on Perl include I<The
416 Perl Review> ( http://www.theperlreview.com ), I<Unix Review> (
417 http://www.unixreview.com/ ), I<Linux Magazine> (
418 http://www.linuxmagazine.com/ ), and Usenix's newsletter/magazine to
419 its members, I<login:> ( http://www.usenix.org/ ).
420
421 The Perl columns of Randal L. Schwartz are available on the web at
422 http://www.stonehenge.com/merlyn/WebTechniques/ ,
423 http://www.stonehenge.com/merlyn/UnixReview/ , and
424 http://www.stonehenge.com/merlyn/LinuxMag/ .
425
426 The first (and for a long time, only) periodical devoted to All Things
427 Perl, I<The Perl Journal> contains tutorials, demonstrations, case
428 studies, announcements, contests, and much more.  I<TPJ> has columns
429 on web development, databases, Win32 Perl, graphical programming,
430 regular expressions, and networking, and sponsors the Obfuscated Perl
431 Contest and the Perl Poetry Contests.  Beginning in November 2002, I<TPJ>
432 moved to a reader-supported monthly e-zine format in which subscribers
433 can download issues as PDF documents. In 2006, I<TPJ> merged with Dr.
434 Dobbs Journal (online edition). To read old I<TPJ> articles, see
435 http://www.ddj.com/ .
436
437 =head2 What mailing lists are there for Perl?
438
439 Most of the major modules (C<Tk>, C<CGI>, C<libwww-perl>) have their own
440 mailing lists.  Consult the documentation that came with the module for
441 subscription information.
442
443 A comprehensive list of Perl related mailing lists can be found at:
444
445         http://lists.perl.org/
446
447 =head2 Where are the archives for comp.lang.perl.misc?
448
449 The Google search engine now carries archived and searchable newsgroup
450 content.
451
452 http://groups.google.com/group/comp.lang.perl.misc/topics
453
454 If you have a question, you can be sure someone has already asked the
455 same question at some point on c.l.p.m. It requires some time and patience
456 to sift through all the content but often you will find the answer you
457 seek.
458
459 =head2 Where can I buy a commercial version of perl?
460
461 In a real sense, perl already I<is> commercial software: it has a license
462 that you can grab and carefully read to your manager. It is distributed
463 in releases and comes in well-defined packages. There is a very large
464 user community and an extensive literature.  The comp.lang.perl.*
465 newsgroups and several of the mailing lists provide free answers to your
466 questions in near real-time.  Perl has traditionally been supported by
467 Larry, scores of software designers and developers, and myriad
468 programmers, all working for free to create a useful thing to make life
469 better for everyone.
470
471 However, these answers may not suffice for managers who require a
472 purchase order from a company whom they can sue should anything go awry.
473 Or maybe they need very serious hand-holding and contractual obligations.
474 Shrink-wrapped CDs with perl on them are available from several sources if
475 that will help.  For example, many Perl books include a distribution of perl,
476 as do the O'Reilly Perl Resource Kits (in both the Unix flavor
477 and in the proprietary Microsoft flavor); the free Unix distributions
478 also all come with perl.
479
480 =head2 Where do I send bug reports?
481
482 (contributed by brian d foy)
483
484 First, ensure that you've found an actual bug. Second, ensure you've
485 found an actual bug.
486
487 If you've found a bug with the perl interpreter or one of the modules
488 in the standard library (those that come with Perl), you can use the
489 C<perlbug> utility that comes with Perl (>= 5.004). It collects
490 information about your installation to include with your message, then
491 sends the message to the right place.
492
493 To determine if a module came with your version of Perl, you can
494 use the C<Module::CoreList> module. It has the information about
495 the modules (with their versions) included with each release of Perl.
496
497 If C<Module::CoreList> is not installed on your system, check out
498 http://perlpunks.de/corelist .
499
500 Every CPAN module has a bug tracker set up in RT, http://rt.cpan.org .
501 You can submit bugs to RT either through its web interface or by
502 email. To email a bug report, send it to
503 bug-E<lt>distribution-nameE<gt>@rt.cpan.org . For example, if you
504 wanted to report a bug in C<Business::ISBN>, you could send a message to
505 bug-Business-ISBN@rt.cpan.org .
506
507 Some modules might have special reporting requirements, such as a
508 Sourceforge or Google Code tracking system, so you should check the
509 module documentation too.
510
511 =head2 What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
512
513 Perl.com at http://www.perl.com/ is part of the O'Reilly Network, a
514 subsidiary of O'Reilly Media.
515
516 The Perl Foundation is an advocacy organization for the Perl language
517 which maintains the web site http://www.perl.org/ as a general
518 advocacy site for the Perl language. It uses the domain to provide
519 general support services to the Perl community, including the hosting
520 of mailing lists, web sites, and other services.  There are also many
521 other sub-domains for special topics like learning Perl, Perl news, jobs
522 in Perl, such as:
523
524         http://learn.perl.org/
525         http://use.perl.org/
526         http://jobs.perl.org/
527         http://lists.perl.org/
528
529 Perl Mongers uses the pm.org domain for services related to Perl user
530 groups, including the hosting of mailing lists and web sites.  See the
531 Perl user group web site at http://www.pm.org/ for more information about
532 joining, starting, or requesting services for a Perl user group.
533
534 http://www.cpan.org/ is the Comprehensive Perl Archive Network,
535 a replicated worldwide repository of Perl software, see
536 the I<What is CPAN?> question earlier in this document.
537
538 =head1 AUTHOR AND COPYRIGHT
539
540 Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
541 other authors as noted. All rights reserved.
542
543 This documentation is free; you can redistribute it and/or modify it
544 under the same terms as Perl itself.
545
546 Irrespective of its distribution, all code examples here are in the public
547 domain.  You are permitted and encouraged to use this code and any
548 derivatives thereof in your own programs for fun or for profit as you
549 see fit.  A simple comment in the code giving credit to the FAQ would
550 be courteous but is not required.