This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
c90f6b34e881ec4cad3e7be8132e218d3904682f
[perl5.git] / INSTALL
1 =head1 NAME
2
3 Install - Build and Installation guide for perl5.
4
5 =head1 SYNOPSIS
6
7 The basic steps to build and install perl5 on a Unix system are:
8
9         rm -f config.sh Policy.sh
10         sh Configure -de
11         make
12         make test
13         make install
14
15         # You may also wish to add these:
16         (cd /usr/include && h2ph *.h sys/*.h)
17         (installhtml --help)
18         (cd pod && make tex  && <process the latex files>)
19
20 Each of these is explained in further detail below.
21
22 The above commands will install Perl to /usr/local or /opt, depending
23 on the platform.  If that's not okay with you, use
24
25         rm -f config.sh Policy.sh
26         sh Configure
27         make
28         make test
29         make install
30
31 Full configuration instructions can be found in the INSTALL file.
32
33 For information on non-Unix systems, see the section on
34 L<"Porting information"> below.
35
36 If you have problems, corrections, or questions, please see
37 L<"Reporting Problems"> below.
38
39 For information on what's new in this release, see the
40 pod/perldelta.pod file.  For more detailed information about specific
41 changes, see the Changes file.
42
43 IMPORTANT NOTE:  5.005_53 and later releases do not export unadorned
44 global symbols anymore.  This means most CPAN modules probably won't
45 build under this release without adding '-DPERL_POLLUTE' to ccflags
46 in config.sh.  This is not the default because we want the modules
47 to get fixed *before* the 5.6 release.  pod/perldelta.pod contains
48 additional notes about this.
49
50 =head1 DESCRIPTION
51
52 This document is written in pod format as an easy way to indicate its
53 structure.  The pod format is described in pod/perlpod.pod, but you can
54 read it as is with any pager or editor.  Headings and items are marked
55 by lines beginning with '='.  The other mark-up used is
56
57     B<text>     embolden text, used for switches, programs or commands
58     C<code>     literal code
59     L<name>     A link (cross reference) to name
60
61 You should probably at least skim through this entire document before
62 proceeding.
63
64 If you're building Perl on a non-Unix system, you should also read
65 the README file specific to your operating system, since this may
66 provide additional or different instructions for building Perl.
67
68 If there is a hint file for your system (in the hints/ directory) you
69 should also read that hint file for specific information for your
70 system.  (Unixware users should use the svr4.sh hint file.)  If
71 there is a README file for your platform, then you should read
72 that too.  Additional information is in the Porting/ directory.
73
74 =head1 WARNING:  This version is not binary compatible with Perl 5.005.
75
76 If you have dynamically loaded extensions that you built under perl
77 5.005, you will need to rebuild and reinstall those extensions to use
78 them with 5.6.  Pure perl modules should continue to work just fine
79 without reinstallation.  See the discussions below on L<"Coexistence
80 with earlier versions of perl5"> and L<"Upgrading from 5.005 to
81 5.6"> for more details.
82
83 The standard extensions supplied with Perl will be handled automatically.
84
85 In a related issue, old modules may possibly be affected by the
86 changes in the Perl language in the current release.  Please see
87 pod/perldelta.pod (and pod/perl500Xdelta.pod) for a description of
88 what's changed.  See also your installed copy of the perllocal.pod
89 file for a (possibly incomplete) list of locally installed modules.
90 Also see CPAN::autobundle for one way to make a "bundle" of your
91 currently installed modules.
92
93 =head1 WARNING:  This version requires a compiler that supports ANSI C.
94
95 If you find that your C compiler is not ANSI-capable, try obtaining
96 GCC, available from GNU mirrors worldwide (e.g. ftp://ftp.gnu.org/pub/gnu).
97 Another alternative may be to use a tool like ansi2knr to convert the
98 sources back to K&R style, but there is no guarantee this route will get
99 you anywhere, since the prototypes are not the only ANSI features used
100 in the Perl sources.  ansi2knr is usually found as part of the freely
101 available Ghostscript distribution.  Another similar tool is
102 unprotoize, distributed with GCC.  Since unprotoize requires GCC to
103 run, you may have to run it on a platform where GCC is available, and move
104 the sources back to the platform without GCC.
105
106 If you succeed in automatically converting the sources to a K&R compatible
107 form, be sure to email perlbug@perl.com to let us know the steps you
108 followed.  This will enable us to officially support this option.
109
110 =head1 Space Requirements
111
112 The complete perl5 source tree takes up about 15 MB of disk space.
113 After completing make, it takes up roughly 20 MB, though the actual
114 total is likely to be quite system-dependent.  The installation
115 directories need something on the order of 15 MB, though again that
116 value is system-dependent.
117
118 =head1 Start with a Fresh Distribution
119
120 If you have built perl before, you should clean out the build directory
121 with the command
122
123         make distclean
124
125 or
126
127         make realclean
128
129 The only difference between the two is that make distclean also removes
130 your old config.sh and Policy.sh files.
131
132 The results of a Configure run are stored in the config.sh and Policy.sh
133 files.  If you are upgrading from a previous version of perl, or if you
134 change systems or compilers or make other significant changes, or if
135 you are experiencing difficulties building perl, you should probably
136 not re-use your old config.sh.  Simply remove it
137
138         rm -f config.sh
139
140 If you wish to use your old config.sh, be especially attentive to the
141 version and architecture-specific questions and answers.  For example,
142 the default directory for architecture-dependent library modules
143 includes the version name.  By default, Configure will reuse your old
144 name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
145 Configure for a different version, e.g. 5.004.  Yes, Configure should
146 probably check and correct for this, but it doesn't, presently.
147 Similarly, if you used a shared libperl.so (see below) with version
148 numbers, you will probably want to adjust them as well.
149
150 Also, be careful to check your architecture name.  For example, some
151 Linux distributions use i386, while others may use i486.  If you build
152 it yourself, Configure uses the output of the arch command, which
153 might be i586 or i686 instead.  If you pick up a precompiled binary, or
154 compile extensions on different systems, they might not all agree on
155 the architecture name.
156
157 In short, if you wish to use your old config.sh, I recommend running
158 Configure interactively rather than blindly accepting the defaults.
159
160 If your reason to reuse your old config.sh is to save your particular
161 installation choices, then you can probably achieve the same effect by
162 using the Policy.sh file.  See the section on L<"Site-wide Policy
163 settings"> below.  If you wish to start with a fresh distribution, you
164 also need to remove any old Policy.sh files you may have with
165
166         rm -f Policy.sh
167
168 =head1 Run Configure
169
170 Configure will figure out various things about your system.  Some
171 things Configure will figure out for itself, other things it will ask
172 you about.  To accept the default, just press RETURN.   The default is
173 almost always okay.  It is normal for some things to be "NOT found",
174 since Configure often searches for many different ways of performing
175 the same function.
176
177 At any Configure prompt, you can type  &-d and Configure will use the
178 defaults from then on.
179
180 After it runs, Configure will perform variable substitution on all the
181 *.SH files and offer to run make depend.
182
183 =head2 Common Configure options
184
185 Configure supports a number of useful options.  Run B<Configure -h> to
186 get a listing.  See the Porting/Glossary file for a complete list of
187 Configure variables you can set and their definitions.
188
189 =over 4
190
191 =item gcc
192
193 To compile with gcc you should run
194
195         sh Configure -Dcc=gcc
196
197 This is the preferred way to specify gcc (or another alternative
198 compiler) so that the hints files can set appropriate defaults.
199
200 =item Installation prefix
201
202 By default, for most systems, perl will be installed in
203 /usr/local/{bin, lib, man}.  (See L<"Installation Directories">
204 and L<"Coexistence with earlier versions of perl5"> below for
205 further details.)
206
207 You can specify a different 'prefix' for the default installation
208 directory, when Configure prompts you or by using the Configure command
209 line option -Dprefix='/some/directory', e.g.
210
211         sh Configure -Dprefix=/opt/perl
212
213 If your prefix contains the string "perl", then the suggested
214 directory structure is simplified.  For example, if you use
215 prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
216 /opt/perl/lib/perl5/.  Again, see L<"Installation Directories"> below
217 for more details.
218
219 NOTE:  You must not specify an installation directory that is the same
220 as or below your perl source directory.  If you do, installperl will
221 attempt infinite recursion.
222
223 =item /usr/bin/perl
224
225 It may seem obvious, but Perl is useful only when users can easily
226 find it.  It's often a good idea to have both /usr/bin/perl and
227 /usr/local/bin/perl be symlinks to the actual binary.  Be especially
228 careful, however, not to overwrite a version of perl supplied by your
229 vendor unless you are sure you know what you are doing.
230
231 By default, Configure will arrange for /usr/bin/perl to be linked to
232 the current version of perl.  You can turn off that behavior by running
233
234         Configure -Uinstallusrbinperl
235
236 or by answering 'no' to the appropriate Configure prompt.
237
238 In any case, system administrators are strongly encouraged to
239 put (symlinks to) perl and its accompanying utilities, such as perldoc,
240 into a directory typically found along a user's PATH, or in another
241 obvious and convenient place.
242
243 =item Overriding an old config.sh
244
245 If you want to use your old config.sh but override some of the items
246 with command line options, you need to use B<Configure -O>.
247
248 =back
249
250 If you are willing to accept all the defaults, and you want terse
251 output, you can run
252
253         sh Configure -des
254
255 For my Solaris system, I usually use
256
257         sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
258
259 =head2 GNU-style configure
260
261 If you prefer the GNU-style configure command line interface, you can
262 use the supplied configure.gnu command, e.g.
263
264         CC=gcc ./configure.gnu
265
266 The configure.gnu script emulates a few of the more common configure
267 options.  Try
268
269         ./configure.gnu --help
270
271 for a listing.
272
273 Cross compiling and compiling in a different directory are not supported.
274
275 (The file is called configure.gnu to avoid problems on systems
276 that would not distinguish the files "Configure" and "configure".)
277
278 =head2 Installation Directories
279
280 The installation directories can all be changed by answering the
281 appropriate questions in Configure.  For convenience, all the
282 installation questions are near the beginning of Configure.
283 Further, there are a number of additions to the installation
284 directories since 5.005, so reusing your old config.sh may not
285 be sufficient to put everything where you want it.
286
287 I highly recommend running Configure interactively to be sure it puts
288 everything where you want it.  At any point during the Configure
289 process, you can answer a question with  &-d  and Configure will use
290 the defaults from then on.
291
292 The defaults are intended to be reasonable and sensible for most
293 people building from sources.  Those who build and distribute binary
294 distributions or who export perl to a range of systems will probably
295 need to alter them.  If you are content to just accept the defaults,
296 you can safely skip the next section.
297
298 The directories set up by Configure fall into three broad categories.
299
300 =over 4
301
302 =item Directories for the perl distribution
303
304 By default, Configure will use the following directories for 5.6.
305 $version is the full perl version number, including subversion, e.g.
306 5.6 or 5.6.1, and $archname is a string like sun4-sunos,
307 determined by Configure.  The full definitions of all Configure
308 variables are in the file Porting/Glossary.
309
310     Configure variable  Default value
311     $prefix             /usr/local
312     $bin                $prefix/bin
313     $scriptdir          $prefix/bin
314     $privlib            $prefix/lib/perl5/$version
315     $archlib            $prefix/lib/perl5/$version/$archname
316     $man1dir            $prefix/man/man1
317     $man3dir            $prefix/man/man3
318     $html1dir           (none)
319     $html3dir           (none)
320
321 Actually, Configure recognizes the SVR3-style
322 /usr/local/man/l_man/man1 directories, if present, and uses those
323 instead.  Also, if $prefix contains the string "perl", the library
324 directories are simplified as described below.  For simplicity, only
325 the common style is shown here.
326
327 =item Directories for site-specific add-on files
328
329 After perl is installed, you may later wish to add modules (e.g. from
330 CPAN) or scripts.  Configure will set up the following directories to
331 be used for installing those add-on modules and scripts.  $apiversion
332 is the perl version number (without subversion), e.g. 5.6.
333
334     Configure variable  Default value
335     $siteprefix         $prefix
336     $sitebin            $siteprefix/bin
337     $sitescriptdir      $siteprefix/bin
338     $sitelib            $siteprefix/lib/perl5/site_perl/
339     $sitearch           $siteprefix/lib/perl5/site_perl/$apiversion/$archname
340     $siteman1dir        $siteprefix/man/man1
341     $siteman3dir        $siteprefix/man/man3
342     $sitehtml1dir       (none)
343     $sitehtml3dir       (none)
344
345 By default, ExtUtils::MakeMaker will install architecture-independent
346 modules into $sitelib/$apiversion and architecture-dependent modules
347 into $sitearch.
348
349 =item Directories for vendor-supplied add-on files
350
351 Lastly, if you are building a binary distribution of perl for
352 distribution, Configure can optionally set up the following directories
353 for you to use to distribute add-on modules.
354
355     Configure variable  Default value
356     $vendorprefix       (none)
357     (The next ones are set only if vendorprefix is set.)
358     $vendorbin          $vendorprefix/bin
359     $vendorscriptdir    $vendorprefix/bin
360     $vendorlib          $vendorprefix/lib/perl5/vendor_perl/
361     $vendorarch     $vendorprefix/lib/perl5/vendor_perl/$apiversion/$archname
362     $vendorman1dir      $vendorprefix/man/man1
363     $vendorman3dir      $vendorprefix/man/man3
364     $vendorhtml1dir     (none)
365     $vendorhtml3dir     (none)
366
367 These are normally empty, but may be set as needed.  For example,
368 a vendor might choose the following settings:
369
370         $prefix         /usr/bin
371         $siteprefix     /usr/local/bin
372         $vendorprefix   /usr/bin
373
374 This would have the effect of setting the following:
375
376         $bin            /usr/bin
377         $scriptdir      /usr/bin
378         $privlib        /usr/lib/perl5/$version
379         $archlib        /usr/lib/perl5/$version/$archname
380         $man1dir        /usr/man/man1
381         $man3dir        /usr/man/man3
382
383         $sitebin        /usr/local/bin
384         $sitescriptdir  /usr/local/bin
385         $sitelib        /usr/local/lib/perl5/site_perl/
386         $sitearch       /usr/local/lib/perl5/site_perl/$apiversion/$archname
387         $siteman1dir    /usr/local/man/man1
388         $siteman3dir    /usr/local/man/man3
389
390         $vendorbin              /usr/bin
391         $vendorscriptdir        /usr/bin
392         $vendorlib      /usr/lib/perl5/vendor_perl/
393         $vendorarch     /usr/lib/perl5/vendor_perl/$apiversion/$archname
394         $vendorman1dir  /usr/man/man1
395         $vendorman3dir  /usr/man/man3
396
397 Note how in this example, the vendor-supplied directories are in the
398 /usr hierarchy, while the directories reserved for the end-user are in
399 the /usr/local hierarchy.  Note too how the vendor-supplied
400 directories track $apiversion, rather than $version, to ease upgrading
401 between maintenance subversions.  See L<"Coexistence with earlier
402 versions of perl5"> below for more details.
403
404 Of course you may use these directories however you see fit.  For
405 example, you may wish to use $siteprefix for site-specific files that
406 are stored locally on your own disk and use $vendorprefix for
407 site-specific files that are stored elsewhere on your organization's
408 network.  One way to do that would be something like
409
410         sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
411
412 =item otherlibdirs
413
414 As a final catch-all, Configure also offers an $otherlibdirs
415 variable.  This variable contains a colon-separated list of additional
416 directories to add to @INC.  By default, it will be set to
417 $prefix/site_perl if Configure detects that you have 5.004-era modules
418 installed there.  However, you can set it to anything you like.
419
420 =item Man Pages
421
422 In versions 5.005_57 and earlier, the default was to store module man
423 pages in a version-specific directory, such as
424 /usr/local/lib/perl5/$version/man/man3.  The default for 5.005_58 and
425 after is /usr/local/man/man3 so that most users can find the man pages
426 without resetting MANPATH.
427
428 You can continue to use the old default from the command line with
429
430         sh Configure -Dman3dir=/usr/local/lib/perl5/5.6/man/man3
431
432 Some users also prefer to use a .3pm suffix.  You can do that with
433
434         sh Configure -Dman3ext=3pm
435
436 Again, these are just the defaults, and can be changed as you run
437 Configure.
438
439 =item HTML pages
440
441 As of perl5.005_57, the standard perl installation does not do
442 anything with HTML documentation, but that may change in the future.
443 Further, some add-on modules may wish to install HTML documents.  The
444 html Configure variables listed above are provided if you wish to
445 specify where such documents should be placed.  The default is "none",
446 but will likely eventually change to something useful based on user
447 feedback.
448
449 =back
450
451 Some users prefer to append a "/share" to $privlib and $sitelib
452 to emphasize that those directories can be shared among different
453 architectures.
454
455 Note that these are just the defaults.  You can actually structure the
456 directories any way you like.  They don't even have to be on the same
457 filesystem.
458
459 Further details about the installation directories, maintenance and
460 development subversions, and about supporting multiple versions are
461 discussed in L<"Coexistence with earlier versions of perl5"> below.
462
463 If you specify a prefix that contains the string "perl", then the
464 library directory structure is slightly simplified.  Instead of
465 suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
466
467 Thus, for example, if you Configure with
468 -Dprefix=/opt/perl, then the default library directories for 5.6 are
469
470     Configure variable  Default value
471         $privlib        /opt/perl/lib/5.6
472         $archlib        /opt/perl/lib/5.6/$archname
473         $sitelib        /opt/perl/lib/site_perl/5.6
474         $sitearch       /opt/perl/lib/site_perl/5.6/$archname
475
476 =head2 Changing the installation directory
477
478 Configure distinguishes between the directory in which perl (and its
479 associated files) should be installed and the directory in which it
480 will eventually reside.  For most sites, these two are the same; for
481 sites that use AFS, this distinction is handled automatically.
482 However, sites that use software such as depot to manage software
483 packages, or users building binary packages for distribution may also
484 wish to install perl into a different directory and use that
485 management software to move perl to its final destination.  This
486 section describes how to do that.
487
488 Suppose you want to install perl under the /tmp/perl5 directory.  You
489 could edit config.sh and change all the install* variables to point to
490 /tmp/perl5 instead of /usr/local, or you could simply use the
491 following command line:
492
493         sh Configure -Dinstallprefix=/tmp/perl5
494
495 (replace /tmp/perl5 by a directory of your choice).
496
497 Beware, though, that if you go to try to install new add-on
498 modules, they too will get installed in under '/tmp/perl5' if you
499 follow this example.  The next section shows one way of dealing with
500 that problem.
501
502 =head2 Creating an installable tar archive
503
504 If you need to install perl on many identical systems, it is
505 convenient to compile it once and create an archive that can be
506 installed on multiple systems.  Suppose, for example, that you want to
507 create an archive that can be installed in /opt/perl.
508 Here's one way to do that:
509
510     # Set up to install perl into a different directory,
511     # e.g. /tmp/perl5 (see previous part).
512     sh Configure -Dinstallprefix=/tmp/perl5 -Dprefix=/opt/perl -des
513     make
514     make test
515     make install   # This will install everything into /tmp/perl5.
516     cd /tmp/perl5
517     # Edit $archlib/Config.pm and $archlib/.packlist to change all the
518     # install* variables back to reflect where everything will
519     # really be installed.  (That is, change /tmp/perl5 to /opt/perl
520     # everywhere in those files.)
521     # Check the scripts in $scriptdir to make sure they have the correct
522     # #!/wherever/perl line.
523     tar cvf ../perl5-archive.tar .
524     # Then, on each machine where you want to install perl,
525     cd /opt/perl # Or wherever you specified as $prefix
526     tar xvf perl5-archive.tar
527
528 =head2 Site-wide Policy settings
529
530 After Configure runs, it stores a number of common site-wide "policy"
531 answers (such as installation directories and the local perl contact
532 person) in the Policy.sh file.  If you want to build perl on another
533 system using the same policy defaults, simply copy the Policy.sh file
534 to the new system and Configure will use it along with the appropriate
535 hint file for your system.
536
537 Alternatively, if you wish to change some or all of those policy
538 answers, you should
539
540         rm -f Policy.sh
541
542 to ensure that Configure doesn't re-use them.
543
544 Further information is in the Policy_sh.SH file itself.
545
546 If the generated Policy.sh file is unsuitable, you may freely edit it
547 to contain any valid shell commands.  It will be run just after the
548 platform-specific hints files.
549
550 Note:  Since the directory hierarchy for 5.6 contains a number of
551 new vendor* and site* entries, your Policy.sh file will probably not
552 set them to your desired values.  I encourage you to run Configure
553 interactively to be sure it puts things where you want them.
554
555 =head2 Configure-time Options
556
557 There are several different ways to Configure and build perl for your
558 system.  For most users, the defaults are sensible and will work.
559 Some users, however, may wish to further customize perl.  Here are
560 some of the main things you can change.
561
562 =head2 Threads
563
564 On some platforms, perl5.005 and later can be compiled with
565 experimental support for threads.  To enable this, read the file
566 README.threads, and then try:
567
568         sh Configure -Dusethreads
569
570 Currently, you need to specify -Dusethreads on the Configure command
571 line so that the hint files can make appropriate adjustments.
572
573 The default is to compile without thread support.
574
575 =head2 Selecting File IO mechanisms
576
577 Previous versions of perl used the standard IO mechanisms as defined in
578 stdio.h.  Versions 5.003_02 and later of perl allow alternate IO
579 mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
580 the default and is the only supported mechanism.
581
582 This PerlIO abstraction can be enabled either on the Configure command
583 line with
584
585         sh Configure -Duseperlio
586
587 or interactively at the appropriate Configure prompt.
588
589 If you choose to use the PerlIO abstraction layer, there are two
590 (experimental) possibilities for the underlying IO calls.  These have been
591 tested to some extent on some platforms, but are not guaranteed to work
592 everywhere.
593
594 =over 4
595
596 =item 1.
597
598 AT&T's "sfio".  This has superior performance to stdio.h in many
599 cases, and is extensible by the use of "discipline" modules.  Sfio
600 currently only builds on a subset of the UNIX platforms perl supports.
601 Because the data structures are completely different from stdio, perl
602 extension modules or external libraries may not work.  This
603 configuration exists to allow these issues to be worked on.
604
605 This option requires the 'sfio' package to have been built and installed.
606 A (fairly old) version of sfio is in CPAN.
607
608 You select this option by
609
610         sh Configure -Duseperlio -Dusesfio
611
612 If you have already selected -Duseperlio, and if Configure detects
613 that you have sfio, then sfio will be the default suggested by
614 Configure.
615
616 Note:  On some systems, sfio's iffe configuration script fails to
617 detect that you have an atexit function (or equivalent).  Apparently,
618 this is a problem at least for some versions of Linux and SunOS 4.
619 Configure should detect this problem and warn you about problems with
620 _exit vs. exit.  If you have this problem, the fix is to go back to
621 your sfio sources and correct iffe's guess about atexit.
622
623 There also might be a more recent release of Sfio that fixes your
624 problem.
625
626 =item 2.
627
628 Normal stdio IO, but with all IO going through calls to the PerlIO
629 abstraction layer.  This configuration can be used to check that perl and
630 extension modules have been correctly converted to use the PerlIO
631 abstraction.
632
633 This configuration should work on all platforms (but might not).
634
635 You select this option via:
636
637         sh Configure -Duseperlio -Uusesfio
638
639 If you have already selected -Duseperlio, and if Configure does not
640 detect sfio, then this will be the default suggested by Configure.
641
642 =back
643
644 =head2 Dynamic Loading
645
646 By default, Configure will compile perl to use dynamic loading if
647 your system supports it.  If you want to force perl to be compiled
648 statically, you can either choose this when Configure prompts you or
649 you can use the Configure command line option -Uusedl.
650
651 =head2 Building a shared libperl.so Perl library
652
653 Currently, for most systems, the main perl executable is built by
654 linking the "perl library" libperl.a with perlmain.o, your static
655 extensions (usually just DynaLoader.a) and various extra libraries,
656 such as -lm.
657
658 On some systems that support dynamic loading, it may be possible to
659 replace libperl.a with a shared libperl.so.  If you anticipate building
660 several different perl binaries (e.g. by embedding libperl into
661 different programs, or by using the optional compiler extension), then
662 you might wish to build a shared libperl.so so that all your binaries
663 can share the same library.
664
665 The disadvantages are that there may be a significant performance
666 penalty associated with the shared libperl.so, and that the overall
667 mechanism is still rather fragile with respect to different versions
668 and upgrades.
669
670 In terms of performance, on my test system (Solaris 2.5_x86) the perl
671 test suite took roughly 15% longer to run with the shared libperl.so.
672 Your system and typical applications may well give quite different
673 results.
674
675 The default name for the shared library is typically something like
676 libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 or simply
677 libperl.so.  Configure tries to guess a sensible naming convention
678 based on your C library name.  Since the library gets installed in a
679 version-specific architecture-dependent directory, the exact name
680 isn't very important anyway, as long as your linker is happy.
681
682 For some systems (mostly SVR4), building a shared libperl is required
683 for dynamic loading to work, and hence is already the default.
684
685 You can elect to build a shared libperl by
686
687         sh Configure -Duseshrplib
688
689 To build a shared libperl, the environment variable controlling shared
690 library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
691 NeXTSTEP/OPENSTEP/Rhapsody, LIBRARY_PATH for BeOS, SHLIB_PATH for
692 HP-UX, LIBPATH for AIX, PATH for cygwin) must be set up to include
693 the Perl build directory because that's where the shared libperl will
694 be created.  Configure arranges makefile to have the correct shared
695 library search settings.
696
697 However, there are some special cases where manually setting the
698 shared library path might be required.  For example, if you want to run
699 something like the following with the newly-built but not-yet-installed
700 ./perl:
701
702         cd t; ./perl misc/failing_test.t
703 or
704         ./perl -Ilib ~/my_mission_critical_test
705
706 then you need to set up the shared library path explicitly.
707 You can do this with
708
709    LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
710
711 for Bourne-style shells, or
712
713    setenv LD_LIBRARY_PATH `pwd`
714
715 for Csh-style shells.  (This procedure may also be needed if for some
716 unexpected reason Configure fails to set up makefile correctly.)
717
718 You can often recognize failures to build/use a shared libperl from error
719 messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
720 for example:
721 18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
722
723 There is also an potential problem with the shared perl library if you
724 want to have more than one "flavor" of the same version of perl (e.g.
725 with and without -DDEBUGGING).  For example, suppose you build and
726 install a standard Perl 5.004 with a shared library.  Then, suppose you
727 try to build Perl 5.004 with -DDEBUGGING enabled, but everything else
728 the same, including all the installation directories.  How can you
729 ensure that your newly built perl will link with your newly built
730 libperl.so.4 rather with the installed libperl.so.4?  The answer is
731 that you might not be able to.  The installation directory is encoded
732 in the perl binary with the LD_RUN_PATH environment variable (or
733 equivalent ld command-line option).  On Solaris, you can override that
734 with LD_LIBRARY_PATH; on Linux you can't.  On Digital Unix, you can
735 override LD_LIBRARY_PATH by setting the _RLD_ROOT environment variable
736 to point to the perl build directory.
737
738 The only reliable answer is that you should specify a different
739 directory for the architecture-dependent library for your -DDEBUGGING
740 version of perl.  You can do this by changing all the *archlib*
741 variables in config.sh to point to your new architecture-dependent library.
742
743 =head2 Malloc Issues
744
745 Perl relies heavily on malloc(3) to grow data structures as needed,
746 so perl's performance can be noticeably affected by the performance of
747 the malloc function on your system.  The perl source is shipped with a
748 version of malloc that has been optimized for the typical requests from
749 perl, so there's a chance that it may be both faster and use less memory
750 than your system malloc.
751
752 However, if your system already has an excellent malloc, or if you are
753 experiencing difficulties with extensions that use third-party libraries
754 that call malloc, then you should probably use your system's malloc.
755 (Or, you might wish to explore the malloc flags discussed below.)
756
757 =over 4
758
759 =item Using the system malloc
760
761 To build without perl's malloc, you can use the Configure command
762
763         sh Configure -Uusemymalloc
764
765 or you can answer 'n' at the appropriate interactive Configure prompt.
766
767 =item -DPERL_POLLUTE_MALLOC
768
769 NOTE: This flag is enabled automatically on some platforms if you
770 asked for binary compatibility with version 5.005, or if you just
771 run Configure to accept all the defaults on those platforms.  You
772 can refuse the automatic binary compatibility flags wholesale by
773 running:
774
775         sh Configure -Ubincompat5005
776
777 or by answering 'n' at the appropriate prompt.
778
779 Perl's malloc family of functions are called Perl_malloc(),
780 Perl_realloc(), Perl_calloc() and Perl_mfree().  When this flag is
781 not enabled, the names do not clash with the system versions of
782 these functions.
783
784 If enabled, Perl's malloc family of functions will have the same
785 names as the system versions.  This may be sometimes required when you
786 have libraries that like to free() data that may have been allocated
787 by Perl_malloc() and vice versa.
788
789 Note that enabling this option may sometimes lead to duplicate symbols
790 from the linker for malloc et al.  In such cases, the system probably
791 does not allow its malloc functions to be fully replaced with custom
792 versions.
793
794 =back
795
796 =head2 Building a debugging perl
797
798 You can run perl scripts under the perl debugger at any time with
799 B<perl -d your_script>.  If, however, you want to debug perl itself,
800 you probably want to do
801
802         sh Configure -Doptimize='-g'
803
804 This will do two independent things:  First, it will force compilation
805 to use cc -g so that you can use your system's debugger on the
806 executable.  (Note:  Your system may actually require something like
807 cc -g2.  Check your man pages for cc(1) and also any hint file for
808 your system.)  Second, it will add -DDEBUGGING to your ccflags
809 variable in config.sh so that you can use B<perl -D> to access perl's
810 internal state.  (Note: Configure will only add -DDEBUGGING by default
811 if you are not reusing your old config.sh.  If you want to reuse your
812 old config.sh, then you can just edit it and change the optimize and
813 ccflags variables by hand and then propagate your changes as shown in
814 L<"Propagating your changes to config.sh"> below.)
815
816 You can actually specify -g and -DDEBUGGING independently, but usually
817 it's convenient to have both.
818
819 If you are using a shared libperl, see the warnings about multiple
820 versions of perl under L<Building a shared libperl.so Perl library>.
821
822 =head2 Other Compiler Flags
823
824 For most users, all of the Configure defaults are fine.  However, you
825 can change a number of factors in the way perl is built by adding
826 appropriate -D directives to your ccflags variable in config.sh.
827
828 You should also run Configure interactively to verify that a hint file
829 doesn't inadvertently override your ccflags setting.  (Hints files
830 shouldn't do that, but some might.)
831
832 =head2 Extensions
833
834 By default, Configure will offer to build every extension which appears
835 to be supported.  For example, Configure will offer to build GDBM_File
836 only if it is able to find the gdbm library.  (See examples below.)
837 B, DynaLoader, Fcntl, IO, and attrs are always built by default.
838 Configure does not contain code to test for POSIX compliance, so POSIX
839 is always built by default as well.  If you wish to skip POSIX, you can
840 set the Configure variable useposix=false either in a hint file or from
841 the Configure command line.  Similarly, the Opcode extension is always
842 built by default, but you can skip it by setting the Configure variable
843 useopcode=false either in a hint file for from the command line.
844
845 You can learn more about each of these extensions by consulting the
846 documentation in the individual .pm modules, located under the
847 ext/ subdirectory.
848
849 Even if you do not have dynamic loading, you must still build the
850 DynaLoader extension; you should just build the stub dl_none.xs
851 version.  (Configure will suggest this as the default.)
852
853 In summary, here are the Configure command-line variables you can set
854 to turn off each extension:
855
856     B                   (Always included by default)
857     DB_File             i_db
858     DynaLoader          (Must always be included as a static extension)
859     Fcntl               (Always included by default)
860     GDBM_File           i_gdbm
861     IO                  (Always included by default)
862     NDBM_File           i_ndbm
863     ODBM_File           i_dbm
864     POSIX               useposix
865     SDBM_File           (Always included by default)
866     Opcode              useopcode
867     Socket              d_socket
868     Threads             usethreads
869     attrs               (Always included by default)
870
871 Thus to skip the NDBM_File extension, you can use
872
873         sh Configure -Ui_ndbm
874
875 Again, this is taken care of automatically if you don't have the ndbm
876 library.
877
878 Of course, you may always run Configure interactively and select only
879 the extensions you want.
880
881 Note:  The DB_File module will only work with version 1.x of Berkeley
882 DB or newer releases of version 2.  Configure will automatically detect
883 this for you and refuse to try to build DB_File with earlier
884 releases of version 2.
885
886 If you re-use your old config.sh but change your system (e.g. by
887 adding libgdbm) Configure will still offer your old choices of extensions
888 for the default answer, but it will also point out the discrepancy to
889 you.
890
891 Finally, if you have dynamic loading (most modern Unix systems do)
892 remember that these extensions do not increase the size of your perl
893 executable, nor do they impact start-up time, so you probably might as
894 well build all the ones that will work on your system.
895
896 =head2 Including locally-installed libraries
897
898 Perl5 comes with interfaces to number of database extensions, including
899 dbm, ndbm, gdbm, and Berkeley db.  For each extension, if
900 Configure can find the appropriate header files and libraries, it will
901 automatically include that extension.  The gdbm and db libraries
902 are not included with perl.  See the library documentation for
903 how to obtain the libraries.
904
905 If your database header (.h) files are not in a directory normally
906 searched by your C compiler, then you will need to include the
907 appropriate -I/your/directory option when prompted by Configure.  If
908 your database library (.a) files are not in a directory normally
909 searched by your C compiler and linker, then you will need to include
910 the appropriate -L/your/directory option when prompted by Configure.
911 See the examples below.
912
913 =head2 Examples
914
915 =over 4
916
917 =item gdbm in /usr/local
918
919 Suppose you have gdbm and want Configure to find it and build the
920 GDBM_File extension.  This example assumes you have gdbm.h
921 installed in /usr/local/include/gdbm.h and libgdbm.a installed in
922 /usr/local/lib/libgdbm.a.  Configure should figure all the
923 necessary steps out automatically.
924
925 Specifically, when Configure prompts you for flags for
926 your C compiler, you should include  -I/usr/local/include.
927
928 When Configure prompts you for linker flags, you should include
929 -L/usr/local/lib.
930
931 If you are using dynamic loading, then when Configure prompts you for
932 linker flags for dynamic loading, you should again include
933 -L/usr/local/lib.
934
935 Again, this should all happen automatically.  This should also work if
936 you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
937 /opt/gnu, /usr/GNU, or /opt/GNU).
938
939 =item gdbm in /usr/you
940
941 Suppose you have gdbm installed in some place other than /usr/local/,
942 but you still want Configure to find it.  To be specific, assume you
943 have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a.  You
944 still have to add -I/usr/you/include to cc flags, but you have to take
945 an extra step to help Configure find libgdbm.a.  Specifically, when
946 Configure prompts you for library directories, you have to add
947 /usr/you/lib to the list.
948
949 It is possible to specify this from the command line too (all on one
950 line):
951
952         sh Configure -de \
953                 -Dlocincpth="/usr/you/include" \
954                 -Dloclibpth="/usr/you/lib"
955
956 locincpth is a space-separated list of include directories to search.
957 Configure will automatically add the appropriate -I directives.
958
959 loclibpth is a space-separated list of library directories to search.
960 Configure will automatically add the appropriate -L directives.  If
961 you have some libraries under /usr/local/ and others under
962 /usr/you, then you have to include both, namely
963
964         sh Configure -de \
965                 -Dlocincpth="/usr/you/include /usr/local/include" \
966                 -Dloclibpth="/usr/you/lib /usr/local/lib"
967
968 =back
969
970 =head2 What if it doesn't work?
971
972 If you run into problems, try some of the following ideas.
973 If none of them help, then see L<"Reporting Problems"> below.
974
975 =over 4
976
977 =item Running Configure Interactively
978
979 If Configure runs into trouble, remember that you can always run
980 Configure interactively so that you can check (and correct) its
981 guesses.
982
983 All the installation questions have been moved to the top, so you don't
984 have to wait for them.  Once you've handled them (and your C compiler and
985 flags) you can type  &-d  at the next Configure prompt and Configure
986 will use the defaults from then on.
987
988 If you find yourself trying obscure command line incantations and
989 config.over tricks, I recommend you run Configure interactively
990 instead.  You'll probably save yourself time in the long run.
991
992 =item Hint files
993
994 The perl distribution includes a number of system-specific hints files
995 in the hints/ directory.  If one of them matches your system, Configure
996 will offer to use that hint file.
997
998 Several of the hint files contain additional important information.
999 If you have any problems, it is a good idea to read the relevant hint file
1000 for further information.  See hints/solaris_2.sh for an extensive example.
1001 More information about writing good hints is in the hints/README.hints
1002 file.
1003
1004 =item *** WHOA THERE!!! ***
1005
1006 Occasionally, Configure makes a wrong guess.  For example, on SunOS
1007 4.1.3, Configure incorrectly concludes that tzname[] is in the
1008 standard C library.  The hint file is set up to correct for this.  You
1009 will see a message:
1010
1011     *** WHOA THERE!!! ***
1012         The recommended value for $d_tzname on this machine was "undef"!
1013         Keep the recommended value? [y]
1014
1015 You should always keep the recommended value unless, after reading the
1016 relevant section of the hint file, you are sure you want to try
1017 overriding it.
1018
1019 If you are re-using an old config.sh, the word "previous" will be
1020 used instead of "recommended".  Again, you will almost always want
1021 to keep the previous value, unless you have changed something on your
1022 system.
1023
1024 For example, suppose you have added libgdbm.a to your system
1025 and you decide to reconfigure perl to use GDBM_File.  When you run
1026 Configure again, you will need to add -lgdbm to the list of libraries.
1027 Now, Configure will find your gdbm include file and library and will
1028 issue a message:
1029
1030     *** WHOA THERE!!! ***
1031         The previous value for $i_gdbm on this machine was "undef"!
1032         Keep the previous value? [y]
1033
1034 In this case, you do not want to keep the previous value, so you
1035 should answer 'n'.  (You'll also have to manually add GDBM_File to
1036 the list of dynamic extensions to build.)
1037
1038 =item Changing Compilers
1039
1040 If you change compilers or make other significant changes, you should
1041 probably not re-use your old config.sh.  Simply remove it or
1042 rename it, e.g. mv config.sh config.sh.old.  Then rerun Configure
1043 with the options you want to use.
1044
1045 This is a common source of problems.  If you change from cc to
1046 gcc, you should almost always remove your old config.sh.
1047
1048 =item Propagating your changes to config.sh
1049
1050 If you make any changes to config.sh, you should propagate
1051 them to all the .SH files by running
1052
1053         sh Configure -S
1054
1055 You will then have to rebuild by running
1056
1057         make depend
1058         make
1059
1060 =item config.over
1061
1062 You can also supply a shell script config.over to over-ride Configure's
1063 guesses.  It will get loaded up at the very end, just before config.sh
1064 is created.  You have to be careful with this, however, as Configure
1065 does no checking that your changes make sense.
1066
1067 =item config.h
1068
1069 Many of the system dependencies are contained in config.h.
1070 Configure builds config.h by running the config_h.SH script.
1071 The values for the variables are taken from config.sh.
1072
1073 If there are any problems, you can edit config.h directly.  Beware,
1074 though, that the next time you run Configure, your changes will be
1075 lost.
1076
1077 =item cflags
1078
1079 If you have any additional changes to make to the C compiler command
1080 line, they can be made in cflags.SH.  For instance, to turn off the
1081 optimizer on toke.c, find the line in the switch structure for
1082 toke.c and put the command optimize='-g' before the ;; .  You
1083 can also edit cflags directly, but beware that your changes will be
1084 lost the next time you run Configure.
1085
1086 To explore various ways of changing ccflags from within a hint file,
1087 see the file hints/README.hints.
1088
1089 To change the C flags for all the files, edit config.sh and change either
1090 $ccflags or $optimize, and then re-run
1091
1092         sh Configure -S
1093         make depend
1094
1095 =item No sh
1096
1097 If you don't have sh, you'll have to copy the sample file Porting/config_H
1098 to config.h and edit the config.h to reflect your system's peculiarities.
1099 You'll probably also have to extensively modify the extension building
1100 mechanism.
1101
1102 =item Environment variable clashes
1103
1104 Configure uses a CONFIG variable that is reported to cause trouble on
1105 ReliantUnix 5.44.  If your system sets this variable, you can try
1106 unsetting it before you run Configure.  Configure should eventually
1107 be fixed to avoid polluting the namespace of the environment.
1108
1109 =item Digital UNIX/Tru64 UNIX and BIN_SH
1110
1111 In Digital UNIX/Tru64 UNIX, Configure might abort with
1112
1113 Build a threading Perl? [n]
1114 Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
1115
1116 This indicates that Configure is being run with a broken Korn shell
1117 (even though you think you are using a Bourne shell by using
1118 "sh Configure" or "./Configure").  The Korn shell bug has been reported
1119 to Compaq as of February 1999 but in the meanwhile, the reason ksh is
1120 being used is that you have the environment variable BIN_SH set to
1121 'xpg4'.  This causes /bin/sh to delegate its duties to /bin/posix/sh
1122 (a ksh).  Unset the environment variable and rerun Configure.
1123
1124 =item HP-UX 11, pthreads, and libgdbm
1125
1126 If you are running Configure with -Dusethreads in HP-UX 11, be warned
1127 that POSIX threads and libgdbm (the GNU dbm library) compiled before
1128 HP-UX 11 do not mix.  This will cause a basic test run by Configure to
1129 fail
1130
1131 Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
1132 Return Pointer is 0xc082bf33
1133 sh: 5345 Quit(coredump)
1134
1135 and Configure will give up.  The cure is to recompile and install
1136 libgdbm under HP-UX 11.
1137
1138 =item Porting information
1139
1140 Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
1141 corresponding README files and subdirectories.  Additional information,
1142 including a glossary of all those config.sh variables, is in the Porting
1143 subdirectory.  Especially Porting/Glossary should come in handy. 
1144
1145 Ports for other systems may also be available.  You should check out
1146 http://www.perl.com/CPAN/ports for current information on ports to
1147 various other operating systems.
1148
1149 If you plan to port Perl to a new architecture study carefully the
1150 section titled "Philosophical Issues in Patching and Porting Perl"
1151 in the file Porting/pumpkin.pod and the file Porting/patching.pod.
1152 Study also how other non-UNIX ports have solved problems.
1153
1154 =back
1155
1156 =head1 make depend
1157
1158 This will look for all the includes.  The output is stored in makefile.
1159 The only difference between Makefile and makefile is the dependencies at
1160 the bottom of makefile.  If you have to make any changes, you should edit
1161 makefile, not Makefile since the Unix make command reads makefile first.
1162 (On non-Unix systems, the output may be stored in a different file.
1163 Check the value of $firstmakefile in your config.sh if in doubt.)
1164
1165 Configure will offer to do this step for you, so it isn't listed
1166 explicitly above.
1167
1168 =head1 make
1169
1170 This will attempt to make perl in the current directory.
1171
1172 =head2 What if it doesn't work?
1173
1174 If you can't compile successfully, try some of the following ideas.
1175 If none of them help, and careful reading of the error message and
1176 the relevant manual pages on your system doesn't help,
1177 then see L<"Reporting Problems"> below.
1178
1179 =over 4
1180
1181 =item hints
1182
1183 If you used a hint file, try reading the comments in the hint file
1184 for further tips and information.
1185
1186 =item extensions
1187
1188 If you can successfully build miniperl, but the process crashes
1189 during the building of extensions, you should run
1190
1191         make minitest
1192
1193 to test your version of miniperl.
1194
1195 =item locale
1196
1197 If you have any locale-related environment variables set, try unsetting
1198 them.  I have some reports that some versions of IRIX hang while
1199 running B<./miniperl configpm> with locales other than the C locale.
1200 See the discussion under L<"make test"> below about locales and the
1201 whole L<"Locale problems"> section in the file pod/perllocale.pod.
1202 The latter is especially useful if you see something like this
1203
1204         perl: warning: Setting locale failed.
1205         perl: warning: Please check that your locale settings:
1206                 LC_ALL = "En_US",
1207                 LANG = (unset)
1208             are supported and installed on your system.
1209         perl: warning: Falling back to the standard locale ("C").
1210
1211 at Perl startup.
1212
1213 =item varargs
1214
1215 If you get varargs problems with gcc, be sure that gcc is installed
1216 correctly and that you are not passing -I/usr/include to gcc.  When using
1217 gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1218 in config.sh.  The problem is usually solved by running fixincludes
1219 correctly.  If you do change config.sh, don't forget to propagate
1220 your changes (see L<"Propagating your changes to config.sh"> below).
1221 See also the L<"vsprintf"> item below.
1222
1223 =item util.c
1224
1225 If you get error messages such as the following (the exact line
1226 numbers and function name may vary in different versions of perl):
1227
1228     util.c: In function `Perl_form':
1229     util.c:1107: number of arguments doesn't match prototype
1230     proto.h:125: prototype declaration
1231
1232 it might well be a symptom of the gcc "varargs problem".  See the
1233 previous L<"varargs"> item.
1234
1235 =item Solaris and SunOS dynamic loading
1236
1237 If you have problems with dynamic loading using gcc on SunOS or
1238 Solaris, and you are using GNU as and GNU ld, you may need to add
1239 -B/bin/ (for SunOS) or -B/usr/ccs/bin/ (for Solaris) to your
1240 $ccflags, $ldflags, and $lddlflags so that the system's versions of as
1241 and ld are used.  Note that the trailing '/' is required.
1242 Alternatively, you can use the GCC_EXEC_PREFIX
1243 environment variable to ensure that Sun's as and ld are used.  Consult
1244 your gcc documentation for further information on the -B option and
1245 the GCC_EXEC_PREFIX variable.
1246
1247 One convenient way to ensure you are not using GNU as and ld is to
1248 invoke Configure with
1249
1250     sh Configure -Dcc='gcc -B/usr/ccs/bin/'
1251
1252 for Solaris systems.  For a SunOS system, you must use -B/bin/
1253 instead.
1254
1255 Alternatively, recent versions of GNU ld reportedly work if you
1256 include C<-Wl,-export-dynamic> in the ccdlflags variable in
1257 config.sh.
1258
1259 =item ld.so.1: ./perl: fatal: relocation error:
1260
1261 If you get this message on SunOS or Solaris, and you're using gcc,
1262 it's probably the GNU as or GNU ld problem in the previous item
1263 L<"Solaris and SunOS dynamic loading">.
1264
1265 =item LD_LIBRARY_PATH
1266
1267 If you run into dynamic loading problems, check your setting of
1268 the LD_LIBRARY_PATH environment variable.  If you're creating a static
1269 Perl library (libperl.a rather than libperl.so) it should build
1270 fine with LD_LIBRARY_PATH unset, though that may depend on details
1271 of your local set-up.
1272
1273 =item dlopen: stub interception failed
1274
1275 The primary cause of the 'dlopen: stub interception failed' message is
1276 that the LD_LIBRARY_PATH environment variable includes a directory
1277 which is a symlink to /usr/lib (such as /lib).
1278
1279 The reason this causes a problem is quite subtle.  The file libdl.so.1.0
1280 actually *only* contains functions which generate 'stub interception
1281 failed' errors!  The runtime linker intercepts links to
1282 "/usr/lib/libdl.so.1.0" and links in internal implementation of those
1283 functions instead.  [Thanks to Tim Bunce for this explanation.]
1284
1285 =item nm extraction
1286
1287 If Configure seems to be having trouble finding library functions,
1288 try not using nm extraction.  You can do this from the command line
1289 with
1290
1291         sh Configure -Uusenm
1292
1293 or by answering the nm extraction question interactively.
1294 If you have previously run Configure, you should not reuse your old
1295 config.sh.
1296
1297 =item umask not found
1298
1299 If the build processes encounters errors relating to umask(), the problem
1300 is probably that Configure couldn't find your umask() system call.
1301 Check your config.sh.  You should have d_umask='define'.  If you don't,
1302 this is probably the L<"nm extraction"> problem discussed above.  Also,
1303 try reading the hints file for your system for further information.
1304
1305 =item vsprintf
1306
1307 If you run into problems with vsprintf in compiling util.c, the
1308 problem is probably that Configure failed to detect your system's
1309 version of vsprintf().  Check whether your system has vprintf().
1310 (Virtually all modern Unix systems do.)  Then, check the variable
1311 d_vprintf in config.sh.  If your system has vprintf, it should be:
1312
1313         d_vprintf='define'
1314
1315 If Configure guessed wrong, it is likely that Configure guessed wrong
1316 on a number of other common functions too.  This is probably
1317 the L<"nm extraction"> problem discussed above.
1318
1319 =item do_aspawn
1320
1321 If you run into problems relating to do_aspawn or do_spawn, the
1322 problem is probably that Configure failed to detect your system's
1323 fork() function.  Follow the procedure in the previous item
1324 on L<"nm extraction">.
1325
1326 =item __inet_* errors
1327
1328 If you receive unresolved symbol errors during Perl build and/or test
1329 referring to __inet_* symbols, check to see whether BIND 8.1 is
1330 installed.  It installs a /usr/local/include/arpa/inet.h that refers to
1331 these symbols.  Versions of BIND later than 8.1 do not install inet.h
1332 in that location and avoid the errors.  You should probably update to a
1333 newer version of BIND.  If you can't, you can either link with the
1334 updated resolver library provided with BIND 8.1 or rename
1335 /usr/local/bin/arpa/inet.h during the Perl build and test process to
1336 avoid the problem.
1337
1338 =item #error "No DATAMODEL_NATIVE specified"
1339
1340 This is a common error when trying to build perl on Solaris 2.6 with a
1341 gcc installation from Solaris 2.5 or 2.5.1.  The Solaris header files
1342 changed, so you need to update your gcc installation.  You can either
1343 rerun the fixincludes script from gcc or take the opportunity to
1344 update your gcc installation.
1345
1346 =item Optimizer
1347
1348 If you can't compile successfully, try turning off your compiler's
1349 optimizer.  Edit config.sh and change the line
1350
1351         optimize='-O'
1352
1353 to
1354
1355         optimize=' '
1356
1357 then propagate your changes with B<sh Configure -S> and rebuild
1358 with B<make depend; make>.
1359
1360 =item CRIPPLED_CC
1361
1362 If you still can't compile successfully, try adding a -DCRIPPLED_CC
1363 flag.  (Just because you get no errors doesn't mean it compiled right!)
1364 This simplifies some complicated expressions for compilers that get
1365 indigestion easily.
1366
1367 =item Missing functions
1368
1369 If you have missing routines, you probably need to add some library or
1370 other, or you need to undefine some feature that Configure thought was
1371 there but is defective or incomplete.  Look through config.h for
1372 likely suspects.  If Configure guessed wrong on a number of functions,
1373 you might have the L<"nm extraction"> problem discussed above.
1374
1375 =item toke.c
1376
1377 Some compilers will not compile or optimize the larger files (such as
1378 toke.c) without some extra switches to use larger jump offsets or
1379 allocate larger internal tables.  You can customize the switches for
1380 each file in cflags.  It's okay to insert rules for specific files into
1381 makefile since a default rule only takes effect in the absence of a
1382 specific rule.
1383
1384 =item Missing dbmclose
1385
1386 SCO prior to 3.2.4 may be missing dbmclose().  An upgrade to 3.2.4
1387 that includes libdbm.nfs (which includes dbmclose()) may be available.
1388
1389 =item Note (probably harmless): No library found for -lsomething
1390
1391 If you see such a message during the building of an extension, but
1392 the extension passes its tests anyway (see L<"make test"> below),
1393 then don't worry about the warning message.  The extension
1394 Makefile.PL goes looking for various libraries needed on various
1395 systems; few systems will need all the possible libraries listed.
1396 For example, a system may have -lcposix or -lposix, but it's
1397 unlikely to have both, so most users will see warnings for the one
1398 they don't have.  The phrase 'probably harmless' is intended to
1399 reassure you that nothing unusual is happening, and the build
1400 process is continuing.
1401
1402 On the other hand, if you are building GDBM_File and you get the
1403 message
1404
1405     Note (probably harmless): No library found for -lgdbm
1406
1407 then it's likely you're going to run into trouble somewhere along
1408 the line, since it's hard to see how you can use the GDBM_File
1409 extension without the -lgdbm library.
1410
1411 It is true that, in principle, Configure could have figured all of
1412 this out, but Configure and the extension building process are not
1413 quite that tightly coordinated.
1414
1415 =item sh: ar: not found
1416
1417 This is a message from your shell telling you that the command 'ar'
1418 was not found.  You need to check your PATH environment variable to
1419 make sure that it includes the directory with the 'ar' command.  This
1420 is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
1421 directory.
1422
1423 =item db-recno failure on tests 51, 53 and 55
1424
1425 Old versions of the DB library (including the DB library which comes
1426 with FreeBSD 2.1) had broken handling of recno databases with modified
1427 bval settings.  Upgrade your DB library or OS.
1428
1429 =item Bad arg length for semctl, is XX, should be ZZZ
1430
1431 If you get this error message from the lib/ipc_sysv test, your System
1432 V IPC may be broken.  The XX typically is 20, and that is what ZZZ
1433 also should be.  Consider upgrading your OS, or reconfiguring your OS
1434 to include the System V semaphores.
1435
1436 =item lib/ipc_sysv........semget: No space left on device
1437
1438 Either your account or the whole system has run out of semaphores.  Or
1439 both.  Either list the semaphores with "ipcs" and remove the unneeded
1440 ones (which ones these are depends on your system and applications)
1441 with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1442 system.
1443
1444 =item GNU binutils
1445
1446 If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1447 tools you may be in for some trouble.  For example creating archives
1448 with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1449 may lead into linking problems.  Either recompile your GNU binutils
1450 under your current operating system release, or modify your PATH not
1451 to include the GNU utils before running Configure, or specify the
1452 vendor-supplied utilities explicitly to Configure, for example by
1453 Configure -Dar=/bin/ar.
1454
1455 =item Miscellaneous
1456
1457 Some additional things that have been reported for either perl4 or perl5:
1458
1459 Genix may need to use libc rather than libc_s, or #undef VARARGS.
1460
1461 NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1462
1463 UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
1464
1465 FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been
1466 configured to the kernel.  Perl tries to detect this, though, and
1467 you will get a message telling what to do.
1468
1469 If you get syntax errors on '(', try -DCRIPPLED_CC.
1470
1471 Machines with half-implemented dbm routines will need to #undef I_ODBM
1472
1473 HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
1474 Patch Bundle" has been reported to break the io/fs test #18 which
1475 tests whether utime() can change timestamps.  The Y2K patch seems to
1476 break utime() so that over NFS the timestamps do not get changed
1477 (on local filesystems utime() still works).
1478
1479 =back
1480
1481 =head1 make test
1482
1483 This will run the regression tests on the perl you just made.  If
1484 'make test' doesn't say "All tests successful" then something went
1485 wrong.  See the file t/README in the t subdirectory.
1486
1487 Note that you can't run the tests in background if this disables
1488 opening of /dev/tty. You can use 'make test-notty' in that case but
1489 a few tty tests will be skipped.
1490
1491 =head2 What if make test doesn't work?
1492
1493 If make test bombs out, just cd to the t directory and run ./TEST
1494 by hand to see if it makes any difference.  If individual tests
1495 bomb, you can run them by hand, e.g.,
1496
1497         ./perl op/groups.t
1498
1499 Another way to get more detailed information about failed tests and
1500 individual subtests is to cd to the t directory and run
1501
1502         ./perl harness
1503
1504 (this assumes that most basic tests succeed, since harness uses
1505 complicated constructs).
1506
1507 You should also read the individual tests to see if there are any helpful
1508 comments that apply to your system.
1509
1510 =over 4
1511
1512 =item locale
1513
1514 Note:  One possible reason for errors is that some external programs
1515 may be broken due to the combination of your environment and the way
1516 B<make test> exercises them.  For example, this may happen if you have
1517 one or more of these environment variables set:  LC_ALL LC_CTYPE
1518 LC_COLLATE LANG.  In some versions of UNIX, the non-English locales
1519 are known to cause programs to exhibit mysterious errors.
1520
1521 If you have any of the above environment variables set, please try
1522
1523         setenv LC_ALL C
1524
1525 (for C shell) or
1526
1527         LC_ALL=C;export LC_ALL
1528
1529 for Bourne or Korn shell) from the command line and then retry
1530 make test.  If the tests then succeed, you may have a broken program that
1531 is confusing the testing.  Please run the troublesome test by hand as
1532 shown above and see whether you can locate the program.  Look for
1533 things like:  exec, `backquoted command`, system, open("|...") or
1534 open("...|").  All these mean that Perl is trying to run some
1535 external program.
1536
1537 =item Out of memory
1538
1539 On some systems, particularly those with smaller amounts of RAM, some
1540 of the tests in t/op/pat.t may fail with an "Out of memory" message.
1541 Specifically, in perl5.004_64, tests 74 and 78 have been reported to
1542 fail on some systems.  On my SparcStation IPC with 8 MB of RAM, test 78
1543 will fail if the system is running any other significant tasks at the
1544 same time.
1545
1546 Try stopping other jobs on the system and then running the test by itself:
1547
1548         cd t; ./perl op/pat.t
1549
1550 to see if you have any better luck.  If your perl still fails this
1551 test, it does not necessarily mean you have a broken perl.  This test
1552 tries to exercise the regular expression subsystem quite thoroughly,
1553 and may well be far more demanding than your normal usage.
1554
1555 =back
1556
1557 =head1 make install
1558
1559 This will put perl into the public directory you specified to
1560 Configure; by default this is /usr/local/bin.  It will also try
1561 to put the man pages in a reasonable place.  It will not nroff the man
1562 pages, however.  You may need to be root to run B<make install>.  If you
1563 are not root, you must own the directories in question and you should
1564 ignore any messages about chown not working.
1565
1566 =head2 Installing perl under different names
1567
1568 If you want to install perl under a name other than "perl" (for example,
1569 when installing perl with special features enabled, such as debugging),
1570 indicate the alternate name on the "make install" line, such as:
1571
1572     make install PERLNAME=myperl
1573
1574 You can separately change the base used for versioned names (like
1575 "perl5.005") by setting PERLNAME_VERBASE, like
1576
1577     make install PERLNAME=perl5 PERLNAME_VERBASE=perl
1578
1579 This can be useful if you have to install perl as "perl5" (due to an
1580 ancient version in /usr/bin supplied by your vendor, eg).  Without this
1581 the versioned binary would be called "perl55.005".
1582
1583 =head2 Installed files
1584
1585 If you want to see exactly what will happen without installing
1586 anything, you can run
1587
1588         ./perl installperl -n
1589         ./perl installman -n
1590
1591 make install will install the following:
1592
1593         perl,
1594             perl5.nnn   where nnn is the current release number.  This
1595                         will be a link to perl.
1596         suidperl,
1597             sperl5.nnn  If you requested setuid emulation.
1598         a2p             awk-to-perl translator
1599         cppstdin        This is used by perl -P, if your cc -E can't
1600                         read from stdin.
1601         c2ph, pstruct   Scripts for handling C structures in header files.
1602         s2p             sed-to-perl translator
1603         find2perl       find-to-perl translator
1604         h2ph            Extract constants and simple macros from C headers
1605         h2xs            Converts C .h header files to Perl extensions.
1606         perlbug         Tool to report bugs in Perl.
1607         perldoc         Tool to read perl's pod documentation.
1608         pl2pm           Convert Perl 4 .pl files to Perl 5 .pm modules
1609         pod2html,       Converters from perl's pod documentation format
1610         pod2latex,      to other useful formats.
1611         pod2man, and
1612         pod2text
1613         splain          Describe Perl warnings and errors
1614         dprofpp         Perl code profile post-processor
1615
1616         library files   in $privlib and $archlib specified to
1617                         Configure, usually under /usr/local/lib/perl5/.
1618         man pages       in $man1dir, usually /usr/local/man/man1.
1619         module man
1620         pages           in $man3dir, usually /usr/local/man/man3.
1621         pod/*.pod       in $privlib/pod/.
1622
1623 Installperl will also create the directories listed above
1624 in L<"Installation Directories">.
1625
1626 Perl's *.h header files and the libperl.a library are also installed
1627 under $archlib so that any user may later build new modules, run the
1628 optional Perl compiler, or embed the perl interpreter into another
1629 program even if the Perl source is no longer available.
1630
1631 =head1 Coexistence with earlier versions of perl5
1632
1633 In general, you can usually safely upgrade from one version of Perl (e.g.
1634 5.004_04) to another similar version (e.g. 5.004_05) without re-compiling
1635 all of your add-on extensions.  You can also safely leave the old version
1636 around in case the new version causes you problems for some reason.
1637 For example, if you want to be sure that your script continues to run
1638 with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
1639 top of the script with the particular version you want to run, e.g.
1640 #!/usr/local/bin/perl5.00404.
1641
1642 Most extensions will probably not need to be recompiled to use
1643 with a newer version of perl.   Here is how it is supposed to work.
1644 (These examples assume you accept all the Configure defaults.)
1645
1646 Suppose you already have version 5.005_03 installed.  The directories
1647 searched by 5.005_03 are
1648
1649         /usr/local/lib/perl5/5.00503/$archname
1650         /usr/local/lib/perl5/5.00503
1651         /usr/local/lib/perl5/site_perl/5.005/$archname
1652         /usr/local/lib/perl5/site_perl/5.005
1653
1654 Now, suppose you install version 5.6.  The directories searched by
1655 version 5.6 will be
1656
1657         /usr/local/lib/perl5/5.6/$archname
1658         /usr/local/lib/perl5/5.6
1659         /usr/local/lib/perl5/site_perl/5.6/$archname
1660         /usr/local/lib/perl5/site_perl/5.6
1661
1662         /usr/local/lib/perl5/site_perl/5.005/$archname
1663         /usr/local/lib/perl5/site_perl/5.005
1664
1665 Notice the last two entries -- Perl understands the default structure
1666 of the $sitelib directories and will look back in older, compatible
1667 directories.  This way, modules installed under 5.005_03 will continue
1668 to be usable by 5.005_03 but will also accessible to 5.6.  Further,
1669 suppose that you upgrade a module to one which requires features
1670 present only in 5.6.  That new module will get installed into
1671 /usr/local/lib/perl5/site_perl/5.6 and will be available to 5.6,
1672 but will not interfere with the 5.005_03 version.
1673
1674 Also, by default, 5.6 will look in
1675
1676         /usr/local/lib/perl5/site_perl/
1677
1678 for 5.004-era pure perl modules.
1679
1680 Lastly, suppose you now install version 5.6.1.  The directories
1681 searched by 5.6.1 will be
1682
1683         /usr/local/lib/perl5/5.6.1/$archname
1684         /usr/local/lib/perl5/5.6.1
1685         /usr/local/lib/perl5/site_perl/5.6/$archname
1686         /usr/local/lib/perl5/site_perl/5.6
1687
1688         /usr/local/lib/perl5/site_perl/5.005/$archname
1689         /usr/local/lib/perl5/site_perl/5.005
1690         /usr/local/lib/perl5/site_perl/
1691
1692 When you install an add-on extension, it gets installed into $sitelib (or
1693 $sitearch if it is architecture-specific).  This directory deliberately
1694 does NOT include the sub-version number (01) so that both 5.6 and
1695 5.6.1 can use the extension.
1696
1697 However, if you do run into problems, and you want to continue to use the
1698 old version of perl along with your extension, move those extension files
1699 to the appropriate version directory, such as $privlib (or $archlib).
1700 (The extension's .packlist file lists the files installed with that
1701 extension.  For the Tk extension, for example, the list of files installed
1702 is in $sitearch/auto/Tk/.packlist.)  Then use your newer version of perl
1703 to rebuild and re-install the extension into $sitelib.  This way, Perl
1704 5.6 will find your files in the 5.6 directory, and newer versions
1705 of perl will find your newer extension in the $sitelib directory.
1706 (This is also why perl searches the site-specific libraries last.)
1707
1708 Alternatively, if you are willing to reinstall all your modules
1709 every time you upgrade perl, then you can include the subversion
1710 number in $sitearch and $sitelib when you run Configure.
1711
1712 =head2 Maintaining completely separate versions
1713
1714 Many users prefer to keep all versions of perl in completely
1715 separate directories.  This guarantees that an update to one version
1716 won't interfere with another version.  One convenient way to do this
1717 is by using a separate prefix for each version, such as
1718
1719         sh Configure -Dprefix=/opt/perl5.004
1720
1721 and adding /opt/perl5.004/bin to the shell PATH variable.  Such users
1722 may also wish to add a symbolic link /usr/local/bin/perl so that
1723 scripts can still start with #!/usr/local/bin/perl.
1724
1725 Others might share a common directory for maintenance sub-versions
1726 (e.g. 5.004 for all 5.004_0x versions), but change directory with
1727 each major version.
1728
1729 If you are installing a development subversion, you probably ought to
1730 seriously consider using a separate directory, since development
1731 subversions may not have all the compatibility wrinkles ironed out
1732 yet.
1733
1734 =head2 Upgrading from 5.005 to 5.6
1735
1736 Extensions built and installed with versions of perl prior to 5.005_50
1737 will need to be recompiled to be used with 5.005_50 and later.  You will,
1738 however, be able to continue using 5.005 even after you install 5.6.
1739 The 5.005 binary will still be able to find the modules built under
1740 5.005; the 5.6 binary will look in the new $sitearch and $sitelib
1741 directories, and will not find them.  See also your installed copy
1742 of the perllocal.pod file for a (possibly incomplete) list of locally
1743 installed modules.  Note that you want perllocal.pod not perllocale.pod
1744 for installed module information.
1745
1746 =head1 Coexistence with perl4
1747
1748 You can safely install perl5 even if you want to keep perl4 around.
1749
1750 By default, the perl5 libraries go into /usr/local/lib/perl5/, so
1751 they don't override the perl4 libraries in /usr/local/lib/perl/.
1752
1753 In your /usr/local/bin directory, you should have a binary named
1754 perl4.036.  That will not be touched by the perl5 installation
1755 process.  Most perl4 scripts should run just fine under perl5.
1756 However, if you have any scripts that require perl4, you can replace
1757 the #! line at the top of them by #!/usr/local/bin/perl4.036 (or
1758 whatever the appropriate pathname is).  See pod/perltrap.pod for
1759 possible problems running perl4 scripts under perl5.
1760
1761 =head1 cd /usr/include; h2ph *.h sys/*.h
1762
1763 Some perl scripts need to be able to obtain information from the
1764 system header files.  This command will convert the most commonly used
1765 header files in /usr/include into files that can be easily interpreted
1766 by perl.  These files will be placed in the architecture-dependent
1767 library ($archlib) directory you specified to Configure.
1768
1769 Note:  Due to differences in the C and perl languages, the conversion
1770 of the header files is not perfect.  You will probably have to
1771 hand-edit some of the converted files to get them to parse correctly.
1772 For example, h2ph breaks spectacularly on type casting and certain
1773 structures.
1774
1775 =head1 installhtml --help
1776
1777 Some sites may wish to make perl documentation available in HTML
1778 format.  The installhtml utility can be used to convert pod
1779 documentation into linked HTML files and install them.
1780
1781 Currently, the supplied ./installhtml script does not make use of the
1782 html Configure variables.  This should be fixed in a future release.
1783
1784 The following command-line is an example of one used to convert
1785 perl documentation:
1786
1787   ./installhtml                   \
1788       --podroot=.                 \
1789       --podpath=lib:ext:pod:vms   \
1790       --recurse                   \
1791       --htmldir=/perl/nmanual     \
1792       --htmlroot=/perl/nmanual    \
1793       --splithead=pod/perlipc     \
1794       --splititem=pod/perlfunc    \
1795       --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
1796       --verbose
1797
1798 See the documentation in installhtml for more details.  It can take
1799 many minutes to execute a large installation and you should expect to
1800 see warnings like "no title", "unexpected directive" and "cannot
1801 resolve" as the files are processed. We are aware of these problems
1802 (and would welcome patches for them).
1803
1804 You may find it helpful to run installhtml twice. That should reduce
1805 the number of "cannot resolve" warnings.
1806
1807 =head1 cd pod && make tex && (process the latex files)
1808
1809 Some sites may also wish to make the documentation in the pod/ directory
1810 available in TeX format.  Type
1811
1812         (cd pod && make tex && <process the latex files>)
1813
1814 =head1 Reporting Problems
1815
1816 If you have difficulty building perl, and none of the advice in this file
1817 helps, and careful reading of the error message and the relevant manual
1818 pages on your system doesn't help either, then you should send a message
1819 to either the comp.lang.perl.misc newsgroup or to perlbug@perl.com with
1820 an accurate description of your problem.
1821
1822 Please include the output of the ./myconfig shell script that comes with
1823 the distribution.  Alternatively, you can use the perlbug program that
1824 comes with the perl distribution, but you need to have perl compiled
1825 before you can use it.  (If you have not installed it yet, you need to
1826 run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
1827
1828 Please try to make your message brief but clear.  Trim out unnecessary
1829 information.  Do not include large files (such as config.sh or a complete
1830 Configure or make log) unless absolutely necessary.  Do not include a
1831 complete transcript of your build session.  Just include the failing
1832 commands, the relevant error messages, and whatever preceding commands
1833 are necessary to give the appropriate context.  Plain text should
1834 usually be sufficient--fancy attachments or encodings may actually
1835 reduce the number of people who read your message.  Your message
1836 will get relayed to over 400 subscribers around the world so please
1837 try to keep it brief but clear.
1838
1839 =head1 DOCUMENTATION
1840
1841 Read the manual entries before running perl.  The main documentation
1842 is in the pod/ subdirectory and should have been installed during the
1843 build process.  Type B<man perl> to get started.  Alternatively, you
1844 can type B<perldoc perl> to use the supplied perldoc script.  This is
1845 sometimes useful for finding things in the library modules.
1846
1847 Under UNIX, you can produce a documentation book in postscript form,
1848 along with its table of contents, by going to the pod/ subdirectory and
1849 running (either):
1850
1851         ./roffitall -groff              # If you have GNU groff installed
1852         ./roffitall -psroff             # If you have psroff
1853
1854 This will leave you with two postscript files ready to be printed.
1855 (You may need to fix the roffitall command to use your local troff
1856 set-up.)
1857
1858 Note that you must have performed the installation already before running
1859 the above, since the script collects the installed files to generate
1860 the documentation.
1861
1862 =head1 AUTHOR
1863
1864 Original author:  Andy Dougherty doughera@lafayette.edu , borrowing very
1865 heavily from the original README by Larry Wall, with lots of helpful
1866 feedback and additions from the perl5-porters@perl.org folks.
1867
1868 If you have problems, corrections, or questions, please see
1869 L<"Reporting Problems"> above.
1870
1871 =head1 REDISTRIBUTION
1872
1873 This document is part of the Perl package and may be distributed under
1874 the same terms as perl itself, with the following additional request:
1875 If you are distributing a modified version of perl (perhaps as part of
1876 a larger package) please B<do> modify these installation instructions
1877 and the contact information to match your distribution.
1878
1879 =head1 LAST MODIFIED
1880
1881 $Id: INSTALL,v 1.58 1999/07/23 14:43:00 doughera Exp $