Debian Codegraph @

upstream/debian-unstable/man1/perlfaq2.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLFAQ2 1"
58 .TH PERLFAQ2 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlfaq2 \- Obtaining and Learning about Perl
65 .SH VERSION
66 .IX Header "VERSION"
67 version 5.20240218
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This section of the FAQ answers questions about where to find
71 source and documentation for Perl, support, and
72 related matters.
73 .SS "What machines support Perl? Where do I get it?"
74 .IX Subsection "What machines support Perl? Where do I get it?"
75 The standard release of Perl (the one maintained by the Perl
76 development team) is distributed only in source code form. You
77 can find the latest releases at <http://www.cpan.org/src/>.
78 .PP
79 Perl builds and runs on a bewildering number of platforms. Virtually
80 all known and current Unix derivatives are supported (perl's native
81 platform), as are other systems like VMS, DOS, OS/2, Windows,
82 QNX, BeOS, OS X, MPE/iX and the Amiga.
83 .PP
84 Binary distributions for some proprietary platforms can be found
85 <http://www.cpan.org/ports/> directory. Because these are not part of
86 the standard distribution, they may and in fact do differ from the
87 base perl port in a variety of ways. You'll have to check their
88 respective release notes to see just what the differences are. These
89 differences can be either positive (e.g. extensions for the features
90 of the particular platform that are not supported in the source
91 release of perl) or negative (e.g. might be based upon a less current
92 source release of perl).
93 .SS "How can I get a binary version of Perl?"
94 .IX Subsection "How can I get a binary version of Perl?"
95 See CPAN Ports <http://www.cpan.org/ports/>
96 .SS "I don't have a C compiler. How can I build my own Perl interpreter?"
97 .IX Subsection "I don't have a C compiler. How can I build my own Perl interpreter?"
98 For Windows, use a binary version of Perl,
99 Strawberry Perl <http://strawberryperl.com/> and
100 ActivePerl <http://www.activestate.com/activeperl> come with a
101 bundled C compiler.
102 .PP
103 Otherwise if you really do want to build Perl, you need to get a
104 binary version of \f(CW\*(C`gcc\*(C'\fR for your system first. Use a search
105 engine to find out how to do this for your operating system.
106 .SS "I copied the Perl binary from one machine to another, but scripts don't work."
107 .IX Subsection "I copied the Perl binary from one machine to another, but scripts don't work."
108 That's probably because you forgot libraries, or library paths differ.
109 You really should build the whole distribution on the machine it will
110 eventually live on, and then type \f(CW\*(C`make install\*(C'\fR. Most other
111 approaches are doomed to failure.
112 .PP
113 One simple way to check that things are in the right place is to print out
114 the hard-coded \f(CW@INC\fR that perl looks through for libraries:
115 .PP
116 .Vb 1
117 \& % perl \-le \*(Aqprint for @INC\*(Aq
118 .Ve
119 .PP
120 If this command lists any paths that don't exist on your system, then you
121 may need to move the appropriate libraries to these locations, or create
122 symbolic links, aliases, or shortcuts appropriately. \f(CW@INC\fR is also printed as
123 part of the output of
124 .PP
125 .Vb 1
126 \& % perl \-V
127 .Ve
128 .PP
129 You might also want to check out
130 "How do I keep my own module/library directory?" in perlfaq8.
131 .SS "I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?"
132 .IX Subsection "I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?"
133 Read the \fIINSTALL\fR file, which is part of the source distribution.
134 It describes in detail how to cope with most idiosyncrasies that the
135 \&\f(CW\*(C`Configure\*(C'\fR script can't work around for any given system or
136 architecture.
137 .SS "What modules and extensions are available for Perl? What is CPAN?"
138 .IX Subsection "What modules and extensions are available for Perl? What is CPAN?"
139 CPAN stands for Comprehensive Perl Archive Network, a multi-gigabyte
140 archive replicated on hundreds of machines all over the world. CPAN
141 contains tens of thousands of modules and extensions, source code
142 and documentation, designed for \fIeverything\fR from commercial
143 database interfaces to keyboard/screen control and running large web sites.
144 .PP
145 You can search CPAN on <http://metacpan.org>.
146 .PP
147 The master web site for CPAN is <http://www.cpan.org/>,
148 <http://www.cpan.org/SITES.html> lists all mirrors.
149 .PP
150 See the CPAN FAQ at <http://www.cpan.org/misc/cpan\-faq.html> for answers
151 to the most frequently asked questions about CPAN.
152 .PP
153 The Task::Kensho module has a list of recommended modules which
154 you should review as a good starting point.
155 .SS "Where can I get information on Perl?"
156 .IX Subsection "Where can I get information on Perl?"
157 .IP \(bu 4
158 <http://www.perl.org/>
159 .IP \(bu 4
160 <http://perldoc.perl.org/>
161 .IP \(bu 4
162 <http://learn.perl.org/>
163 .PP
164 The complete Perl documentation is available with the Perl distribution.
165 If you have Perl installed locally, you probably have the documentation
166 installed as well: type \f(CW\*(C`perldoc perl\*(C'\fR in a terminal or
167 view online <http://perldoc.perl.org/perl.html>.
168 .PP
169 (Some operating system distributions may ship the documentation in a different
170 package; for instance, on Debian, you need to install the \f(CW\*(C`perl\-doc\*(C'\fR package.)
171 .PP
172 Many good books have been written about Perl\-\-see the section later in
173 perlfaq2 for more details.
174 .SS "What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?"
175 .IX Subsection "What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?"
176 Perl.com <http://www.perl.com/> used to be part of the O'Reilly
177 Network, a subsidiary of O'Reilly Media. Although it retains most of
178 the original content from its O'Reilly Network, it is now hosted by
179 The Perl Foundation <http://www.perlfoundation.org/>.
180 .PP
181 The Perl Foundation is an advocacy organization for the Perl language
182 which maintains the web site <http://www.perl.org/> as a general
183 advocacy site for the Perl language. It uses the domain to provide
184 general support services to the Perl community, including the hosting
185 of mailing lists, web sites, and other services. There are also many
186 other sub-domains for special topics like learning Perl and jobs in Perl,
187 such as:
188 .IP \(bu 4
189 <http://www.perl.org/>
190 .IP \(bu 4
191 <http://learn.perl.org/>
192 .IP \(bu 4
193 <http://jobs.perl.org/>
194 .IP \(bu 4
195 <http://lists.perl.org/>
196 .PP
197 Perl Mongers <http://www.pm.org/> uses the pm.org domain for services
198 related to local Perl user groups, including the hosting of mailing lists
199 and web sites. See the Perl Mongers web site <http://www.pm.org/> for more
200 information about joining, starting, or requesting services for a
201 Perl user group.
202 .PP
203 CPAN, or the Comprehensive Perl Archive Network <http://www.cpan.org/>,
204 is a replicated, worldwide repository of Perl software.
205 See What is CPAN?.
206 .SS "Where can I post questions?"
207 .IX Subsection "Where can I post questions?"
208 There are many Perl mailing lists for various
209 topics, specifically the beginners list <http://lists.perl.org/list/beginners.html>
210 may be of use.
211 .PP
212 Other places to ask questions are on the
213 PerlMonks site <http://www.perlmonks.org/> or
214 stackoverflow <http://stackoverflow.com/questions/tagged/perl>.
215 .SS "Perl Books"
216 .IX Subsection "Perl Books"
217 There are many good books on Perl <http://www.perl.org/books/library.html>.
218 .SS "Which magazines have Perl content?"
219 .IX Subsection "Which magazines have Perl content?"
220 There are no current magazines that focus on Perl, although you sometimes
221 will find Perl content in more general interest programming titles.
222 .PP
223 In the distant past, there have been a few Perl magazines. The first was \fIThe Perl
224 Journal\fR, published by Jon Orwant. After that, there was \fIThe Perl Review\fR,
225 published by brian d foy, and \fR\f(CI$foo\fR\fI Magazin\fR, published by Renée Bäcker
226 (<http://www.foo\-magazin.de>).
227 .PP
228 The closest you might find today is Perl Weekly, (<https://perlweekly.com>),
229 an online newsletter with a magazine-like format.
230 .SS "Which Perl blogs should I read?"
231 .IX Subsection "Which Perl blogs should I read?"
232 Perl News <http://perlnews.org/> covers some of the major events in the Perl
233 world, Perl Weekly <http://perlweekly.com/> is a weekly e\-mail
234 (and RSS feed) of hand-picked Perl articles.
235 .PP
236 <http://blogs.perl.org/> hosts many Perl blogs, there are also
237 several blog aggregators: Perlsphere <http://perlsphere.net/> and
238 IronMan <http://ironman.enlightenedperl.org/> are two of them.
239 .SS "What mailing lists are there for Perl?"
240 .IX Subsection "What mailing lists are there for Perl?"
241 A comprehensive list of Perl-related mailing lists can be found at
242 <http://lists.perl.org/>
243 .SS "Where can I buy a commercial version of Perl?"
244 .IX Subsection "Where can I buy a commercial version of Perl?"
245 Perl already \fIis\fR commercial software: it has a license
246 that you can grab and carefully read to your manager. It is distributed
247 in releases and comes in well-defined packages. There is a very large
248 and supportive user community and an extensive literature.
249 .PP
250 If you still need commercial support
251 ActiveState <http://www.activestate.com/activeperl> offers
252 this.
253 .SS "Where do I send bug reports?"
254 .IX Subsection "Where do I send bug reports?"
255 (contributed by brian d foy)
256 .PP
257 First, ensure that you've found an actual bug. Second, ensure you've
258 found an actual bug.
259 .PP
260 If you've found a bug with the perl interpreter or one of the modules
261 in the standard library (those that come with Perl), submit a
262 bug report to the GitHub issue tracker at
263 <https://github.com/Perl/perl5/issues>.
264 .PP
265 To determine if a module came with your version of Perl, you can
266 install and use Module::CoreList. It knows the modules (with their
267 versions) included with each release of Perl:
268 .PP
269 .Vb 3
270 \& $ corelist File::Copy
271 \& Data for 2023\-07\-02
272 \& File::Copy was first released with perl 5.002
273 \&
274 \& $ corelist Business::ISBN
275 \& Data for 2023\-07\-02
276 \& Business::ISBN was not in CORE (or so I think)
277 .Ve
278 .PP
279 If the module does not come with Perl, report its issues
280 using the tool that the particular module author decided to use, such as
281 a GitHub or Google Code. The quickest way may be to check the MetaCPAN
282 page for the module (for example,
283 <https://metacpan.org/pod/Business::ISBN>), which shows the denoted
284 bugtracker in the left sidebar as the "Issues" link.
285 .PP
286 Also check the module's documentation, \fIREADME\fR, the build files
287 (\fIMakefile.PL\fR or \f(CW\*(C`Build.PL\*(C'\fR), or \fIMETA.{json,yml}\fR files. Although
288 many module authors follow the same pattern, some have their own way.
289 Use the directions you find.
290 .PP
291 Sometimes the module author does not declare a bugtracker. For a long
292 time, everyone assumed that the CPAN Request Tracker
293 (<https://rt.cpan.org>) was the bugtracker since every distribution had
294 an RT queue generated automatically. In somes cases, the author might
295 use CPAN RT. They also might have not declared a different
296 bugtracker but don't use CPAN RT.
297 .PP
298 Submit bugs to RT either through its web interface,
299 <https://rt.cpan.org>, or by email. Send email to \fIbug\-<distribution\-name>@rt.cpan.org\fR. For example, if you
300 wanted to report a bug in the example module Foo::Bar, you could send
301 a message to \fIbug\-Foo\[email protected]\fR.
302 .SH "AUTHOR AND COPYRIGHT"
303 .IX Header "AUTHOR AND COPYRIGHT"
304 Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and
305 other authors as noted. All rights reserved.
306 .PP
307 This documentation is free; you can redistribute it and/or modify it
308 under the same terms as Perl itself.
309 .PP
310 Irrespective of its distribution, all code examples here are in the public
311 domain. You are permitted and encouraged to use this code and any
312 derivatives thereof in your own programs for fun or for profit as you
313 see fit. A simple comment in the code giving credit to the FAQ would
314 be courteous but is not required.