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