CPAN is upstream for Time::Local again
[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 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 There are many good books on Perl. See the L<perlbook> documentation or
227 ( http://books.perl.org ).
228
229 =head2 Which magazines have Perl content?
230
231 I<The Perl Review> ( http://www.theperlreview.com ) focuses on Perl
232 almost completely (although it sometimes sneaks in an article about
233 another language). There's also I<$foo Magazin>, a german magazine
234 dedicated to Perl, at ( http://www.foo-magazin.de ).
235
236 The I<Perl-Zeitung> is a German-speaking magazine for Perl beginners
237 (see http://perl-zeitung.at.tf ).
238
239 Magazines that frequently carry quality articles on Perl include I<The
240 Perl Review> ( http://www.theperlreview.com ), I<Unix Review> (
241 http://www.unixreview.com/ ), I<Linux Magazine> (
242 http://www.linuxmagazine.com/ ), and Usenix's newsletter/magazine to
243 its members, I<login:> ( http://www.usenix.org/ ).
244
245 The Perl columns of Randal L. Schwartz are available on the web at
246 http://www.stonehenge.com/merlyn/WebTechniques/ ,
247 http://www.stonehenge.com/merlyn/UnixReview/ , and
248 http://www.stonehenge.com/merlyn/LinuxMag/ .
249
250 The first (and for a long time, only) periodical devoted to All Things
251 Perl, I<The Perl Journal> contains tutorials, demonstrations, case
252 studies, announcements, contests, and much more. I<TPJ> has columns
253 on web development, databases, Win32 Perl, graphical programming,
254 regular expressions, and networking, and sponsors the Obfuscated Perl
255 Contest and the Perl Poetry Contests. Beginning in November 2002, I<TPJ>
256 moved to a reader-supported monthly e-zine format in which subscribers
257 can download issues as PDF documents. In 2006, I<TPJ> merged with Dr.
258 Dobbs Journal (online edition). To read old I<TPJ> articles, see
259 http://www.ddj.com/ , brian d foy's index of online TPJ content
260 ( http://www.perlmonks.org/index.pl?node_id=711609 ).
261
262 =head2 What mailing lists are there for Perl?
263
264 Most of the major modules (C<Tk>, C<CGI>, C<libwww-perl>) have their own
265 mailing lists. Consult the documentation that came with the module for
266 subscription information.
267
268 A comprehensive list of Perl related mailing lists can be found at:
269
270         http://lists.perl.org/
271
272 =head2 Where are the archives for comp.lang.perl.misc?
273
274 The Google search engine now carries archived and searchable newsgroup
275 content.
276
277 http://groups.google.com/group/comp.lang.perl.misc/topics
278
279 If you have a question, you can be sure someone has already asked the
280 same question at some point on c.l.p.m. It requires some time and patience
281 to sift through all the content but often you will find the answer you
282 seek.
283
284 =head2 Where can I buy a commercial version of perl?
285
286 In a real sense, perl already I<is> commercial software: it has a license
287 that you can grab and carefully read to your manager. It is distributed
288 in releases and comes in well-defined packages. There is a very large
289 user community and an extensive literature. The comp.lang.perl.*
290 newsgroups and several of the mailing lists provide free answers to your
291 questions in near real-time. Perl has traditionally been supported by
292 Larry, scores of software designers and developers, and myriad
293 programmers, all working for free to create a useful thing to make life
294 better for everyone.
295
296 However, these answers may not suffice for managers who require a
297 purchase order from a company whom they can sue should anything go awry.
298 Or maybe they need very serious hand-holding and contractual obligations.
299 Shrink-wrapped CDs with perl on them are available from several sources if
300 that will help. For example, many Perl books include a distribution of perl,
301 as do the O'Reilly Perl Resource Kits (in both the Unix flavor
302 and in the proprietary Microsoft flavor); the free Unix distributions
303 also all come with perl.
304
305 =head2 Where do I send bug reports?
306
307 (contributed by brian d foy)
308
309 First, ensure that you've found an actual bug. Second, ensure you've
310 found an actual bug.
311
312 If you've found a bug with the perl interpreter or one of the modules
313 in the standard library (those that come with Perl), you can use the
314 L<perlbug> utility that comes with Perl (>= 5.004). It collects
315 information about your installation to include with your message, then
316 sends the message to the right place.
317
318 To determine if a module came with your version of Perl, you can
319 use the C<Module::CoreList> module. It has the information about
320 the modules (with their versions) included with each release of Perl.
321
322 If C<Module::CoreList> is not installed on your system, check out
323 http://perlpunks.de/corelist .
324
325 Every CPAN module has a bug tracker set up in RT, http://rt.cpan.org .
326 You can submit bugs to RT either through its web interface or by
327 email. To email a bug report, send it to
328 bug-E<lt>distribution-nameE<gt>@rt.cpan.org . For example, if you
329 wanted to report a bug in C<Business::ISBN>, you could send a message to
330 bug-Business-ISBN@rt.cpan.org .
331
332 Some modules might have special reporting requirements, such as a
333 Sourceforge or Google Code tracking system, so you should check the
334 module documentation too.
335
336 =head2 What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
337
338 Perl.com ( http://www.perl.com/ ) used to be part of the O'Reilly
339 Network, a subsidiary of O'Reilly Media. Although it retains most of
340 the original content from its O'Reilly Network, it is now hosted by
341 The Perl Foundation.
342
343 The Perl Foundation is an advocacy organization for the Perl language
344 which maintains the web site ( http://www.perl.org/ ) as a general
345 advocacy site for the Perl language. It uses the domain to provide
346 general support services to the Perl community, including the hosting
347 of mailing lists, web sites, and other services. There are also many
348 other sub-domains for special topics like learning Perl, Perl news,
349 jobs in Perl, such as:
350
351         http://www.perl.org/
352         http://learn.perl.org/
353         http://jobs.perl.org/
354         http://lists.perl.org/
355
356 Perl Mongers uses the pm.org domain for services related to Perl user
357 groups, including the hosting of mailing lists and web sites. See the
358 Perl Mongers website ( http://www.pm.org/ ) for more information about
359 joining, starting, or requesting services for a Perl user group.
360
361 CPAN, or the Comprehensive Perl Archive Network (
362 http://www.cpan.org/ ), is a replicated, worldwide repository of Perl
363 software. See I<What is CPAN?> in L<perlfaq2>.
364
365 =head1 AUTHOR AND COPYRIGHT
366
367 Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
368 other authors as noted. All rights reserved.
369
370 This documentation is free; you can redistribute it and/or modify it
371 under the same terms as Perl itself.
372
373 Irrespective of its distribution, all code examples here are in the public
374 domain. You are permitted and encouraged to use this code and any
375 derivatives thereof in your own programs for fun or for profit as you
376 see fit. A simple comment in the code giving credit to the FAQ would
377 be courteous but is not required.