Add missing test boilerplates to new MakeMaker tests
[perl.git] / INSTALL
1 If you read this file _as_is_, just ignore the funny characters you see.
2 It is written in the POD format (see pod/perlpod.pod) which is specially
3 designed to be readable as is.
4
5 =head1 NAME
6
7 Install - Build and Installation guide for perl 5.
8
9 =head1 SYNOPSIS
10
11 First, make sure you have an up-to-date version of Perl.  If you
12 didn't get your Perl source from CPAN, check the latest version at
13 http://www.cpan.org/src/.  Perl uses a version scheme where even-numbered
14 subreleases (like 5.8.x and 5.10.x) are stable maintenance releases and
15 odd-numbered subreleases (like 5.7.x and 5.9.x) are unstable
16 development releases.  Development releases should not be used in
17 production environments.  Fixes and new features are first carefully
18 tested in development releases and only if they prove themselves to be
19 worthy will they be migrated to the maintenance releases.
20
21 The basic steps to build and install perl 5 on a Unix system with all
22 the defaults are to run, from a freshly unpacked source tree:
23
24         sh Configure -de
25         make
26         make test
27         make install
28
29 Each of these is explained in further detail below.
30
31 The above commands will install Perl to /usr/local (or some other
32 platform-specific directory -- see the appropriate file in hints/.)
33 If that's not okay with you, you can run Configure interactively, by
34 just typing "sh Configure" (without the -de args). You can also specify
35 any prefix location by adding "-Dprefix='/some/dir'" to Configure's args.
36 To explicitly name the perl binary, use the command
37 "make install PERLNAME=myperl".
38
39 These options, and many more, are explained in further detail below.
40
41 If you have problems, corrections, or questions, please see
42 L<"Reporting Problems"> below.
43
44 For information on what's new in this release, see the
45 pod/perl5101delta.pod file.  For more information about how to find more
46 specific detail about changes, see the Changes file.
47
48 =head1 DESCRIPTION
49
50 This document is written in pod format as an easy way to indicate its
51 structure.  The pod format is described in pod/perlpod.pod, but you can
52 read it as is with any pager or editor.  Headings and items are marked
53 by lines beginning with '='.  The other mark-up used is
54
55     B<text>     embolden text, used for switches, programs or commands
56     C<code>     literal code
57     L<name>     A link (cross reference) to name
58     F<file>     A filename
59
60 Although most of the defaults are probably fine for most users,
61 you should probably at least skim through this document before
62 proceeding.
63
64 In addition to this file, check if there is a README file specific to
65 your operating system, since it may provide additional or different
66 instructions for building Perl.  If there is a hint file for your
67 system (in the hints/ directory) you might also want to read it
68 for even more information.
69
70 For additional information about porting Perl, see the section on
71 L<"Porting information"> below, and look at the files in the Porting/
72 directory.
73
74 =head1 PRELIMINARIES
75
76 =head2 Changes and Incompatibilities
77
78 Please see pod/perl5101delta.pod for a description of the changes and
79 potential incompatibilities introduced with this release.  A few of
80 the most important issues are listed below, but you should refer
81 to pod/perl5101delta.pod for more detailed information.
82
83 B<WARNING:> This version is not binary compatible with releases of
84 Perl prior to 5.10.0.
85 If you have built extensions (i.e. modules that include C code)
86 using an earlier version of Perl, you will need to rebuild and reinstall
87 those extensions.
88
89 Pure perl modules without XS or C code should continue to work fine
90 without reinstallation.  See the discussion below on
91 L<"Coexistence with earlier versions of perl 5"> for more details.
92
93 The standard extensions supplied with Perl will be handled automatically.
94
95 On a related issue, old modules may possibly be affected by the changes
96 in the Perl language in the current release.  Please see
97 pod/perl5101delta.pod for a description of what's changed.  See your
98 installed copy of the perllocal.pod file for a (possibly incomplete)
99 list of locally installed modules.  Also see CPAN::autobundle for one
100 way to make a "bundle" of your currently installed modules.
101
102 =head1 Run Configure
103
104 Configure will figure out various things about your system.  Some
105 things Configure will figure out for itself, other things it will ask
106 you about.  To accept the default, just press RETURN.   The default is
107 almost always okay.  It is normal for some things to be "NOT found",
108 since Configure often searches for many different ways of performing
109 the same function.
110
111 At any Configure prompt, you can type  &-d  and Configure will use the
112 defaults from then on.
113
114 After it runs, Configure will perform variable substitution on all the
115 *.SH files and offer to run make depend.
116
117 The results of a Configure run are stored in the config.sh and Policy.sh
118 files.
119
120 =head2 Common Configure options
121
122 Configure supports a number of useful options.  Run
123
124         Configure -h
125
126 to get a listing.  See the Porting/Glossary file for a complete list of
127 Configure variables you can set and their definitions.
128
129 =over 4
130
131 =item C compiler
132
133 To compile with gcc, if it's not the default compiler on your
134 system, you should run
135
136         sh Configure -Dcc=gcc
137
138 This is the preferred way to specify gcc (or any another alternative
139 compiler) so that the hints files can set appropriate defaults.
140
141 =item Installation prefix
142
143 By default, for most systems, perl will be installed in
144 /usr/local/{bin, lib, man}.  (See L<"Installation Directories">
145 and L<"Coexistence with earlier versions of perl 5"> below for
146 further details.)
147
148 You can specify a different 'prefix' for the default installation
149 directory when Configure prompts you, or by using the Configure command
150 line option -Dprefix='/some/directory', e.g.
151
152         sh Configure -Dprefix=/opt/perl
153
154 If your prefix contains the string "perl", then the suggested
155 directory structure is simplified.  For example, if you use
156 prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
157 /opt/perl/lib/perl5/.  Again, see L<"Installation Directories"> below
158 for more details.  Do not include a trailing slash, (i.e. /opt/perl/)
159 or you may experience odd test failures.
160
161 NOTE:  You must not specify an installation directory that is the same
162 as or below your perl source directory.  If you do, installperl will
163 attempt infinite recursion.
164
165 =item /usr/bin/perl
166
167 It may seem obvious, but Perl is useful only when users can easily
168 find it.  It's often a good idea to have both /usr/bin/perl and
169 /usr/local/bin/perl be symlinks to the actual binary.  Be especially
170 careful, however, not to overwrite a version of perl supplied by your
171 vendor unless you are sure you know what you are doing.  If you insist
172 on replacing your vendor's perl, useful information on how it was
173 configured may be found with
174
175         perl -V:config_args
176
177 (Check the output carefully, however, since this doesn't preserve
178 spaces in arguments to Configure.  For that, you have to look carefully
179 at config_arg1, config_arg2, etc.)
180
181 By default, Configure will not try to link /usr/bin/perl to the current
182 version of perl.  You can turn on that behavior by running
183
184         Configure -Dinstallusrbinperl
185
186 or by answering 'yes' to the appropriate Configure prompt.
187
188 In any case, system administrators are strongly encouraged to put
189 (symlinks to) perl and its accompanying utilities, such as perldoc,
190 into a directory typically found along a user's PATH, or in another
191 obvious and convenient place.
192
193 =item Building a development release
194
195 For development releases (odd subreleases, like 5.9.x) if you want to
196 use Configure -d, you will also need to supply -Dusedevel to Configure,
197 because the default answer to the question "do you really want to
198 Configure a development version?" is "no".  The -Dusedevel skips that
199 sanity check.
200
201 =back
202
203 If you are willing to accept all the defaults, and you want terse
204 output, you can run
205
206         sh Configure -des
207
208 =head2 Altering Configure variables for C compiler switches etc.
209
210 For most users, most of the Configure defaults are fine, or can easily
211 be set on the Configure command line.  However, if Configure doesn't
212 have an option to do what you want, you can change Configure variables
213 after the platform hints have been run by using Configure's -A switch.
214 For example, here's how to add a couple of extra flags to C compiler
215 invocations:
216
217         sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED"
218
219 To clarify, those ccflags values are not Configure options; if passed to
220 Configure directly, they won't do anything useful (they will define a
221 variable in config.sh, but without taking any action based upon it).
222 But when passed to the compiler, those flags will activate #ifdefd code.
223
224 For more help on Configure switches, run
225
226         sh Configure -h
227
228 =head2 Major Configure-time Build Options
229
230 There are several different ways to Configure and build perl for your
231 system.  For most users, the defaults are sensible and will work.
232 Some users, however, may wish to further customize perl.  Here are
233 some of the main things you can change.
234
235 =head3 Threads
236
237 On some platforms, perl can be compiled with support for threads.  To
238 enable this, run
239
240         sh Configure -Dusethreads
241
242 The default is to compile without thread support.
243
244 Perl used to have two different internal threads implementations.  The current
245 model (available internally since 5.6, and as a user-level module since 5.8) is
246 called interpreter-based implementation (ithreads), with one interpreter per
247 thread, and explicit sharing of data.  The (deprecated) 5.005 version
248 (5005threads) has been removed for release 5.10.
249
250 The 'threads' module is for use with the ithreads implementation.  The
251 'Thread' module emulates the old 5005threads interface on top of the current
252 ithreads model.
253
254 When using threads, perl uses a dynamically-sized buffer for some of
255 the thread-safe library calls, such as those in the getpw*() family.
256 This buffer starts small, but it will keep growing until the result
257 fits.  To get a fixed upper limit, you should compile Perl with
258 PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want.  One
259 way to do this is to run Configure with
260 C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>.
261
262 =head3 Large file support
263
264 Since Perl 5.6.0, Perl has supported large files (files larger than
265 2 gigabytes), and in many common platforms like Linux or Solaris this
266 support is on by default.
267
268 This is both good and bad. It is good in that you can use large files,
269 seek(), stat(), and -s them.  It is bad in that if you are interfacing Perl
270 using some extension, the components you are connecting to must also
271 be large file aware: if Perl thinks files can be large but the other
272 parts of the software puzzle do not understand the concept, bad things
273 will happen.
274
275 There's also one known limitation with the current large files
276 implementation: unless you also have 64-bit integers (see the next
277 section), you cannot use the printf/sprintf non-decimal integer formats
278 like C<%x> to print filesizes.  You can use C<%d>, though.
279
280 If you want to compile perl without large file support, use
281
282     sh Configure -Uuselargefiles
283
284 =head3 64 bit support
285
286 If your platform does not run natively at 64 bits, but can simulate
287 them with compiler flags and/or C<long long> or C<int64_t>,
288 you can build a perl that uses 64 bits.
289
290 There are actually two modes of 64-bitness: the first one is achieved
291 using Configure -Duse64bitint and the second one using Configure
292 -Duse64bitall.  The difference is that the first one is minimal and
293 the second one maximal.  The first works in more places than the second.
294
295 The C<use64bitint> option does only as much as is required to get
296 64-bit integers into Perl (this may mean, for example, using "long
297 longs") while your memory may still be limited to 2 gigabytes (because
298 your pointers could still be 32-bit).  Note that the name C<64bitint>
299 does not imply that your C compiler will be using 64-bit C<int>s (it
300 might, but it doesn't have to).  The C<use64bitint> simply means that
301 you will be able to have 64 bit-wide scalar values.
302
303 The C<use64bitall> option goes all the way by attempting to switch
304 integers (if it can), longs (and pointers) to being 64-bit.  This may
305 create an even more binary incompatible Perl than -Duse64bitint: the
306 resulting executable may not run at all in a 32-bit box, or you may
307 have to reboot/reconfigure/rebuild your operating system to be 64-bit
308 aware.
309
310 Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
311 On these systems, it might be the default compilation mode, and there
312 is currently no guarantee that passing no use64bitall option to the
313 Configure process will build a 32bit perl. Implementing -Duse32bit*
314 options is planned for perl 5.12.
315
316 =head3 Long doubles
317
318 In some systems you may be able to use long doubles to enhance the
319 range and precision of your double precision floating point numbers
320 (that is, Perl's numbers).  Use Configure -Duselongdouble to enable
321 this support (if it is available).
322
323 =head3 "more bits"
324
325 You can "Configure -Dusemorebits" to turn on both the 64-bit support
326 and the long double support.
327
328 =head3 Algorithmic Complexity Attacks on Hashes
329
330 In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
331 Processing such hashes would consume large amounts of CPU time,
332 enabling a "Denial of Service" attack against Perl.  Such hashes may be
333 a problem for example for mod_perl sites, sites with Perl CGI scripts
334 and web services, that process data originating from external sources.
335
336 In Perl 5.8.1 a security feature was introduced to make it harder to
337 create such degenerate hashes. A visible side effect of this was that
338 the keys(), values(), and each() functions may return the hash elements
339 in different order between different runs of Perl even with the same
340 data.  It also had unintended binary incompatibility issues with
341 certain modules compiled against Perl 5.8.0.
342
343 In Perl 5.8.2 an improved scheme was introduced.  Hashes will return
344 elements in the same order as Perl 5.8.0 by default.  On a hash by hash
345 basis, if pathological data is detected during a hash key insertion,
346 then that hash will switch to an alternative random hash seed.  As
347 adding keys can always dramatically change returned hash element order,
348 existing programs will not be affected by this, unless they
349 specifically test for pre-recorded hash return order for contrived
350 data. (eg the list of keys generated by C<map {"\0"x$_} 0..15> trigger
351 randomisation) In effect the new implementation means that 5.8.1 scheme
352 is only being used on hashes which are under attack.
353
354 One can still revert to the old guaranteed repeatable order (and be
355 vulnerable to attack by wily crackers) by setting the environment
356 variable PERL_HASH_SEED, see L<perlrun/PERL_HASH_SEED>.  Another option
357 is to add -DUSE_HASH_SEED_EXPLICIT to the compilation flags (for
358 example by using C<Configure -Accflags=-DUSE_HASH_SEED_EXPLICIT>), in
359 which case one has to explicitly set the PERL_HASH_SEED environment
360 variable to enable the security feature, or by adding -DNO_HASH_SEED to
361 the compilation flags to completely disable the randomisation feature.
362
363 B<Perl has never guaranteed any ordering of the hash keys>, and the
364 ordering has already changed several times during the lifetime of Perl
365 5.  Also, the ordering of hash keys has always been, and continues to
366 be, affected by the insertion order.  Note that because of this
367 randomisation for example the Data::Dumper results will be different
368 between different runs of Perl, since Data::Dumper by default dumps
369 hashes "unordered".  The use of the Data::Dumper C<Sortkeys> option is
370 recommended.
371
372 =head3 SOCKS
373
374 Perl can be configured to be 'socksified', that is, to use the SOCKS
375 TCP/IP proxy protocol library.  SOCKS is used to give applications
376 access to transport layer network proxies.  Perl supports only SOCKS
377 Version 5.  The corresponding Configure option is -Dusesocks.
378 You can find more about SOCKS from wikipedia at
379 L<http://en.wikipedia.org/wiki/SOCKS>.
380
381 =head3 Dynamic Loading
382
383 By default, Configure will compile perl to use dynamic loading.
384 If you want to force perl to be compiled completely
385 statically, you can either choose this when Configure prompts you or
386 you can use the Configure command line option -Uusedl.
387 With this option, you won't be able to use any new extension
388 (XS) module without recompiling perl itself.
389
390 =head3 Building a shared Perl library
391
392 Currently, for most systems, the main perl executable is built by
393 linking the "perl library" libperl.a with perlmain.o, your static
394 extensions, and various extra libraries, such as -lm.
395
396 On systems that support dynamic loading, it may be possible to
397 replace libperl.a with a shared libperl.so.  If you anticipate building
398 several different perl binaries (e.g. by embedding libperl into
399 different programs, or by using the optional compiler extension), then
400 you might wish to build a shared libperl.so so that all your binaries
401 can share the same library.
402
403 The disadvantages are that there may be a significant performance
404 penalty associated with the shared libperl.so, and that the overall
405 mechanism is still rather fragile with respect to different versions
406 and upgrades.
407
408 In terms of performance, on my test system (Solaris 2.5_x86) the perl
409 test suite took roughly 15% longer to run with the shared libperl.so.
410 Your system and typical applications may well give quite different
411 results.
412
413 The default name for the shared library is typically something like
414 libperl.so.5.8.8 (for Perl 5.8.8), or libperl.so.588, or simply
415 libperl.so.  Configure tries to guess a sensible naming convention
416 based on your C library name.  Since the library gets installed in a
417 version-specific architecture-dependent directory, the exact name
418 isn't very important anyway, as long as your linker is happy.
419
420 You can elect to build a shared libperl by
421
422         sh Configure -Duseshrplib
423
424 To build a shared libperl, the environment variable controlling shared
425 library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
426 NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
427 for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
428 the Perl build directory because that's where the shared libperl will
429 be created.  Configure arranges makefile to have the correct shared
430 library search settings.  You can find the name of the environment
431 variable Perl thinks works in your your system by
432
433         grep ldlibpthname config.sh
434
435 However, there are some special cases where manually setting the
436 shared library path might be required.  For example, if you want to run
437 something like the following with the newly-built but not-yet-installed
438 ./perl:
439
440         cd t; ./perl -MTestInit misc/failing_test.t
441
442 or
443
444         ./perl -Ilib ~/my_mission_critical_test
445
446 then you need to set up the shared library path explicitly.
447 You can do this with
448
449    LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
450
451 for Bourne-style shells, or
452
453    setenv LD_LIBRARY_PATH `pwd`
454
455 for Csh-style shells.  (This procedure may also be needed if for some
456 unexpected reason Configure fails to set up makefile correctly.) (And
457 again, it may be something other than LD_LIBRARY_PATH for you, see above.)
458
459 You can often recognize failures to build/use a shared libperl from error
460 messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
461 for example:
462
463     18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
464
465 There is also an potential problem with the shared perl library if you
466 want to have more than one "flavor" of the same version of perl (e.g.
467 with and without -DDEBUGGING).  For example, suppose you build and
468 install a standard Perl 5.10.0 with a shared library.  Then, suppose you
469 try to build Perl 5.10.0 with -DDEBUGGING enabled, but everything else
470 the same, including all the installation directories.  How can you
471 ensure that your newly built perl will link with your newly built
472 libperl.so.8 rather with the installed libperl.so.8?  The answer is
473 that you might not be able to.  The installation directory is encoded
474 in the perl binary with the LD_RUN_PATH environment variable (or
475 equivalent ld command-line option).  On Solaris, you can override that
476 with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
477 LD_PRELOAD, specifying the exact filename you wish to be used; and on
478 Digital Unix, you can override LD_LIBRARY_PATH by setting the
479 _RLD_ROOT environment variable to point to the perl build directory.
480
481 In other words, it is generally not a good idea to try to build a perl
482 with a shared library if $archlib/CORE/$libperl already exists from a
483 previous build.
484
485 A good workaround is to specify a different directory for the
486 architecture-dependent library for your -DDEBUGGING version of perl.
487 You can do this by changing all the *archlib* variables in config.sh to
488 point to your new architecture-dependent library.
489
490 =head3 Environment access
491
492 Perl often needs to write to the program's environment, such as when C<%ENV>
493 is assigned to. Many implementations of the C library function C<putenv()>
494 leak memory, so where possible perl will manipulate the environment directly
495 to avoid these leaks. The default is now to perform direct manipulation
496 whenever perl is running as a stand alone interpreter, and to call the safe
497 but potentially leaky C<putenv()> function when the perl interpreter is
498 embedded in another application. You can force perl to always use C<putenv()>
499 by compiling with -DPERL_USE_SAFE_PUTENV. You can force an embedded perl to
500 use direct manipulation by setting C<PL_use_safe_putenv = 0;> after the
501 C<perl_construct()> call.
502
503 =head2 Installation Directories
504
505 The installation directories can all be changed by answering the
506 appropriate questions in Configure.  For convenience, all the installation
507 questions are near the beginning of Configure.  Do not include trailing
508 slashes on directory names.  At any point during the Configure process,
509 you can answer a question with  &-d  and Configure will use the defaults
510 from then on.  Alternatively, you can
511
512         grep '^install' config.sh
513
514 after Configure has run to verify the installation paths.
515
516 The defaults are intended to be reasonable and sensible for most
517 people building from sources.  Those who build and distribute binary
518 distributions or who export perl to a range of systems will probably
519 need to alter them.  If you are content to just accept the defaults,
520 you can safely skip the next section.
521
522 The directories set up by Configure fall into three broad categories.
523
524 =over 4
525
526 =item Directories for the perl distribution
527
528 By default, Configure will use the following directories for 5.10.0.
529 $version is the full perl version number, including subversion, e.g.
530 5.10.0 or 5.9.5, and $archname is a string like sun4-sunos,
531 determined by Configure.  The full definitions of all Configure
532 variables are in the file Porting/Glossary.
533
534     Configure variable  Default value
535     $prefixexp          /usr/local
536     $binexp             $prefixexp/bin
537     $scriptdirexp       $prefixexp/bin
538     $privlibexp         $prefixexp/lib/perl5/$version
539     $archlibexp         $prefixexp/lib/perl5/$version/$archname
540     $man1direxp         $prefixexp/man/man1
541     $man3direxp         $prefixexp/man/man3
542     $html1direxp        (none)
543     $html3direxp        (none)
544
545 $prefixexp is generated from $prefix, with ~ expansion done to convert home
546 directories into absolute paths. Similarly for the other variables listed. As
547 file system calls do not do this, you should always reference the ...exp
548 variables, to support users who build perl in their home directory.
549
550 Actually, Configure recognizes the SVR3-style
551 /usr/local/man/l_man/man1 directories, if present, and uses those
552 instead.  Also, if $prefix contains the string "perl", the library
553 directories are simplified as described below.  For simplicity, only
554 the common style is shown here.
555
556 =item Directories for site-specific add-on files
557
558 After perl is installed, you may later wish to add modules (e.g. from
559 CPAN) or scripts.  Configure will set up the following directories to
560 be used for installing those add-on modules and scripts.
561
562     Configure variable  Default value
563     $siteprefixexp      $prefixexp
564     $sitebinexp         $siteprefixexp/bin
565     $sitescriptexp      $siteprefixexp/bin
566     $sitelibexp         $siteprefixexp/lib/perl5/site_perl/$version
567     $sitearchexp        $siteprefixexp/lib/perl5/site_perl/$version/$archname
568     $siteman1direxp     $siteprefixexp/man/man1
569     $siteman3direxp     $siteprefixexp/man/man3
570     $sitehtml1direxp    (none)
571     $sitehtml3direxp    (none)
572
573 By default, ExtUtils::MakeMaker will install architecture-independent
574 modules into $sitelib and architecture-dependent modules into $sitearch.
575
576 =item Directories for vendor-supplied add-on files
577
578 Lastly, if you are building a binary distribution of perl for
579 distribution, Configure can optionally set up the following directories
580 for you to use to distribute add-on modules.
581
582     Configure variable  Default value
583     $vendorprefixexp    (none)
584     (The next ones are set only if vendorprefix is set.)
585     $vendorbinexp       $vendorprefixexp/bin
586     $vendorscriptexp    $vendorprefixexp/bin
587     $vendorlibexp
588         $vendorprefixexp/lib/perl5/vendor_perl/$version
589     $vendorarchexp
590         $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
591     $vendorman1direxp   $vendorprefixexp/man/man1
592     $vendorman3direxp   $vendorprefixexp/man/man3
593     $vendorhtml1direxp  (none)
594     $vendorhtml3direxp  (none)
595
596 These are normally empty, but may be set as needed.  For example,
597 a vendor might choose the following settings:
598
599     $prefix             /usr
600     $siteprefix         /usr/local
601     $vendorprefix       /usr
602
603 This would have the effect of setting the following:
604
605     $binexp             /usr/bin
606     $scriptdirexp       /usr/bin
607     $privlibexp         /usr/lib/perl5/$version
608     $archlibexp         /usr/lib/perl5/$version/$archname
609     $man1direxp         /usr/man/man1
610     $man3direxp         /usr/man/man3
611
612     $sitebinexp         /usr/local/bin
613     $sitescriptexp      /usr/local/bin
614     $sitelibexp         /usr/local/lib/perl5/site_perl/$version
615     $sitearchexp        /usr/local/lib/perl5/site_perl/$version/$archname
616     $siteman1direxp     /usr/local/man/man1
617     $siteman3direxp     /usr/local/man/man3
618
619     $vendorbinexp       /usr/bin
620     $vendorscriptexp    /usr/bin
621     $vendorlibexp       /usr/lib/perl5/vendor_perl/$version
622     $vendorarchexp      /usr/lib/perl5/vendor_perl/$version/$archname
623     $vendorman1direxp   /usr/man/man1
624     $vendorman3direxp   /usr/man/man3
625
626 Note how in this example, the vendor-supplied directories are in the
627 /usr hierarchy, while the directories reserved for the end-user are in
628 the /usr/local hierarchy.
629
630 The entire installed library hierarchy is installed in locations with
631 version numbers, keeping the installations of different versions distinct.
632 However, later installations of Perl can still be configured to search the
633 installed libraries corresponding to compatible earlier versions.
634 See L<"Coexistence with earlier versions of perl 5"> below for more details
635 on how Perl can be made to search older version directories.
636
637 Of course you may use these directories however you see fit.  For
638 example, you may wish to use $siteprefix for site-specific files that
639 are stored locally on your own disk and use $vendorprefix for
640 site-specific files that are stored elsewhere on your organization's
641 network.  One way to do that would be something like
642
643         sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
644
645 =item otherlibdirs
646
647 As a final catch-all, Configure also offers an $otherlibdirs
648 variable.  This variable contains a colon-separated list of additional
649 directories to add to @INC.  By default, it will be empty.
650 Perl will search these directories (including architecture and
651 version-specific subdirectories) for add-on modules and extensions.
652
653 For example, if you have a bundle of perl libraries from a previous
654 installation, perhaps in a strange place:
655
656         Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
657
658 =item APPLLIB_EXP
659
660 There is one other way of adding paths to @INC at perl build time, and
661 that is by setting the APPLLIB_EXP C pre-processor token to a colon-
662 separated list of directories, like this
663
664        sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
665
666 The directories defined by APPLLIB_EXP get added to @INC I<first>,
667 ahead of any others, and so provide a way to override the standard perl
668 modules should you, for example, want to distribute fixes without
669 touching the perl distribution proper.  And, like otherlib dirs,
670 version and architecture specific subdirectories are also searched, if
671 present, at run time.  Of course, you can still search other @INC
672 directories ahead of those in APPLLIB_EXP by using any of the standard
673 run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
674
675 =item usesitecustomize
676
677 Run-time customization of @INC can be enabled with:
678
679         sh Configure -Dusesitecustomize
680
681 which will define USE_SITECUSTOMIZE and $Config{usesitecustomize}.
682 When enabled, this makes perl run F<$sitelibexp/sitecustomize.pl> before
683 anything else.  This script can then be set up to add additional
684 entries to @INC.
685
686 =item Man Pages
687
688 By default, man pages will be installed in $man1dir and $man3dir, which
689 are normally /usr/local/man/man1 and /usr/local/man/man3.  If you
690 want to use a .3pm suffix for perl man pages, you can do that with
691
692         sh Configure -Dman3ext=3pm
693
694 =item HTML pages
695
696 Currently, the standard perl installation does not do anything with
697 HTML documentation, but that may change in the future.  Further, some
698 add-on modules may wish to install HTML documents.  The html Configure
699 variables listed above are provided if you wish to specify where such
700 documents should be placed.  The default is "none", but will likely
701 eventually change to something useful based on user feedback.
702
703 =back
704
705 Some users prefer to append a "/share" to $privlib and $sitelib
706 to emphasize that those directories can be shared among different
707 architectures.
708
709 Note that these are just the defaults.  You can actually structure the
710 directories any way you like.  They don't even have to be on the same
711 filesystem.
712
713 Further details about the installation directories, maintenance and
714 development subversions, and about supporting multiple versions are
715 discussed in L<"Coexistence with earlier versions of perl 5"> below.
716
717 If you specify a prefix that contains the string "perl", then the
718 library directory structure is slightly simplified.  Instead of
719 suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
720
721 Thus, for example, if you Configure with
722 -Dprefix=/opt/perl, then the default library directories for 5.9.0 are
723
724     Configure variable  Default value
725         $privlib        /opt/perl/lib/5.9.0
726         $archlib        /opt/perl/lib/5.9.0/$archname
727         $sitelib        /opt/perl/lib/site_perl/5.9.0
728         $sitearch       /opt/perl/lib/site_perl/5.9.0/$archname
729
730 =head2 Changing the installation directory
731
732 Configure distinguishes between the directory in which perl (and its
733 associated files) should be installed, and the directory in which it
734 will eventually reside.  For most sites, these two are the same; for
735 sites that use AFS, this distinction is handled automatically.
736 However, sites that use package management software such as rpm or
737 dpkg, or users building binary packages for distribution may also
738 wish to install perl into a different directory before moving perl
739 to its final destination.  There are two ways to do that:
740
741 =over 4
742
743 =item installprefix
744
745 To install perl under the /tmp/perl5 directory, use the following
746 command line:
747
748     sh Configure -Dinstallprefix=/tmp/perl5
749
750 (replace /tmp/perl5 by a directory of your choice).
751
752 Beware, though, that if you go to try to install new add-on
753 modules, they too will get installed in under '/tmp/perl5' if you
754 follow this example.  That's why it's usually better to use DESTDIR,
755 as shown in the next section.
756
757 =item DESTDIR
758
759 If you need to install perl on many identical systems, it is convenient
760 to compile it once and create an archive that can be installed on
761 multiple systems.  Suppose, for example, that you want to create an
762 archive that can be installed in /opt/perl.  One way to do that is by
763 using the DESTDIR variable during C<make install>.  The DESTDIR is
764 automatically prepended to all the installation paths.  Thus you
765 simply do:
766
767     sh Configure -Dprefix=/opt/perl -des
768     make
769     make test
770     make install DESTDIR=/tmp/perl5
771     cd /tmp/perl5/opt/perl
772     tar cvf /tmp/perl5-archive.tar .
773
774 =back
775
776 =head2 Site-wide Policy settings
777
778 After Configure runs, it stores a number of common site-wide "policy"
779 answers (such as installation directories) in the Policy.sh file.
780 If you want to build perl on another system using the same policy
781 defaults, simply copy the Policy.sh file to the new system's perl build
782 directory, and Configure will use it. This will work even if Policy.sh was
783 generated for another version of Perl, or on a system with a
784 different architecture and/or operating system. However, in such cases,
785 you should review the contents of the file before using it: for
786 example, your new target may not keep its man pages in the same place
787 as the system on which the file was generated.
788
789 Alternatively, if you wish to change some or all of those policy
790 answers, you should
791
792         rm -f Policy.sh
793
794 to ensure that Configure doesn't re-use them.
795
796 Further information is in the Policy_sh.SH file itself.
797
798 If the generated Policy.sh file is unsuitable, you may freely edit it
799 to contain any valid shell commands.  It will be run just after the
800 platform-specific hints files.
801
802 =head2 Disabling older versions of Perl
803
804 Configure will search for binary compatible versions of previously
805 installed perl binaries in the tree that is specified as target tree,
806 and these will be used as locations to search for modules by the perl
807 being built. The list of perl versions found will be put in the Configure
808 variable inc_version_list.
809
810 To disable this use of older perl modules, even completely valid pure perl
811 modules, you can specify to not include the paths found:
812
813        sh Configure -Dinc_version_list=none ...
814
815 When using the newer perl, you can add these paths again in the
816 $PERL5LIB environment variable or with perl's -I runtime option.
817
818 =head2 Building Perl outside of the source directory
819
820 Sometimes it is desirable to build Perl in a directory different from
821 where the sources are, for example if you want to keep your sources
822 read-only, or if you want to share the sources between different binary
823 architectures.  You can do this (if your file system supports symbolic
824 links) by
825
826         mkdir /tmp/perl/build/directory
827         cd /tmp/perl/build/directory
828         sh /path/to/perl/source/Configure -Dmksymlinks ...
829
830 This will create in /tmp/perl/build/directory a tree of symbolic links
831 pointing to files in /path/to/perl/source.  The original files are left
832 unaffected.  After Configure has finished you can just say
833
834         make
835         make test
836         make install
837
838 as usual, and Perl will be built in /tmp/perl/build/directory.
839
840 =head2 Building a debugging perl
841
842 You can run perl scripts under the perl debugger at any time with
843 B<perl -d your_script>.  If, however, you want to debug perl itself,
844 you probably want to have support for perl internal debugging code
845 (activated by adding -DDEBUGGING to ccflags), and/or support for the
846 system debugger by adding -g to the optimisation flags. For that,
847 use the parameter:
848
849         sh Configure -DDEBUGGING
850
851 or
852
853         sh Configure -DDEBUGGING=<mode>
854
855 For a more eye appealing call, -DEBUGGING is defined to be an alias
856 for -DDEBUGGING. For both, the -U calls are also supported, in order
857 to be able to overrule the hints or Policy.sh settings.
858
859 Here are the DEBUGGING modes:
860
861 =over 4
862
863 =item -DDEBUGGING
864
865 =item -DEBUGGING
866
867 =item -DEBUGGING=both
868
869 Sets both -DDEBUGGING in the ccflags, and adds -g to optimize.
870
871 You can actually specify -g and -DDEBUGGING independently (see below),
872 but usually it's convenient to have both.
873
874 =item -DEBUGGING=-g
875
876 =item -Doptimize=-g
877
878 Adds -g to optimize, but does not set -DDEBUGGING.
879
880 (Note:  Your system may actually require something like cc -g2.
881 Check your man pages for cc(1) and also any hint file for your system.)
882
883 =item -DEBUGGING=none
884
885 =item -UDEBUGGING
886
887 Removes -g from optimize, and -DDEBUGGING from ccflags.
888
889 =back
890
891 If you are using a shared libperl, see the warnings about multiple
892 versions of perl under L<Building a shared Perl library>.
893
894 =head2 Extensions
895
896 Perl ships with a number of standard extensions.  These are contained
897 in the ext/ subdirectory.
898
899 By default, Configure will offer to build every extension which appears
900 to be supported.  For example, Configure will offer to build GDBM_File
901 only if it is able to find the gdbm library.
902
903 To disable certain extensions so that they are not built, use the
904 -Dnoextensions=... and -Donlyextensions=... options.  They both accept
905 a space-separated list of extensions.  The extensions listed in
906 C<noextensions> are removed from the list of extensions to build, while
907 the C<onlyextensions> is rather more severe and builds only the listed
908 extensions.  The latter should be used with extreme caution since
909 certain extensions are used by many other extensions and modules:
910 examples of such modules include Fcntl and IO.  The order of processing
911 these options is first C<only> (if present), then C<no> (if present).
912
913 Of course, you may always run Configure interactively and select only
914 the extensions you want.
915
916 If you unpack any additional extensions in the ext/ directory before
917 running Configure, then Configure will offer to build those additional
918 extensions as well.  Most users probably shouldn't have to do this --
919 it is usually easier to build additional extensions later after perl
920 has been installed.  However, if you wish to have those additional
921 extensions statically linked into the perl binary, then this offers a
922 convenient way to do that in one step.  (It is not necessary, however;
923 you can build and install extensions just fine even if you don't have
924 dynamic loading.  See lib/ExtUtils/MakeMaker.pm for more details.)
925 Another way of specifying extra modules is described in
926 L<"Adding extra modules to the build"> below.
927
928 If you re-use an old config.sh but change your system (e.g. by
929 adding libgdbm) Configure will still offer your old choices of extensions
930 for the default answer, but it will also point out the discrepancy to
931 you.
932
933 =head2 Including locally-installed libraries
934
935 Perl comes with interfaces to number of libraries, including threads,
936 dbm, ndbm, gdbm, and Berkeley db.  For the *db* extension, if
937 Configure can find the appropriate header files and libraries, it will
938 automatically include that extension.  The threading extension needs
939 to be specified explicitely (see L<Threads>).
940
941 Those libraries are not distributed with perl. If your header (.h) files
942 for those libraries are not in a directory normally searched by your C
943 compiler, then you will need to include the appropriate -I/your/directory
944 option when prompted by Configure.  If your libraries are not in a
945 directory normally searched by your C compiler and linker, then you will
946 need to include the appropriate -L/your/directory option when prompted
947 by Configure. See the examples below.
948
949 =head3 Examples
950
951 =over 4
952
953 =item gdbm in /usr/local
954
955 Suppose you have gdbm and want Configure to find it and build the
956 GDBM_File extension.  This example assumes you have gdbm.h
957 installed in /usr/local/include/gdbm.h and libgdbm.a installed in
958 /usr/local/lib/libgdbm.a.  Configure should figure all the
959 necessary steps out automatically.
960
961 Specifically, when Configure prompts you for flags for
962 your C compiler, you should include -I/usr/local/include, if it's
963 not here yet. Similarly, when Configure prompts you for linker flags,
964 you should include -L/usr/local/lib.
965
966 If you are using dynamic loading, then when Configure prompts you for
967 linker flags for dynamic loading, you should again include
968 -L/usr/local/lib.
969
970 Again, this should all happen automatically.  This should also work if
971 you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
972 /opt/gnu, /usr/GNU, or /opt/GNU).
973
974 =item BerkeleyDB in /usr/local/BerkeleyDB
975
976 The version of BerkeleyDB distributed by sleepycat.com installs in a
977 version-specific directory by default, typically something like
978 /usr/local/BerkeleyDB.4.7.  To have Configure find that, you need to add
979 -I/usr/local/BerkeleyDB.4.7/include to cc flags, as in the previous example,
980 and you will also have to take extra steps to help Configure find -ldb.
981 Specifically, when Configure prompts you for library directories,
982 add /usr/local/BerkeleyDB.4.7/lib to the list.  Also, you will need to
983 add appropriate linker flags to tell the runtime linker where to find the
984 BerkeleyDB shared libraries.
985
986 It is possible to specify this from the command line (all on one
987 line):
988
989     sh Configure -de \
990         -Dlocincpth='/usr/local/BerkeleyDB.4.7/include /usr/local/include' \
991         -Dloclibpth='/usr/local/BerkeleyDB.4.7/lib /usr/local/lib' \
992         -Aldflags='-R/usr/local/BerkeleyDB.4.7/lib'
993
994 locincpth is a space-separated list of include directories to search.
995 Configure will automatically add the appropriate -I directives.
996
997 loclibpth is a space-separated list of library directories to search.
998 Configure will automatically add the appropriate -L directives.
999
1000 The addition to ldflags is so that the dynamic linker knows where to find
1001 the BerkeleyDB libraries.  For Linux and Solaris, the -R option does that.
1002 Other systems may use different flags.  Use the appropriate flag for your
1003 system.
1004
1005 =back
1006
1007 =head2 Overriding an old config.sh
1008
1009 If you want to use an old config.sh produced by a previous run of
1010 Configure, but override some of the items with command line options, you
1011 need to use B<Configure -O>.
1012
1013 =head2 GNU-style configure
1014
1015 If you prefer the GNU-style configure command line interface, you can
1016 use the supplied configure.gnu command, e.g.
1017
1018         CC=gcc ./configure.gnu
1019
1020 The configure.gnu script emulates a few of the more common configure
1021 options.  Try
1022
1023         ./configure.gnu --help
1024
1025 for a listing.
1026
1027 (The file is called configure.gnu to avoid problems on systems
1028 that would not distinguish the files "Configure" and "configure".)
1029
1030 =head2 Malloc Issues
1031
1032 Perl relies heavily on malloc(3) to grow data structures as needed,
1033 so perl's performance can be noticeably affected by the performance of
1034 the malloc function on your system.  The perl source is shipped with a
1035 version of malloc that has been optimized for the typical requests from
1036 perl, so there's a chance that it may be both faster and use less memory
1037 than your system malloc.
1038
1039 However, if your system already has an excellent malloc, or if you are
1040 experiencing difficulties with extensions that use third-party libraries
1041 that call malloc, then you should probably use your system's malloc.
1042 (Or, you might wish to explore the malloc flags discussed below.)
1043
1044 =over 4
1045
1046 =item Using the system malloc
1047
1048 To build without perl's malloc, you can use the Configure command
1049
1050         sh Configure -Uusemymalloc
1051
1052 or you can answer 'n' at the appropriate interactive Configure prompt.
1053
1054 Note that Perl's malloc isn't always used by default; that actually
1055 depends on your system. For example, on Linux and FreeBSD (and many more
1056 systems), Configure chooses to use the system's malloc by default.
1057 See the appropriate file in the F<hints/> directory to see how the
1058 default is set.
1059
1060 =item -DPERL_POLLUTE_MALLOC
1061
1062 NOTE: This flag is enabled automatically on some platforms if you just
1063 run Configure to accept all the defaults.
1064
1065 Perl's malloc family of functions are normally called Perl_malloc(),
1066 Perl_realloc(), Perl_calloc() and Perl_mfree().
1067 These names do not clash with the system versions of these functions.
1068
1069 If this flag is enabled, however, Perl's malloc family of functions
1070 will have the same names as the system versions.  This may be required
1071 sometimes if you have libraries that like to free() data that may have
1072 been allocated by Perl_malloc() and vice versa.
1073
1074 Note that enabling this option may sometimes lead to duplicate symbols
1075 from the linker for malloc et al.  In such cases, the system probably
1076 does not allow its malloc functions to be fully replaced with custom
1077 versions.
1078
1079 =item -DPERL_DEBUGGING_MSTATS
1080
1081 This flag enables debugging mstats, which is required to use the
1082 Devel::Peek::mstat() function. You cannot enable this unless you are
1083 using Perl's malloc, so a typical Configure command would be
1084
1085        sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc
1086
1087 to enable this option.
1088
1089 =back
1090
1091 =head2 What if it doesn't work?
1092
1093 If you run into problems, try some of the following ideas.
1094 If none of them help, then see L<"Reporting Problems"> below.
1095
1096 =over 4
1097
1098 =item Running Configure Interactively
1099
1100 If Configure runs into trouble, remember that you can always run
1101 Configure interactively so that you can check (and correct) its
1102 guesses.
1103
1104 All the installation questions have been moved to the top, so you don't
1105 have to wait for them.  Once you've handled them (and your C compiler and
1106 flags) you can type  &-d  at the next Configure prompt and Configure
1107 will use the defaults from then on.
1108
1109 If you find yourself trying obscure command line incantations and
1110 config.over tricks, I recommend you run Configure interactively
1111 instead.  You'll probably save yourself time in the long run.
1112
1113 =item Hint files
1114
1115 Hint files tell Configure about a number of things:
1116
1117 =over 4
1118
1119 =item o
1120
1121 The peculiarities or conventions of particular platforms -- non-standard
1122 library locations and names, default installation locations for binaries,
1123 and so on.
1124
1125 =item o
1126
1127 The deficiencies of the platform -- for example, library functions that,
1128 although present, are too badly broken to be usable; or limits on
1129 resources that are generously available on most platforms.
1130
1131 =item o
1132
1133 How best to optimize for the platform, both in terms of binary size and/or
1134 speed, and for Perl feature support. Because of wide variations in the
1135 implementation of shared libraries and of threading, for example, Configure
1136 often needs hints in order to be able to use these features.
1137
1138 =back
1139
1140 The perl distribution includes many system-specific hints files
1141 in the hints/ directory. If one of them matches your system, Configure
1142 will offer to use that hint file. Unless you have a very good reason
1143 not to, you should accept its offer.
1144
1145 Several of the hint files contain additional important information.
1146 If you have any problems, it is a good idea to read the relevant hint file
1147 for further information.  See hints/solaris_2.sh for an extensive example.
1148 More information about writing good hints is in the hints/README.hints
1149 file, which also explains hint files known as callback-units.
1150
1151 Note that any hint file is read before any Policy file, meaning that
1152 Policy overrides hints -- see L</Site-wide Policy settings>.
1153
1154 =item WHOA THERE!!!
1155
1156 If you are re-using an old config.sh, it's possible that Configure detects
1157 different values from the ones specified in this file.  You will almost
1158 always want to keep the previous value, unless you have changed something
1159 on your system.
1160
1161 For example, suppose you have added libgdbm.a to your system
1162 and you decide to reconfigure perl to use GDBM_File.  When you run
1163 Configure again, you will need to add -lgdbm to the list of libraries.
1164 Now, Configure will find your gdbm include file and library and will
1165 issue a message:
1166
1167     *** WHOA THERE!!! ***
1168         The previous value for $i_gdbm on this machine was "undef"!
1169         Keep the previous value? [y]
1170
1171 In this case, you do not want to keep the previous value, so you
1172 should answer 'n'.  (You'll also have to manually add GDBM_File to
1173 the list of dynamic extensions to build.)
1174
1175 =item Changing Compilers
1176
1177 If you change compilers or make other significant changes, you should
1178 probably not re-use your old config.sh.  Simply remove it or
1179 rename it, then rerun Configure with the options you want to use.
1180
1181 =item Propagating your changes to config.sh
1182
1183 If you make any changes to config.sh, you should propagate
1184 them to all the .SH files by running
1185
1186         sh Configure -S
1187
1188 You will then have to rebuild by running
1189
1190         make depend
1191         make
1192
1193 =item config.over and config.arch
1194
1195 You can also supply a shell script config.over to over-ride
1196 Configure's guesses.  It will get loaded up at the very end, just
1197 before config.sh is created.  You have to be careful with this,
1198 however, as Configure does no checking that your changes make sense.
1199 This file is usually good for site-specific customizations.
1200
1201 There is also another file that, if it exists, is loaded before the
1202 config.over, called config.arch.  This file is intended to be per
1203 architecture, not per site, and usually it's the architecture-specific
1204 hints file that creates the config.arch.
1205
1206 =item config.h
1207
1208 Many of the system dependencies are contained in config.h.
1209 Configure builds config.h by running the config_h.SH script.
1210 The values for the variables are taken from config.sh.
1211
1212 If there are any problems, you can edit config.h directly.  Beware,
1213 though, that the next time you run Configure, your changes will be
1214 lost.
1215
1216 =item cflags
1217
1218 If you have any additional changes to make to the C compiler command
1219 line, they can be made in cflags.SH.  For instance, to turn off the
1220 optimizer on toke.c, find the line in the switch structure for
1221 toke.c and put the command optimize='-g' before the ;; .  You
1222 can also edit cflags directly, but beware that your changes will be
1223 lost the next time you run Configure.
1224
1225 To explore various ways of changing ccflags from within a hint file,
1226 see the file hints/README.hints.
1227
1228 To change the C flags for all the files, edit config.sh and change either
1229 $ccflags or $optimize, and then re-run
1230
1231         sh Configure -S
1232         make depend
1233
1234 =item No sh
1235
1236 If you don't have sh, you'll have to copy the sample file
1237 Porting/config.sh to config.sh and edit your config.sh to reflect your
1238 system's peculiarities.  See Porting/pumpkin.pod for more information.
1239 You'll probably also have to extensively modify the extension building
1240 mechanism.
1241
1242 =item Porting information
1243
1244 Specific information for the OS/2, Plan 9, VMS and Win32 ports is in the
1245 corresponding README files and subdirectories.  Additional information,
1246 including a glossary of all those config.sh variables, is in the Porting
1247 subdirectory.  Porting/Glossary should especially come in handy.
1248
1249 Ports for other systems may also be available.  You should check out
1250 http://www.cpan.org/ports for current information on ports to
1251 various other operating systems.
1252
1253 If you plan to port Perl to a new architecture, study carefully the
1254 section titled "Philosophical Issues in Patching and Porting Perl"
1255 in the file Porting/pumpkin.pod and the file Porting/patching.pod.
1256 Study also how other non-UNIX ports have solved problems.
1257
1258 =back
1259
1260 =head2 Adding extra modules to the build
1261
1262 You can specify extra modules or module bundles to be fetched from the
1263 CPAN and installed as part of the Perl build.  Either use the -Dextras=...
1264 command line parameter to Configure, for example like this:
1265
1266         Configure -Dextras="Bundle::LWP DBI"
1267
1268 or answer first 'y' to the question 'Install any extra modules?' and
1269 then answer "Bundle::LWP DBI" to the 'Extras?' question.
1270 The module or the bundle names are as for the CPAN module 'install' command.
1271 This will only work if those modules are to be built as dynamic
1272 extensions.  If you wish to include those extra modules as static
1273 extensions, see L<"Extensions"> above.
1274
1275 Notice that because the CPAN module will be used to fetch the extra
1276 modules, you will need access to the CPAN, either via the Internet,
1277 or via a local copy such as a CD-ROM or a local CPAN mirror.  If you
1278 do not, using the extra modules option will die horribly.
1279
1280 Also notice that you yourself are responsible for satisfying any extra
1281 dependencies such as external headers or libraries BEFORE trying the build.
1282 For example: you will need to have the Foo database specific
1283 headers and libraries installed for the DBD::Foo module.  The Configure
1284 process or the Perl build process will not help you with these.
1285
1286 =head2 suidperl
1287
1288 suidperl is an optional component, which is normally neither built
1289 nor installed by default.  From perlfaq1:
1290
1291         On some systems, setuid and setgid scripts (scripts written
1292         in the C shell, Bourne shell, or Perl, for example, with the
1293         set user or group ID permissions enabled) are insecure due to
1294         a race condition in the kernel. For those systems, Perl versions
1295         5 and 4 attempt to work around this vulnerability with an optional
1296         component, a special program named suidperl, also known as sperl.
1297         This program attempts to emulate the set-user-ID and set-group-ID
1298         features of the kernel.
1299
1300 Because of the buggy history of suidperl, and the difficulty
1301 of properly security auditing as large and complex piece of
1302 software as Perl, we cannot recommend using suidperl and the feature
1303 should be considered deprecated.
1304
1305 Instead, use a tool specifically designed to handle changes in
1306 privileges, such as B<sudo>.
1307
1308 =head1 make depend
1309
1310 This will look for all the includes.  The output is stored in makefile.
1311 The only difference between Makefile and makefile is the dependencies at
1312 the bottom of makefile.  If you have to make any changes, you should edit
1313 makefile, not Makefile, since the Unix make command reads makefile first.
1314 (On non-Unix systems, the output may be stored in a different file.
1315 Check the value of $firstmakefile in your config.sh if in doubt.)
1316
1317 Configure will offer to do this step for you, so it isn't listed
1318 explicitly above.
1319
1320 =head1 make
1321
1322 This will attempt to make perl in the current directory.
1323
1324 =head2 Expected errors
1325
1326 These error reports are normal, and can be ignored:
1327
1328   ...
1329   make: [extra.pods] Error 1 (ignored)
1330   ...
1331   make: [extras.make] Error 1 (ignored)
1332
1333 =head2 What if it doesn't work?
1334
1335 If you can't compile successfully, try some of the following ideas.
1336 If none of them help, and careful reading of the error message and
1337 the relevant manual pages on your system doesn't help,
1338 then see L<"Reporting Problems"> below.
1339
1340 =over 4
1341
1342 =item hints
1343
1344 If you used a hint file, try reading the comments in the hint file
1345 for further tips and information.
1346
1347 =item extensions
1348
1349 If you can successfully build miniperl, but the process crashes
1350 during the building of extensions, run
1351
1352         make minitest
1353
1354 to test your version of miniperl.
1355
1356 =item locale
1357
1358 If you have any locale-related environment variables set, try unsetting
1359 them.  I have some reports that some versions of IRIX hang while
1360 running B<./miniperl configpm> with locales other than the C locale.
1361 See the discussion under L<"make test"> below about locales and the
1362 whole L<perllocale/"LOCALE PROBLEMS"> section in the file pod/perllocale.pod.
1363 The latter is especially useful if you see something like this
1364
1365         perl: warning: Setting locale failed.
1366         perl: warning: Please check that your locale settings:
1367                 LC_ALL = "En_US",
1368                 LANG = (unset)
1369             are supported and installed on your system.
1370         perl: warning: Falling back to the standard locale ("C").
1371
1372 at Perl startup.
1373
1374 =item varargs
1375
1376 If you get varargs problems with gcc, be sure that gcc is installed
1377 correctly and that you are not passing -I/usr/include to gcc.  When using
1378 gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1379 in config.sh.  The problem is usually solved by installing gcc
1380 correctly.  If you do change config.sh, don't forget to propagate
1381 your changes (see L<"Propagating your changes to config.sh"> below).
1382 See also the L<"vsprintf"> item below.
1383
1384 =item util.c
1385
1386 If you get error messages such as the following (the exact line
1387 numbers and function name may vary in different versions of perl):
1388
1389     util.c: In function `Perl_form':
1390     util.c:1107: number of arguments doesn't match prototype
1391     proto.h:125: prototype declaration
1392
1393 it might well be a symptom of the gcc "varargs problem".  See the
1394 previous L<"varargs"> item.
1395
1396 =item LD_LIBRARY_PATH
1397
1398 If you run into dynamic loading problems, check your setting of
1399 the LD_LIBRARY_PATH environment variable.  If you're creating a static
1400 Perl library (libperl.a rather than libperl.so) it should build
1401 fine with LD_LIBRARY_PATH unset, though that may depend on details
1402 of your local set-up.
1403
1404 =item nm extraction
1405
1406 If Configure seems to be having trouble finding library functions,
1407 try not using nm extraction.  You can do this from the command line
1408 with
1409
1410         sh Configure -Uusenm
1411
1412 or by answering the nm extraction question interactively.
1413 If you have previously run Configure, you should not reuse your old
1414 config.sh.
1415
1416 =item umask not found
1417
1418 If the build processes encounters errors relating to umask(), the problem
1419 is probably that Configure couldn't find your umask() system call.
1420 Check your config.sh.  You should have d_umask='define'.  If you don't,
1421 this is probably the L<"nm extraction"> problem discussed above.  Also,
1422 try reading the hints file for your system for further information.
1423
1424 =item vsprintf
1425
1426 If you run into problems with vsprintf in compiling util.c, the
1427 problem is probably that Configure failed to detect your system's
1428 version of vsprintf().  Check whether your system has vprintf().
1429 (Virtually all modern Unix systems do.)  Then, check the variable
1430 d_vprintf in config.sh.  If your system has vprintf, it should be:
1431
1432         d_vprintf='define'
1433
1434 If Configure guessed wrong, it is likely that Configure guessed wrong
1435 on a number of other common functions too.  This is probably
1436 the L<"nm extraction"> problem discussed above.
1437
1438 =item do_aspawn
1439
1440 If you run into problems relating to do_aspawn or do_spawn, the
1441 problem is probably that Configure failed to detect your system's
1442 fork() function.  Follow the procedure in the previous item
1443 on L<"nm extraction">.
1444
1445 =item __inet_* errors
1446
1447 If you receive unresolved symbol errors during Perl build and/or test
1448 referring to __inet_* symbols, check to see whether BIND 8.1 is
1449 installed.  It installs a /usr/local/include/arpa/inet.h that refers to
1450 these symbols.  Versions of BIND later than 8.1 do not install inet.h
1451 in that location and avoid the errors.  You should probably update to a
1452 newer version of BIND (and remove the files the old one left behind).
1453 If you can't, you can either link with the updated resolver library provided
1454 with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the Perl build and
1455 test process to avoid the problem.
1456
1457 =item .*_r() prototype NOT found
1458
1459 On a related note, if you see a bunch of complaints like the above about
1460 reentrant functions - specifically networking-related ones - being present
1461 but without prototypes available, check to see if BIND 8.1 (or possibly
1462 other BIND 8 versions) is (or has been) installed. They install
1463 header files such as netdb.h into places such as /usr/local/include (or into
1464 another directory as specified at build/install time), at least optionally.
1465 Remove them or put them in someplace that isn't in the C preprocessor's
1466 header file include search path (determined by -I options plus defaults,
1467 normally /usr/include).
1468
1469 =item #error "No DATAMODEL_NATIVE specified"
1470
1471 This is a common error when trying to build perl on Solaris 2.6 with a
1472 gcc installation from Solaris 2.5 or 2.5.1.  The Solaris header files
1473 changed, so you need to update your gcc installation.  You can either
1474 rerun the fixincludes script from gcc or take the opportunity to
1475 update your gcc installation.
1476
1477 =item Optimizer
1478
1479 If you can't compile successfully, try turning off your compiler's
1480 optimizer.  Edit config.sh and change the line
1481
1482         optimize='-O'
1483
1484 to
1485
1486         optimize=' '
1487
1488 then propagate your changes with B<sh Configure -S> and rebuild
1489 with B<make depend; make>.
1490
1491 =item Missing functions and Undefined symbols
1492
1493 If the build of miniperl fails with a long list of missing functions or
1494 undefined symbols, check the libs variable in the config.sh file.  It
1495 should look something like
1496
1497         libs='-lsocket -lnsl -ldl -lm -lc'
1498
1499 The exact libraries will vary from system to system, but you typically
1500 need to include at least the math library -lm.  Normally, Configure
1501 will suggest the correct defaults.  If the libs variable is empty, you
1502 need to start all over again.  Run
1503
1504         make distclean
1505
1506 and start from the very beginning.  This time, unless you are sure of
1507 what you are doing, accept the default list of libraries suggested by
1508 Configure.
1509
1510 If the libs variable looks correct, you might have the
1511 L<"nm extraction"> problem discussed above.
1512
1513 If you stil have missing routines or undefined symbols, you probably
1514 need to add some library or other, or you need to undefine some feature
1515 that Configure thought was there but is defective or incomplete.  If
1516 you used a hint file, see if it has any relevant advice.  You can also
1517 look through through config.h for likely suspects.
1518
1519 =item toke.c
1520
1521 Some compilers will not compile or optimize the larger files (such as
1522 toke.c) without some extra switches to use larger jump offsets or
1523 allocate larger internal tables.  You can customize the switches for
1524 each file in cflags.  It's okay to insert rules for specific files into
1525 makefile since a default rule only takes effect in the absence of a
1526 specific rule.
1527
1528 =item Missing dbmclose
1529
1530 SCO prior to 3.2.4 may be missing dbmclose().  An upgrade to 3.2.4
1531 that includes libdbm.nfs (which includes dbmclose()) may be available.
1532
1533 =item Note (probably harmless): No library found for -lsomething
1534
1535 If you see such a message during the building of an extension, but
1536 the extension passes its tests anyway (see L<"make test"> below),
1537 then don't worry about the warning message.  The extension
1538 Makefile.PL goes looking for various libraries needed on various
1539 systems; few systems will need all the possible libraries listed.
1540 Most users will see warnings for the ones they don't have.  The
1541 phrase 'probably harmless' is intended to reassure you that nothing
1542 unusual is happening, and the build process is continuing.
1543
1544 On the other hand, if you are building GDBM_File and you get the
1545 message
1546
1547     Note (probably harmless): No library found for -lgdbm
1548
1549 then it's likely you're going to run into trouble somewhere along
1550 the line, since it's hard to see how you can use the GDBM_File
1551 extension without the -lgdbm library.
1552
1553 It is true that, in principle, Configure could have figured all of
1554 this out, but Configure and the extension building process are not
1555 quite that tightly coordinated.
1556
1557 =item sh: ar: not found
1558
1559 This is a message from your shell telling you that the command 'ar'
1560 was not found.  You need to check your PATH environment variable to
1561 make sure that it includes the directory with the 'ar' command.  This
1562 is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
1563 directory.
1564
1565 =item db-recno failure on tests 51, 53 and 55
1566
1567 Old versions of the DB library (including the DB library which comes
1568 with FreeBSD 2.1) had broken handling of recno databases with modified
1569 bval settings.  Upgrade your DB library or OS.
1570
1571 =item Bad arg length for semctl, is XX, should be ZZZ
1572
1573 If you get this error message from the ext/IPC/SysV/t/sem test, your System
1574 V IPC may be broken.  The XX typically is 20, and that is what ZZZ
1575 also should be.  Consider upgrading your OS, or reconfiguring your OS
1576 to include the System V semaphores.
1577
1578 =item ext/IPC/SysV/t/sem........semget: No space left on device
1579
1580 Either your account or the whole system has run out of semaphores.  Or
1581 both.  Either list the semaphores with "ipcs" and remove the unneeded
1582 ones (which ones these are depends on your system and applications)
1583 with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1584 system.
1585
1586 =item GNU binutils
1587
1588 If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1589 tools you may be in for some trouble.  For example creating archives
1590 with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1591 may lead into linking problems.  Either recompile your GNU binutils
1592 under your current operating system release, or modify your PATH not
1593 to include the GNU utils before running Configure, or specify the
1594 vendor-supplied utilities explicitly to Configure, for example by
1595 Configure -Dar=/bin/ar.
1596
1597 =item THIS PACKAGE SEEMS TO BE INCOMPLETE
1598
1599 The F<Configure> program has not been able to find all the files which
1600 make up the complete Perl distribution.  You may have a damaged source
1601 archive file (in which case you may also have seen messages such as
1602 C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1603 archive file>), or you may have obtained a structurally-sound but
1604 incomplete archive.  In either case, try downloading again from the
1605 official site named at the start of this document.  If you do find
1606 that any site is carrying a corrupted or incomplete source code
1607 archive, please report it to the site's maintainer.
1608
1609 =item invalid token: ##
1610
1611 You are using a non-ANSI-compliant C compiler.  To compile Perl, you
1612 need to use a compiler that supports ANSI C.  If there is a README
1613 file for your system, it may have further details on your compiler
1614 options.
1615
1616 =item Miscellaneous
1617
1618 Some additional things that have been reported:
1619
1620 Genix may need to use libc rather than libc_s, or #undef VARARGS.
1621
1622 NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1623
1624 UTS may need one or more of -K or -g, and undef LSTAT.
1625
1626 FreeBSD can fail the ext/IPC/SysV/t/sem.t test if SysV IPC has not been
1627 configured in the kernel.  Perl tries to detect this, though, and
1628 you will get a message telling you what to do.
1629
1630 Building Perl on a system that has also BIND (headers and libraries)
1631 installed may run into troubles because BIND installs its own netdb.h
1632 and socket.h, which may not agree with the operating system's ideas of
1633 the same files.  Similarly, including -lbind may conflict with libc's
1634 view of the world.  You may have to tweak -Dlocincpth and -Dloclibpth
1635 to avoid the BIND.
1636
1637 =back
1638
1639 =head2 Cross-compilation
1640
1641 Perl can be cross-compiled.  It is just not trivial, cross-compilation
1642 rarely is.  Perl is routinely cross-compiled for many platforms (as of
1643 June 2005 at least PocketPC aka WinCE, Open Zaurus, EPOC, Symbian, and
1644 the IBM OS/400).  These platforms are known as the B<target> platforms,
1645 while the systems where the compilation takes place are the B<host>
1646 platforms.
1647
1648 What makes the situation difficult is that first of all,
1649 cross-compilation environments vary significantly in how they are set
1650 up and used, and secondly because the primary way of configuring Perl
1651 (using the rather large Unix-tool-dependent Configure script) is not
1652 awfully well suited for cross-compilation.  However, starting from
1653 version 5.8.0, the Configure script also knows one way of supporting
1654 cross-compilation support, please keep reading.
1655
1656 See the following files for more information about compiling Perl for
1657 the particular platforms:
1658
1659 =over 4
1660
1661 =item WinCE/PocketPC
1662
1663 README.ce
1664
1665 =item Open Zaurus
1666
1667 Cross/README
1668
1669 =item EPOC
1670
1671 README.epoc
1672
1673 =item Symbian
1674
1675 README.symbian
1676
1677 =item OS/400
1678
1679 README.os400
1680
1681 =back
1682
1683 Packaging and transferring either the core Perl modules or CPAN
1684 modules to the target platform is also left up to the each
1685 cross-compilation environment.  Often the cross-compilation target
1686 platforms are somewhat limited in diskspace: see the section
1687 L<Minimizing the Perl installation> to learn more of the minimal set
1688 of files required for a functional Perl installation.
1689
1690 For some cross-compilation environments the Configure option
1691 C<-Dinstallprefix=...> might be handy, see L<Changing the installation
1692 directory>.
1693
1694 About the cross-compilation support of Configure: what is known to
1695 work is running Configure in a cross-compilation environment and
1696 building the miniperl executable.  What is known not to work is
1697 building the perl executable because that would require building
1698 extensions: Dynaloader statically and File::Glob dynamically, for
1699 extensions one needs MakeMaker and MakeMaker is not yet
1700 cross-compilation aware, and neither is the main Makefile.
1701
1702 The cross-compilation setup of Configure has successfully been used in
1703 at least two Linux cross-compilation environments.  The setups were
1704 both such that the host system was Intel Linux with a gcc built for
1705 cross-compiling into ARM Linux, and there was a SSH connection to the
1706 target system.
1707
1708 To run Configure in cross-compilation mode the basic switch that
1709 has to be used is C<-Dusecrosscompile>.
1710
1711    sh ./Configure -des -Dusecrosscompile -D...
1712
1713 This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1714 symbol C<usecrosscompile> available, and C<xconfig.h> will be used
1715 for cross-compilation.
1716
1717 During the Configure and build, certain helper scripts will be created
1718 into the Cross/ subdirectory.  The scripts are used to execute a
1719 cross-compiled executable, and to transfer files to and from the
1720 target host.  The execution scripts are named F<run-*> and the
1721 transfer scripts F<to-*> and F<from-*>.  The part after the dash is
1722 the method to use for remote execution and transfer: by default the
1723 methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1724 F<to-scp>, and F<from-scp>.
1725
1726 To configure the scripts for a target host and a directory (in which
1727 the execution will happen and which is to and from where the transfer
1728 happens), supply Configure with
1729
1730     -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1731
1732 The targethost is what e.g. ssh will use as the hostname, the targetdir
1733 must exist (the scripts won't create it), the targetdir defaults to /tmp.
1734 You can also specify a username to use for ssh/rsh logins
1735
1736     -Dtargetuser=luser
1737
1738 but in case you don't, "root" will be used.
1739
1740 Because this is a cross-compilation effort, you will also need to specify
1741 which target environment and which compilation environment to use.
1742 This includes the compiler, the header files, and the libraries.
1743 In the below we use the usual settings for the iPAQ cross-compilation
1744 environment:
1745
1746     -Dtargetarch=arm-linux
1747     -Dcc=arm-linux-gcc
1748     -Dusrinc=/skiff/local/arm-linux/include
1749     -Dincpth=/skiff/local/arm-linux/include
1750     -Dlibpth=/skiff/local/arm-linux/lib
1751
1752 If the name of the C<cc> has the usual GNU C semantics for cross
1753 compilers, that is, CPU-OS-gcc, the names of the C<ar>, C<nm>, and
1754 C<ranlib> will also be automatically chosen to be CPU-OS-ar and so on.
1755 (The C<ld> requires more thought and will be chosen later by Configure
1756 as appropriate.)  Also, in this case the incpth, libpth, and usrinc
1757 will be guessed by Configure (unless explicitly set to something else,
1758 in which case Configure's guesses with be appended).
1759
1760 In addition to the default execution/transfer methods you can also
1761 choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
1762 for example:
1763
1764     -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
1765
1766 Putting it all together:
1767
1768     sh ./Configure -des -Dusecrosscompile \
1769         -Dtargethost=so.me.ho.st \
1770         -Dtargetdir=/tar/get/dir \
1771         -Dtargetuser=root \
1772         -Dtargetarch=arm-linux \
1773         -Dcc=arm-linux-gcc \
1774         -Dusrinc=/skiff/local/arm-linux/include \
1775         -Dincpth=/skiff/local/arm-linux/include \
1776         -Dlibpth=/skiff/local/arm-linux/lib \
1777         -D...
1778
1779 or if you are happy with the defaults:
1780
1781     sh ./Configure -des -Dusecrosscompile \
1782         -Dtargethost=so.me.ho.st \
1783         -Dcc=arm-linux-gcc \
1784         -D...
1785
1786 Another example where the cross-compiler has been installed under
1787 F</usr/local/arm/2.95.5>:
1788
1789     sh ./Configure -des -Dusecrosscompile \
1790         -Dtargethost=so.me.ho.st \
1791         -Dcc=/usr/local/arm/2.95.5/bin/arm-linux-gcc \
1792         -Dincpth=/usr/local/arm/2.95.5/include \
1793         -Dusrinc=/usr/local/arm/2.95.5/include \
1794         -Dlibpth=/usr/local/arm/2.95.5/lib
1795
1796 =head1 make test
1797
1798 This will run the regression tests on the perl you just made.  If
1799 'make test' doesn't say "All tests successful" then something went
1800 wrong.  See the file t/README in the t subdirectory.
1801
1802 Note that you can't run the tests in background if this disables
1803 opening of /dev/tty. You can use 'make test-notty' in that case but
1804 a few tty tests will be skipped.
1805
1806 =head2 What if make test doesn't work?
1807
1808 If make test bombs out, just cd to the t directory and run ./TEST
1809 by hand to see if it makes any difference.  If individual tests
1810 bomb, you can run them by hand, e.g.,
1811
1812         cd t ; ./perl -MTestInit op/groups.t
1813
1814 Another way to get more detailed information about failed tests and
1815 individual subtests is to cd to the t directory and run
1816
1817         cd t ; ./perl harness <list of tests>
1818
1819 (this assumes that most basic tests succeed, since harness uses
1820 complicated constructs). If no list of tests is provided, harness
1821 will run all tests.
1822
1823 You should also read the individual tests to see if there are any helpful
1824 comments that apply to your system.  You may also need to setup your
1825 shared library path if you get errors like:
1826
1827         /sbin/loader: Fatal Error: cannot map libperl.so
1828
1829 See L</"Building a shared Perl library"> earlier in this document.
1830
1831 =over 4
1832
1833 =item locale
1834
1835 Note:  One possible reason for errors is that some external programs
1836 may be broken due to the combination of your environment and the way
1837 'make test' exercises them.  For example, this may happen if you have
1838 one or more of these environment variables set:  LC_ALL LC_CTYPE
1839 LC_COLLATE LANG.  In some versions of UNIX, the non-English locales
1840 are known to cause programs to exhibit mysterious errors.
1841
1842 If you have any of the above environment variables set, please try
1843
1844         setenv LC_ALL C
1845
1846 (for C shell) or
1847
1848         LC_ALL=C;export LC_ALL
1849
1850 for Bourne or Korn shell) from the command line and then retry
1851 make test.  If the tests then succeed, you may have a broken program that
1852 is confusing the testing.  Please run the troublesome test by hand as
1853 shown above and see whether you can locate the program.  Look for
1854 things like:  exec, `backquoted command`, system, open("|...") or
1855 open("...|").  All these mean that Perl is trying to run some
1856 external program.
1857
1858 =item Timing problems
1859
1860 Several tests in the test suite check timing functions, such as
1861 sleep(), and see if they return in a reasonable amount of time.
1862 If your system is quite busy and doesn't respond quickly enough,
1863 these tests might fail.  If possible, try running the tests again
1864 with the system under a lighter load.  These timing-sensitive
1865 and load-sensitive tests include F<t/op/alarm.t>,
1866 F<ext/Time-HiRes/t/HiRes.t>, F<ext/threads-shared/t/waithires.t>,
1867 F<ext/threads-shared/t/stress.t>, F<lib/Benchmark.t>,
1868 F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
1869
1870 You might also experience some failures in F<t/op/stat.t> if you build
1871 perl on an NFS filesystem, if the remote clock and the system clock are
1872 different.
1873
1874 =item Out of memory
1875
1876 On some systems, particularly those with smaller amounts of RAM, some
1877 of the tests in t/op/pat.t may fail with an "Out of memory" message.
1878 For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
1879 test 85 will fail if run under either t/TEST or t/harness.
1880
1881 Try stopping other jobs on the system and then running the test by itself:
1882
1883         cd t; ./perl -MTestInit op/pat.t
1884
1885 to see if you have any better luck.  If your perl still fails this
1886 test, it does not necessarily mean you have a broken perl.  This test
1887 tries to exercise the regular expression subsystem quite thoroughly,
1888 and may well be far more demanding than your normal usage.
1889
1890 =item libgcc_s.so.1: cannot open shared object file
1891
1892 This message has been reported on gcc-3.2.3 and earlier installed with
1893 a non-standard prefix.  Setting the LD_LIBRARY_PATH environment variable
1894 (or equivalent) to include gcc's lib/ directory with the libgcc_s.so.1
1895 shared library should fix the problem.
1896
1897 =item Failures from lib/File/Temp/t/security saying "system possibly insecure"
1898
1899 First, such warnings are not necessarily serious or indicative of a
1900 real security threat.  That being said, they bear investigating.
1901
1902 Note that each of the tests is run twice.  The first time is in the
1903 directory returned by File::Spec->tmpdir() (often /tmp on Unix
1904 systems), and the second time in the directory from which the test was
1905 run (usually the 't' directory, if the test was run as part of 'make
1906 test').
1907
1908 The tests may fail for the following reasons:
1909
1910 (1) If the directory the tests are being run in is owned by somebody
1911 other than the user running the tests, or by root (uid 0).
1912
1913 This failure can happen if the Perl source code distribution is
1914 unpacked in such a way that the user ids in the distribution package
1915 are used as-is.  Some tar programs do this.
1916
1917 (2) If the directory the tests are being run in is writable by group or
1918 by others, and there is no sticky bit set for the directory.  (With
1919 UNIX/POSIX semantics, write access to a directory means the right to
1920 add or remove files in that directory.  The 'sticky bit' is a feature
1921 used in some UNIXes to give extra protection to files: if the bit is
1922 set for a directory, no one but the owner (or root) can remove that
1923 file even if the permissions would otherwise allow file removal by
1924 others.)
1925
1926 This failure may or may not be a real problem: it depends on the
1927 permissions policy used on this particular system.  This failure can
1928 also happen if the system either doesn't support the sticky bit (this
1929 is the case with many non-UNIX platforms: in principle File::Temp
1930 should know about these platforms and skip the tests), or if the system
1931 supports the sticky bit but for some reason or reasons it is not being
1932 used.  This is, for example, the case with HP-UX: as of HP-UX release
1933 11.00, the sticky bit is very much supported, but HP-UX doesn't use it
1934 on its /tmp directory as shipped.  Also, as with the permissions, some
1935 local policy might dictate that the stickiness is not used.
1936
1937 (3) If the system supports the POSIX 'chown giveaway' feature and if
1938 any of the parent directories of the temporary file back to the root
1939 directory are 'unsafe', using the definitions given above in (1) and
1940 (2).  For Unix systems, this is usually not an issue if you are
1941 building on a local disk.  See the documentation for the File::Temp
1942 module for more information about 'chown giveaway'.
1943
1944 See the documentation for the File::Temp module for more information
1945 about the various security aspects of temporary files.
1946
1947 =back
1948
1949 The core distribution can now run its regression tests in parallel on
1950 Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> in
1951 your environment to the number of tests to run in parallel, and run
1952 C<make test_harness>. On a Bourne-like shell, this can be done as
1953
1954     TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
1955
1956 An environment variable is used, rather than parallel make itself, because
1957 L<TAP::Harness> needs to be able to schedule individual non-conflicting test
1958 scripts itself, and there is no standard interface to C<make> utilities to
1959 interact with their job schedulers.
1960
1961 =head1 make install
1962
1963 This will put perl into the public directory you specified to
1964 Configure; by default this is /usr/local/bin.  It will also try
1965 to put the man pages in a reasonable place.  It will not nroff the man
1966 pages, however.  You may need to be root to run B<make install>.  If you
1967 are not root, you must still have permission to install into the directories
1968 in question and you should ignore any messages about chown not working.
1969
1970 If "make install" just says "`install' is up to date" or something
1971 similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
1972 and you should say "make install-all".  (This confusion is brought to you
1973 by the Perl distribution having a file called INSTALL.)
1974
1975 =head2 Installing perl under different names
1976
1977 If you want to install perl under a name other than "perl" (for example,
1978 when installing perl with special features enabled, such as debugging),
1979 indicate the alternate name on the "make install" line, such as:
1980
1981     make install PERLNAME=myperl
1982
1983 You can separately change the base used for versioned names (like
1984 "perl5.8.9") by setting PERLNAME_VERBASE, like
1985
1986     make install PERLNAME=perl5 PERLNAME_VERBASE=perl
1987
1988 This can be useful if you have to install perl as "perl5" (e.g. to
1989 avoid conflicts with an ancient version in /usr/bin supplied by your vendor).
1990 Without this the versioned binary would be called "perl55.8.8".
1991
1992 =head2 Installing perl under a different directory
1993
1994 You can install perl under a different destination directory by using
1995 the DESTDIR variable during C<make install>, with a command like
1996
1997         make install DESTDIR=/tmp/perl5
1998
1999 DESTDIR is automatically prepended to all the installation paths.  See
2000 the example in L<"DESTDIR"> above.
2001
2002 =head2 Installed files
2003
2004 If you want to see exactly what will happen without installing
2005 anything, you can run
2006
2007         ./perl installperl -n
2008         ./perl installman -n
2009
2010 make install will install the following:
2011
2012     binaries
2013
2014         perl,
2015             perl5.n.n   where 5.n.n is the current release number.  This
2016                         will be a link to perl.
2017         suidperl,
2018             sperl5.n.n  If you requested setuid emulation.
2019         a2p             awk-to-perl translator
2020
2021     scripts
2022
2023         cppstdin        This is used by the deprecated switch perl -P, if
2024                         your cc -E can't read from stdin.
2025         c2ph, pstruct   Scripts for handling C structures in header files.
2026         config_data     Manage Module::Build-like module configuration
2027         corelist        Shows versions of modules that come with different
2028                         versions of perl
2029         cpan            The CPAN shell
2030         cpan2dist       The CPANPLUS distribution creator
2031         cpanp           The CPANPLUS shell
2032         cpanp-run-perl  An helper for cpanp
2033         dprofpp         Perl code profiler post-processor
2034         enc2xs          Encoding module generator
2035         find2perl       find-to-perl translator
2036         h2ph            Extract constants and simple macros from C headers
2037         h2xs            Converts C .h header files to Perl extensions.
2038         instmodsh       A shell to examine installed modules.
2039         libnetcfg       Configure libnet.
2040         perlbug         Tool to report bugs in Perl.
2041         perldoc         Tool to read perl's pod documentation.
2042         perlivp         Perl Installation Verification Procedure
2043         piconv          A Perl implementation of the encoding conversion
2044                         utility iconv
2045         pl2pm           Convert Perl 4 .pl files to Perl 5 .pm modules
2046         pod2html,       Converters from perl's pod documentation format
2047         pod2latex,      to other useful formats.
2048         pod2man,
2049         pod2text,
2050         pod2usage
2051         podchecker      POD syntax checker
2052         podselect       Prints sections of POD documentation
2053         prove           A command-line tool for running tests
2054         psed            A Perl implementation of sed
2055         ptar            A Perl implementation of tar
2056         ptardiff        A diff for tar archives
2057         s2p             sed-to-perl translator
2058         shasum          A tool to print or check SHA checksums
2059         splain          Describe Perl warnings and errors
2060         xsubpp          Compiler to convert Perl XS code into C code
2061
2062     library files
2063
2064                         in $privlib and $archlib specified to
2065                         Configure, usually under /usr/local/lib/perl5/.
2066
2067     documentation
2068
2069         man pages       in $man1dir, usually /usr/local/man/man1.
2070         module man
2071         pages           in $man3dir, usually /usr/local/man/man3.
2072         pod/*.pod       in $privlib/pod/.
2073
2074 installperl will also create the directories listed above
2075 in L<"Installation Directories">.
2076
2077 Perl's *.h header files and the libperl library are also installed
2078 under $archlib so that any user may later build new modules, run the
2079 optional Perl compiler, or embed the perl interpreter into another
2080 program even if the Perl source is no longer available.
2081
2082 =head2 Installing only version-specific parts
2083
2084 Sometimes you only want to install the version-specific parts of the perl
2085 installation.  For example, you may wish to install a newer version of
2086 perl alongside an already installed production version without
2087 disabling installation of new modules for the production version.
2088 To only install the version-specific parts of the perl installation, run
2089
2090         Configure -Dversiononly
2091
2092 or answer 'y' to the appropriate Configure prompt.  Alternatively,
2093 you can just manually run
2094
2095         ./perl installperl -v
2096
2097 and skip installman altogether.
2098
2099 See also L<"Maintaining completely separate versions"> for another
2100 approach.
2101
2102 =head1 cd /usr/include; h2ph *.h sys/*.h
2103
2104 Some perl scripts need to be able to obtain information from the
2105 system header files.  This command will convert the most commonly used
2106 header files in /usr/include into files that can be easily interpreted
2107 by perl.  These files will be placed in the architecture-dependent
2108 library ($archlib) directory you specified to Configure.
2109
2110 Note:  Due to differences in the C and perl languages, the conversion
2111 of the header files is not perfect.  You will probably have to
2112 hand-edit some of the converted files to get them to parse correctly.
2113 For example, h2ph breaks spectacularly on type casting and certain
2114 structures.
2115
2116 =head1 installhtml --help
2117
2118 Some sites may wish to make perl documentation available in HTML
2119 format.  The installhtml utility can be used to convert pod
2120 documentation into linked HTML files and install them.
2121
2122 Currently, the supplied ./installhtml script does not make use of the
2123 html Configure variables.  This should be fixed in a future release.
2124
2125 The following command-line is an example of one used to convert
2126 perl documentation:
2127
2128   ./installhtml                   \
2129       --podroot=.                 \
2130       --podpath=lib:ext:pod:vms   \
2131       --recurse                   \
2132       --htmldir=/perl/nmanual     \
2133       --htmlroot=/perl/nmanual    \
2134       --splithead=pod/perlipc     \
2135       --splititem=pod/perlfunc    \
2136       --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
2137       --verbose
2138
2139 See the documentation in installhtml for more details.  It can take
2140 many minutes to execute a large installation and you should expect to
2141 see warnings like "no title", "unexpected directive" and "cannot
2142 resolve" as the files are processed. We are aware of these problems
2143 (and would welcome patches for them).
2144
2145 You may find it helpful to run installhtml twice. That should reduce
2146 the number of "cannot resolve" warnings.
2147
2148 =head1 cd pod && make tex && (process the latex files)
2149
2150 Some sites may also wish to make the documentation in the pod/ directory
2151 available in TeX format.  Type
2152
2153         (cd pod && make tex && <process the latex files>)
2154
2155 =head1 Starting all over again
2156
2157 If you wish to re-build perl from the same build directory, you should
2158 clean it out with the command
2159
2160         make distclean
2161
2162 or
2163
2164         make realclean
2165
2166 The only difference between the two is that make distclean also removes
2167 your old config.sh and Policy.sh files.
2168
2169 If you are upgrading from a previous version of perl, or if you
2170 change systems or compilers or make other significant changes, or if
2171 you are experiencing difficulties building perl, you should not re-use
2172 your old config.sh.
2173
2174 If your reason to reuse your old config.sh is to save your particular
2175 installation choices, then you can probably achieve the same effect by
2176 using the Policy.sh file.  See the section on L<"Site-wide Policy
2177 settings"> above.
2178
2179 =head1 Reporting Problems
2180
2181 Wherever possible please use the perlbug tool supplied with this Perl
2182 to report problems, as it automatically includes summary configuration
2183 information about your perl, which may help us track down problems far
2184 more quickly. But first you should read the advice in this file,
2185 carefully re-read the error message and check the relevant manual pages
2186 on your system, as these may help you find an immediate solution.  If
2187 you are not sure whether what you are seeing is a bug, you can send a
2188 message describing the problem to the comp.lang.perl.misc newsgroup to
2189 get advice.
2190
2191 The perlbug tool is installed along with perl, so after you have
2192 completed C<make install> it should be possible to run it with plain
2193 C<perlbug>.  If the install fails, or you want to report problems with
2194 C<make test> without installing perl, then you can use C<make nok> to
2195 run perlbug to report the problem, or run it by hand from this source
2196 directory with C<./perl -Ilib utils/perlbug>
2197
2198 If the build fails too early to run perlbug uninstalled, then please
2199 B<run> the C<./myconfig> shell script, and mail its output along with
2200 an accurate description of your problem to perlbug@perl.org
2201
2202 If Configure itself fails, and does not generate a config.sh file
2203 (needed to run C<./myconfig>), then please mail perlbug@perl.org the
2204 description of how Configure fails along with details of your system
2205 - for example the output from running C<uname -a>
2206
2207 Please try to make your message brief but clear.  Brief, clear bug
2208 reports tend to get answered more quickly.  Please don't worry if your
2209 written English is not great - what matters is how well you describe
2210 the important technical details of the problem you have encountered,
2211 not whether your grammar and spelling is flawless.
2212
2213 Trim out unnecessary information.  Do not include large files (such as
2214 config.sh or a complete Configure or make log) unless absolutely
2215 necessary.  Do not include a complete transcript of your build
2216 session.  Just include the failing commands, the relevant error
2217 messages, and whatever preceding commands are necessary to give the
2218 appropriate context.  Plain text should usually be sufficient--fancy
2219 attachments or encodings may actually reduce the number of people who
2220 read your message.  Your message will get relayed to over 400
2221 subscribers around the world so please try to keep it brief but clear.
2222
2223 If the bug you are reporting has security implications, which make it
2224 inappropriate to send to a publicly archived mailing list, then please send
2225 it to perl5-security-report@perl.org. This points to a closed subscription
2226 unarchived mailing list, which includes all the core committers, who be able
2227 to help assess the impact of issues, figure out a resolution, and help
2228 co-ordinate the release of patches to mitigate or fix the problem across all
2229 platforms on which Perl is supported. Please only use this address for security
2230 issues in the Perl core, not for modules independently distributed on CPAN.
2231
2232 If you are unsure what makes a good bug report please read "How to
2233 report Bugs Effectively" by Simon Tatham:
2234 http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
2235
2236 =head1 Coexistence with earlier versions of perl 5
2237
2238 Perl 5.10 is not binary compatible with earlier versions of Perl.
2239 In other words, you will have to recompile your XS modules.
2240
2241 In general, you can usually safely upgrade from one version of Perl (e.g.
2242 5.X.Y) to another similar minor version (e.g. 5.X.(Y+1))) without
2243 re-compiling all of your extensions.  You can also safely leave the old
2244 version around in case the new version causes you problems for some reason.
2245
2246 Usually, most extensions will probably not need to be recompiled to be
2247 used with a newer version of Perl.  Here is how it is supposed to work.
2248 (These examples assume you accept all the Configure defaults.)
2249
2250 Suppose you already have version 5.8.7 installed.  The directories
2251 searched by 5.8.7 are typically like:
2252
2253         /usr/local/lib/perl5/5.8.7/$archname
2254         /usr/local/lib/perl5/5.8.7
2255         /usr/local/lib/perl5/site_perl/5.8.7/$archname
2256         /usr/local/lib/perl5/site_perl/5.8.7
2257
2258 Now, suppose you install version 5.8.8.  The directories
2259 searched by version 5.8.8 will be:
2260
2261         /usr/local/lib/perl5/5.8.8/$archname
2262         /usr/local/lib/perl5/5.8.8
2263         /usr/local/lib/perl5/site_perl/5.8.8/$archname
2264         /usr/local/lib/perl5/site_perl/5.8.8
2265
2266         /usr/local/lib/perl5/site_perl/5.8.7/$archname
2267         /usr/local/lib/perl5/site_perl/5.8.7
2268         /usr/local/lib/perl5/site_perl/
2269
2270 Notice the last three entries -- Perl understands the default structure
2271 of the $sitelib directories and will look back in older, compatible
2272 directories.  This way, modules installed under 5.8.7 will continue
2273 to be usable by 5.8.7 but will also accessible to 5.8.8.  Further,
2274 suppose that you upgrade a module to one which requires features
2275 present only in 5.8.8.  That new module will get installed into
2276 /usr/local/lib/perl5/site_perl/5.8.8 and will be available to 5.8.8,
2277 but will not interfere with the 5.8.7 version.
2278
2279 The last entry, /usr/local/lib/perl5/site_perl/, is there so that
2280 5.6.0 and above will look for 5.004-era pure perl modules.
2281
2282 Lastly, suppose you now install 5.10.0, which is not binary compatible
2283 with 5.8.x.  The directories searched by 5.10.0 (if you don't change the
2284 Configure defaults) will be:
2285
2286         /usr/local/lib/perl5/5.10.0/$archname
2287         /usr/local/lib/perl5/5.10.0
2288         /usr/local/lib/perl5/site_perl/5.10.0/$archname
2289         /usr/local/lib/perl5/site_perl/5.10.0
2290
2291         /usr/local/lib/perl5/site_perl/5.8.8
2292
2293         /usr/local/lib/perl5/site_perl/5.8.7
2294
2295         /usr/local/lib/perl5/site_perl/
2296
2297 Note that the earlier $archname entries are now gone, but pure perl
2298 modules from earlier versions will still be found.
2299
2300 This way, you can choose to share compatible extensions, but also upgrade
2301 to a newer version of an extension that may be incompatible with earlier
2302 versions, without breaking the earlier versions' installations.
2303
2304 =head2 Maintaining completely separate versions
2305
2306 Many users prefer to keep all versions of perl in completely
2307 separate directories.  This guarantees that an update to one version
2308 won't interfere with another version.  (The defaults guarantee this for
2309 libraries after 5.6.0, but not for executables. TODO?)  One convenient
2310 way to do this is by using a separate prefix for each version, such as
2311
2312         sh Configure -Dprefix=/opt/perl5.10.0
2313
2314 and adding /opt/perl5.10.0/bin to the shell PATH variable.  Such users
2315 may also wish to add a symbolic link /usr/local/bin/perl so that
2316 scripts can still start with #!/usr/local/bin/perl.
2317
2318 Others might share a common directory for maintenance sub-versions
2319 (e.g. 5.10 for all 5.10.x versions), but change directory with
2320 each major version.
2321
2322 If you are installing a development subversion, you probably ought to
2323 seriously consider using a separate directory, since development
2324 subversions may not have all the compatibility wrinkles ironed out
2325 yet.
2326
2327 =head2 Upgrading from 5.8.x or earlier
2328
2329 B<Perl 5.10.0 is binary incompatible with Perl 5.8.x and any earlier
2330 Perl release.>  Perl modules having binary parts
2331 (meaning that a C compiler is used) will have to be recompiled to be
2332 used with 5.10.0.  If you find you do need to rebuild an extension with
2333 5.10.0, you may safely do so without disturbing the older
2334 installations.  (See L<"Coexistence with earlier versions of perl 5">
2335 above.)
2336
2337 See your installed copy of the perllocal.pod file for a (possibly
2338 incomplete) list of locally installed modules.  Note that you want
2339 perllocal.pod, not perllocale.pod, for installed module information.
2340
2341 =head1 Minimizing the Perl installation
2342
2343 The following section is meant for people worrying about squeezing the
2344 Perl installation into minimal systems (for example when installing
2345 operating systems, or in really small filesystems).
2346
2347 Leaving out as many extensions as possible is an obvious way:
2348 Encode, with its big conversion tables, consumes a lot of
2349 space.  On the other hand, you cannot throw away everything.  The
2350 Fcntl module is pretty essential.  If you need to do network
2351 programming, you'll appreciate the Socket module, and so forth: it all
2352 depends on what do you need to do.
2353
2354 In the following we offer two different slimmed down installation
2355 recipes.  They are informative, not normative: the choice of files
2356 depends on what you need.
2357
2358 Firstly, the bare minimum to run this script
2359
2360   use strict;
2361   use warnings;
2362   foreach my $f (</*>) {
2363      print("$f\n");
2364   }
2365
2366 in Linux is as follows (under $Config{prefix}):
2367
2368   ./bin/perl
2369   ./lib/perl5/5.9.3/strict.pm
2370   ./lib/perl5/5.9.3/warnings.pm
2371   ./lib/perl5/5.9.3/i686-linux/File/Glob.pm
2372   ./lib/perl5/5.9.3/i686-linux/XSLoader.pm
2373   ./lib/perl5/5.9.3/i686-linux/auto/File/Glob/Glob.so
2374
2375 Secondly, Debian perl-base package contains the following files,
2376 size about 1.9MB in its i386 version:
2377
2378   /usr/bin/perl
2379   /usr/bin/perl5.8.4
2380   /usr/lib/perl/5.8
2381   /usr/lib/perl/5.8.4/B.pm
2382   /usr/lib/perl/5.8.4/B/Deparse.pm
2383   /usr/lib/perl/5.8.4/Config.pm
2384   /usr/lib/perl/5.8.4/Cwd.pm
2385   /usr/lib/perl/5.8.4/Data/Dumper.pm
2386   /usr/lib/perl/5.8.4/DynaLoader.pm
2387   /usr/lib/perl/5.8.4/Errno.pm
2388   /usr/lib/perl/5.8.4/Fcntl.pm
2389   /usr/lib/perl/5.8.4/File/Glob.pm
2390   /usr/lib/perl/5.8.4/IO.pm
2391   /usr/lib/perl/5.8.4/IO/File.pm
2392   /usr/lib/perl/5.8.4/IO/Handle.pm
2393   /usr/lib/perl/5.8.4/IO/Pipe.pm
2394   /usr/lib/perl/5.8.4/IO/Seekable.pm
2395   /usr/lib/perl/5.8.4/IO/Select.pm
2396   /usr/lib/perl/5.8.4/IO/Socket.pm
2397   /usr/lib/perl/5.8.4/POSIX.pm
2398   /usr/lib/perl/5.8.4/Socket.pm
2399   /usr/lib/perl/5.8.4/XSLoader.pm
2400   /usr/lib/perl/5.8.4/auto/Cwd/Cwd.bs
2401   /usr/lib/perl/5.8.4/auto/Cwd/Cwd.so
2402   /usr/lib/perl/5.8.4/auto/Data/Dumper/Dumper.bs
2403   /usr/lib/perl/5.8.4/auto/Data/Dumper/Dumper.so
2404   /usr/lib/perl/5.8.4/auto/DynaLoader/DynaLoader.a
2405   /usr/lib/perl/5.8.4/auto/DynaLoader/autosplit.ix
2406   /usr/lib/perl/5.8.4/auto/DynaLoader/dl_expandspec.al
2407   /usr/lib/perl/5.8.4/auto/DynaLoader/dl_find_symbol_anywhere.al
2408   /usr/lib/perl/5.8.4/auto/DynaLoader/dl_findfile.al
2409   /usr/lib/perl/5.8.4/auto/DynaLoader/extralibs.ld
2410   /usr/lib/perl/5.8.4/auto/Fcntl/Fcntl.bs
2411   /usr/lib/perl/5.8.4/auto/Fcntl/Fcntl.so
2412   /usr/lib/perl/5.8.4/auto/File/Glob/Glob.bs
2413   /usr/lib/perl/5.8.4/auto/File/Glob/Glob.so
2414   /usr/lib/perl/5.8.4/auto/IO/IO.bs
2415   /usr/lib/perl/5.8.4/auto/IO/IO.so
2416   /usr/lib/perl/5.8.4/auto/POSIX/POSIX.bs
2417   /usr/lib/perl/5.8.4/auto/POSIX/POSIX.so
2418   /usr/lib/perl/5.8.4/auto/POSIX/autosplit.ix
2419   /usr/lib/perl/5.8.4/auto/POSIX/load_imports.al
2420   /usr/lib/perl/5.8.4/auto/Socket/Socket.bs
2421   /usr/lib/perl/5.8.4/auto/Socket/Socket.so
2422   /usr/lib/perl/5.8.4/lib.pm
2423   /usr/lib/perl/5.8.4/re.pm
2424   /usr/share/doc/perl-base
2425   /usr/share/doc/perl/AUTHORS.gz
2426   /usr/share/doc/perl/Documentation
2427   /usr/share/doc/perl/README.Debian.gz
2428   /usr/share/doc/perl/changelog.Debian.gz
2429   /usr/share/doc/perl/copyright
2430   /usr/share/man/man1/perl.1.gz
2431   /usr/share/perl/5.8
2432   /usr/share/perl/5.8.4/AutoLoader.pm
2433   /usr/share/perl/5.8.4/Carp.pm
2434   /usr/share/perl/5.8.4/Carp/Heavy.pm
2435   /usr/share/perl/5.8.4/Exporter.pm
2436   /usr/share/perl/5.8.4/Exporter/Heavy.pm
2437   /usr/share/perl/5.8.4/File/Spec.pm
2438   /usr/share/perl/5.8.4/File/Spec/Unix.pm
2439   /usr/share/perl/5.8.4/FileHandle.pm
2440   /usr/share/perl/5.8.4/Getopt/Long.pm
2441   /usr/share/perl/5.8.4/IO/Socket/INET.pm
2442   /usr/share/perl/5.8.4/IO/Socket/UNIX.pm
2443   /usr/share/perl/5.8.4/IPC/Open2.pm
2444   /usr/share/perl/5.8.4/IPC/Open3.pm
2445   /usr/share/perl/5.8.4/List/Util.pm
2446   /usr/share/perl/5.8.4/Scalar/Util.pm
2447   /usr/share/perl/5.8.4/SelectSaver.pm
2448   /usr/share/perl/5.8.4/Symbol.pm
2449   /usr/share/perl/5.8.4/Text/ParseWords.pm
2450   /usr/share/perl/5.8.4/Text/Tabs.pm
2451   /usr/share/perl/5.8.4/Text/Wrap.pm
2452   /usr/share/perl/5.8.4/attributes.pm
2453   /usr/share/perl/5.8.4/base.pm
2454   /usr/share/perl/5.8.4/bytes.pm
2455   /usr/share/perl/5.8.4/bytes_heavy.pl
2456   /usr/share/perl/5.8.4/constant.pm
2457   /usr/share/perl/5.8.4/fields.pm
2458   /usr/share/perl/5.8.4/integer.pm
2459   /usr/share/perl/5.8.4/locale.pm
2460   /usr/share/perl/5.8.4/overload.pm
2461   /usr/share/perl/5.8.4/strict.pm
2462   /usr/share/perl/5.8.4/utf8.pm
2463   /usr/share/perl/5.8.4/utf8_heavy.pl
2464   /usr/share/perl/5.8.4/vars.pm
2465   /usr/share/perl/5.8.4/warnings.pm
2466   /usr/share/perl/5.8.4/warnings/register.pm
2467
2468 A nice trick to find out the minimal set of Perl library files you will
2469 need to run a Perl program is
2470
2471    perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
2472
2473 (this will not find libraries required in runtime, unfortunately, but
2474 it's a minimal set) and if you want to find out all the files you can
2475 use something like the below
2476
2477    strace perl -le 'do "x.pl"' 2>&1 | perl -nle '/^open\(\"(.+?)"/ && print $1'
2478
2479 (The 'strace' is Linux-specific, other similar utilities include 'truss'
2480 and 'ktrace'.)
2481
2482 =head2 C<-DNO_MATHOMS>
2483
2484 If you configure perl with C<-Accflags=-DNO_MATHOMS>, the functions from
2485 F<mathoms.c> will not be compiled in. Those functions are no longer used
2486 by perl itself; for source compatibility reasons, though, they weren't
2487 completely removed.
2488
2489 =head1 DOCUMENTATION
2490
2491 Read the manual entries before running perl.  The main documentation
2492 is in the pod/ subdirectory and should have been installed during the
2493 build process.  Type B<man perl> to get started.  Alternatively, you
2494 can type B<perldoc perl> to use the supplied perldoc script.  This is
2495 sometimes useful for finding things in the library modules.
2496
2497 =head1 AUTHOR
2498
2499 Original author:  Andy Dougherty doughera@lafayette.edu , borrowing very
2500 heavily from the original README by Larry Wall, with lots of helpful
2501 feedback and additions from the perl5-porters@perl.org folks.
2502
2503 If you have problems, corrections, or questions, please see
2504 L<"Reporting Problems"> above.
2505
2506 =head1 REDISTRIBUTION
2507
2508 This document is part of the Perl package and may be distributed under
2509 the same terms as perl itself, with the following additional request:
2510 If you are distributing a modified version of perl (perhaps as part of
2511 a larger package) please B<do> modify these installation instructions
2512 and the contact information to match your distribution.