Removal of a bunch of changes that don't merit perldelta integration
[perl.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 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 @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.  @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 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 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 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 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 $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 man command, or it's been misinstalled.  If that doesn't
160 work, try looking in /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 Aug 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         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         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 Magazines that frequently carry quality articles on Perl include I<The
413 Perl Review> ( http://www.theperlreview.com ), I<Unix Review> (
414 http://www.unixreview.com/ ), I<Linux Magazine> (
415 http://www.linuxmagazine.com/ ), and Usenix's newsletter/magazine to
416 its members, I<login:> ( http://www.usenix.org/ )
417
418 The Perl columns of Randal L. Schwartz are available on the web at
419 http://www.stonehenge.com/merlyn/WebTechniques/ ,
420 http://www.stonehenge.com/merlyn/UnixReview/ , and
421 http://www.stonehenge.com/merlyn/LinuxMag/ .
422
423 The first (and for a long time, only) periodical devoted to All Things
424 Perl, I<The Perl Journal> contains tutorials, demonstrations, case
425 studies, announcements, contests, and much more.  I<TPJ> has columns
426 on web development, databases, Win32 Perl, graphical programming,
427 regular expressions, and networking, and sponsors the Obfuscated Perl
428 Contest and the Perl Poetry Contests.  Beginning in November 2002, TPJ
429 moved to a reader-supported monthly e-zine format in which subscribers
430 can download issues as PDF documents. In 2006, TPJ merged with Dr.
431 Dobbs Journal (online edition). To read old TPJ articles, see
432 http://www.ddj.com/ .
433
434 =head2 What mailing lists are there for Perl?
435
436 Most of the major modules (Tk, CGI, libwww-perl) have their own
437 mailing lists.  Consult the documentation that came with the module for
438 subscription information.
439
440 A comprehensive list of Perl related mailing lists can be found at:
441
442         http://lists.perl.org/
443
444 =head2 Where are the archives for comp.lang.perl.misc?
445
446 The Google search engine now carries archived and searchable newsgroup
447 content.
448
449 http://groups.google.com/group/comp.lang.perl.misc/topics
450
451 If you have a question, you can be sure someone has already asked the
452 same question at some point on c.l.p.m. It requires some time and patience
453 to sift through all the content but often you will find the answer you
454 seek.
455
456 =head2 Where can I buy a commercial version of perl?
457
458 In a real sense, perl already I<is> commercial software: it has a license
459 that you can grab and carefully read to your manager. It is distributed
460 in releases and comes in well-defined packages. There is a very large
461 user community and an extensive literature.  The comp.lang.perl.*
462 newsgroups and several of the mailing lists provide free answers to your
463 questions in near real-time.  Perl has traditionally been supported by
464 Larry, scores of software designers and developers, and myriad
465 programmers, all working for free to create a useful thing to make life
466 better for everyone.
467
468 However, these answers may not suffice for managers who require a
469 purchase order from a company whom they can sue should anything go awry.
470 Or maybe they need very serious hand-holding and contractual obligations.
471 Shrink-wrapped CDs with perl on them are available from several sources if
472 that will help.  For example, many Perl books include a distribution of perl,
473 as do the O'Reilly Perl Resource Kits (in both the Unix flavor
474 and in the proprietary Microsoft flavor); the free Unix distributions
475 also all come with perl.
476
477 =head2 Where do I send bug reports?
478
479 (contributed by brian d foy)
480
481 First, ensure that you've found an actual bug. Second, ensure you've
482 found an actual bug.
483
484 If you've found a bug with the perl interpreter or one of the modules
485 in the standard library (those that come with Perl), you can use the
486 C<perlbug> utility that comes with Perl (>= 5.004). It collects
487 information about your installation to include with your message, then
488 sends the message to the right place.
489
490 To determine if a module came with your version of Perl, you can
491 use the C<Module::CoreList> module. It has the information about
492 the modules (with their versions) included with each release of Perl.
493
494 Every CPAN module has a bug tracker set up in RT, http://rt.cpan.org .
495 You can submit bugs to RT either through its web interface or by
496 email. To email a bug report, send it to
497 bug-E<lt>distribution-nameE<gt>@rt.cpan.org . For example, if you
498 wanted to report a bug in C<Business::ISBN>, you could send a message to
499 bug-Business-ISBN@rt.cpan.org .
500
501 Some modules might have special reporting requirements, such as a
502 Sourceforge or Google Code tracking system, so you should check the
503 module documentation too.
504
505 =head2 What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
506
507 Perl.com at http://www.perl.com/ is part of the O'Reilly Network, a
508 subsidiary of O'Reilly Media.
509
510 The Perl Foundation is an advocacy organization for the Perl language
511 which maintains the web site http://www.perl.org/ as a general
512 advocacy site for the Perl language. It uses the domain to provide
513 general support services to the Perl community, including the hosting
514 of mailing lists, web sites, and other services.  There are also many
515 other sub-domains for special topics like learning Perl, Perl news, jobs
516 in Perl, such as:
517
518         http://learn.perl.org/
519         http://use.perl.org/
520         http://jobs.perl.org/
521         http://lists.perl.org/
522
523 Perl Mongers uses the pm.org domain for services related to Perl user
524 groups, including the hosting of mailing lists and web sites.  See the
525 Perl user group web site at http://www.pm.org/ for more information about
526 joining, starting, or requesting services for a Perl user group.
527
528 http://www.cpan.org/ is the Comprehensive Perl Archive Network,
529 a replicated worldwide repository of Perl software, see
530 the I<What is CPAN?> question earlier in this document.
531
532 =head1 REVISION
533
534 Revision: $Revision$
535
536 Date: $Date$
537
538 See L<perlfaq> for source control details and availability.
539
540 =head1 AUTHOR AND COPYRIGHT
541
542 Copyright (c) 1997-2009 Tom Christiansen, Nathan Torkington, and
543 other authors as noted. All rights reserved.
544
545 This documentation is free; you can redistribute it and/or modify it
546 under the same terms as Perl itself.
547
548 Irrespective of its distribution, all code examples here are in the public
549 domain.  You are permitted and encouraged to use this code and any
550 derivatives thereof in your own programs for fun or for profit as you
551 see fit.  A simple comment in the code giving credit to the FAQ would
552 be courteous but is not required.