3 Install - Build and Installation guide for perl5.
7 First, make sure you are installing an up-to-date version of Perl. If
8 you didn't get your Perl source from CPAN, check the latest version at
9 <URL:http://www.cpan.org/src/>.
11 The basic steps to build and install perl5 on a Unix system
12 with all the defaults are:
14 rm -f config.sh Policy.sh
20 # You may also wish to add these:
21 (cd /usr/include && h2ph *.h sys/*.h)
23 (cd pod && make tex && <process the latex files>)
25 Each of these is explained in further detail below.
27 B<NOTE>: starting from the release 5.6.0, Perl uses a version
28 scheme where even-numbered subreleases (like 5.6 and 5.8) are stable
29 maintenance releases and odd-numbered subreleases (like 5.7 and 5.9) are
30 unstable development releases. Development releases should not be
31 used in production environments. Fixes and new features are first
32 carefully tested in development releases and only if they prove
33 themselves to be worthy will they be migrated to the maintenance
36 The above commands will install Perl to /usr/local (or some other
37 platform-specific directory -- see the appropriate file in hints/.)
38 If that's not okay with you, use
40 rm -f config.sh Policy.sh
46 For information on non-Unix systems, see the section on L<"Porting
49 If "make install" just says "`install' is up to date" or something
50 similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
51 and you should say "make install-all". (This confusion is brought to you
52 by the Perl distribution having a file called INSTALL.)
54 If you have problems, corrections, or questions, please see
55 L<"Reporting Problems"> below.
57 For information on what's new in this release, see the
58 pod/perldelta.pod file. For more detailed information about specific
59 changes, see the Changes file.
63 This document is written in pod format as an easy way to indicate its
64 structure. The pod format is described in pod/perlpod.pod, but you can
65 read it as is with any pager or editor. Headings and items are marked
66 by lines beginning with '='. The other mark-up used is
68 B<text> embolden text, used for switches, programs or commands
70 L<name> A link (cross reference) to name
72 Although most of the defaults are probably fine for most users,
73 you should probably at least skim through this entire document before
76 If you're building Perl on a non-Unix system, you should also read
77 the README file specific to your operating system, since this may
78 provide additional or different instructions for building Perl. There
79 are also README files for several flavors of Unix systems, such as
80 Solaris, HP-UX, and AIX; if you have one of those systems, you should
81 also read the README file specific to that system.
83 If there is a hint file for your system (in the hints/ directory) you
84 should also read that hint file for specific information for your
85 system. (Unixware users should use the svr4.sh or the svr5.sh hint file.)
86 Additional information is in the Porting/ directory.
88 =head1 WARNING: This version requires an extra step to build old extensions.
90 5.005_53 and later releases do not export unadorned
91 global symbols anymore. This means you may need to build rather old
92 extensions that have not been updated for the current naming convention
95 perl Makefile.PL POLLUTE=1
97 Alternatively, you can enable CPP symbol pollution wholesale by
98 building perl itself with:
100 sh Configure -Accflags=-DPERL_POLLUTE
102 pod/perl56delta.pod contains more details about this.
104 =head1 WARNING: This version is not binary compatible with releases of
107 If you have built extensions (i.e. modules that include C code)
108 using an earlier version of Perl, you will need to rebuild and reinstall
111 Pure perl modules without XS or C code should continue to work fine
112 without reinstallation. See the discussions below on
113 L<"Coexistence with earlier versions of perl5"> and
114 L<"Upgrading from 5.005 or 5.6 to 5.8.0"> for more details.
116 The standard extensions supplied with Perl will be handled automatically.
118 On a related issue, old modules may possibly be affected by the
119 changes in the Perl language in the current release. Please see
120 pod/perldelta.pod (and the earlier pod/perl5Xdelta.pod) for a description of
121 what's changed. See your installed copy of the perllocal.pod
122 file for a (possibly incomplete) list of locally installed modules.
123 Also see CPAN::autobundle for one way to make a "bundle" of your
124 currently installed modules.
126 =head1 WARNING: This version requires a compiler that supports ANSI C.
128 Most C compilers are now ANSI-compliant. However, a few current
129 computers are delivered with an older C compiler expressly for
130 rebuilding the system kernel, or for some other historical reason.
131 Alternatively, you may have an old machine which was shipped before
132 ANSI compliance became widespread. Such compilers are not suitable
135 If you find that your default C compiler is not ANSI-capable, but you
136 know that an ANSI-capable compiler is installed on your system, you
137 can tell F<Configure> to use the correct compiler by means of the
138 C<-Dcc=> command-line option -- see L<"gcc">.
140 If do not have an ANSI-capable compiler there are a couple of avenues
147 You may try obtaining GCC, available from GNU mirrors worldwide,
148 listed at <URL:http://www.gnu.org/order/ftp.html>. If, rather than
149 building gcc from source code, you locate a binary version configured
150 for your platform, be sure that it is compiled for the version of the
151 operating system that you are using.
155 You may purchase a commercial ANSI C compiler from your system
156 supplier or elsewhere. (Or your organization may already have
157 licensed such software -- ask your colleagues to find out how to
158 access it.) If there is a README file for your system in the Perl
159 distribution (for example, F<README.hpux>), it may contain advice on
164 Although Perl can be compiled using a C++ compiler, the Configure script
165 does not work with some C++ compilers.
167 =head1 Space Requirements
169 The complete perl5 source tree takes up about 60 MB of disk space.
170 After completing make, it takes up roughly 100 MB, though the actual
171 total is likely to be quite system-dependent. The installation
172 directories need something on the order of 45 MB, though again that
173 value is system-dependent. A perl build with debug symbols and
174 -DDEBUGGING will require something on the order of 10 MB extra.
176 =head1 Start with a Fresh Distribution
178 If you have built perl before, you should clean out the build directory
187 The only difference between the two is that make distclean also removes
188 your old config.sh and Policy.sh files.
190 The results of a Configure run are stored in the config.sh and Policy.sh
191 files. If you are upgrading from a previous version of perl, or if you
192 change systems or compilers or make other significant changes, or if
193 you are experiencing difficulties building perl, you should probably
194 not re-use your old config.sh. Simply remove it
198 If you wish to use your old config.sh, be especially attentive to the
199 version and architecture-specific questions and answers. For example,
200 the default directory for architecture-dependent library modules
201 includes the version name. By default, Configure will reuse your old
202 name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
203 Configure for a different version, e.g. 5.004. Yes, Configure should
204 probably check and correct for this, but it doesn't.
205 Similarly, if you used a shared libperl.so (see below) with version
206 numbers, you will probably want to adjust them as well.
208 Also, be careful to check your architecture name. For example, some
209 Linux distributions use i386, while others may use i486. If you build
210 it yourself, Configure uses the output of the arch command, which
211 might be i586 or i686 instead. If you pick up a precompiled binary, or
212 compile extensions on different systems, they might not all agree on
213 the architecture name.
215 In short, if you wish to use your old config.sh, I recommend running
216 Configure interactively rather than blindly accepting the defaults.
218 If your reason to reuse your old config.sh is to save your particular
219 installation choices, then you can probably achieve the same effect by
220 using the Policy.sh file. See the section on L<"Site-wide Policy
221 settings"> below. If you wish to start with a fresh distribution, you
222 also need to remove any old Policy.sh files you may have with
228 Configure will figure out various things about your system. Some
229 things Configure will figure out for itself, other things it will ask
230 you about. To accept the default, just press RETURN. The default is
231 almost always okay. It is normal for some things to be "NOT found",
232 since Configure often searches for many different ways of performing
235 At any Configure prompt, you can type &-d and Configure will use the
236 defaults from then on.
238 After it runs, Configure will perform variable substitution on all the
239 *.SH files and offer to run make depend.
241 =head2 Disabling older versions of Perl
243 Configure will search for binary compatible versions of previously
244 installed perl binaries in the tree that is specified as target tree
245 and these will be used by the perl being built.
247 To disable use of older perl modules, even completely valid pure perl
248 modules, you can specify to not include the pathes found:
250 sh Configure -Dinc_version_list=none ...
252 When using the newer perl, you can add these pathes again in the
253 $PERL5LIB environment variable or with perl's -I runtime option.
255 =head2 Altering config.sh variables for C compiler switches etc.
257 For most users, all of the Configure defaults are fine. Configure
258 also has several convenient options which are described below.
259 However, if Configure doesn't have an option to do what you want,
260 you can change Configure variables after the platform hints have been
261 run, by using Configure's -A switch. For example, here's how to add
262 a couple of extra flags to C compiler invocations:
264 sh Configure -Accflags="-DPERL_Y2KWARN -DPERL_POLLUTE_MALLOC"
266 For more help on Configure switches, run:
270 =head2 Building Perl outside of the source directory
272 Sometimes it is desirable to build Perl in a directory different from
273 where the sources are, for example if you want to keep your sources
274 read-only, or if you want to share the sources between different binary
275 architectures. You can do this (if your file system supports symbolic
278 mkdir /tmp/perl/build/directory
279 cd /tmp/perl/build/directory
280 sh /path/to/perl/source/Configure -Dmksymlinks ...
282 This will create in /tmp/perl/build/directory a tree of symbolic links
283 pointing to files in /path/to/perl/source. The original files are left
284 unaffected. After Configure has finished you can just say
288 and Perl will be built and tested, all in /tmp/perl/build/directory.
290 =head2 Common Configure options
292 Configure supports a number of useful options. Run B<Configure -h> to
293 get a listing. See the Porting/Glossary file for a complete list of
294 Configure variables you can set and their definitions.
300 To compile with gcc you should run
302 sh Configure -Dcc=gcc
304 This is the preferred way to specify gcc (or another alternative
305 compiler) so that the hints files can set appropriate defaults.
307 =item Installation prefix
309 By default, for most systems, perl will be installed in
310 /usr/local/{bin, lib, man}. (See L<"Installation Directories">
311 and L<"Coexistence with earlier versions of perl5"> below for
314 You can specify a different 'prefix' for the default installation
315 directory, when Configure prompts you or by using the Configure command
316 line option -Dprefix='/some/directory', e.g.
318 sh Configure -Dprefix=/opt/perl
320 If your prefix contains the string "perl", then the suggested
321 directory structure is simplified. For example, if you use
322 prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
323 /opt/perl/lib/perl5/. Again, see L<"Installation Directories"> below
324 for more details. Do not include a trailing slash, (i.e. /opt/perl/)
325 or you may experience odd test failures.
327 NOTE: You must not specify an installation directory that is the same
328 as or below your perl source directory. If you do, installperl will
329 attempt infinite recursion.
333 It may seem obvious, but Perl is useful only when users can easily
334 find it. It's often a good idea to have both /usr/bin/perl and
335 /usr/local/bin/perl be symlinks to the actual binary. Be especially
336 careful, however, not to overwrite a version of perl supplied by your
337 vendor unless you are sure you know what you are doing. If you insist
338 on replacing your vendor's perl, useful information on how it was
339 configured may be found with
343 (Check the output carefully, however, since this doesn't preserve
344 spaces in arguments to Configure. For that, you have to look
345 carefully at config_arg1, config_arg2, etc.)
347 By default, Configure will not try to link /usr/bin/perl to
348 the current version of perl. You can turn on that behavior by running
350 Configure -Dinstallusrbinperl
352 or by answering 'yes' to the appropriate Configure prompt.
353 (Note that before perl 5.8.1, the default behavior was to create
354 or overwrite /usr/bin/perl even if it already existed.)
356 In any case, system administrators are strongly encouraged to
357 put (symlinks to) perl and its accompanying utilities, such as perldoc,
358 into a directory typically found along a user's PATH, or in another
359 obvious and convenient place.
361 =item Overriding an old config.sh
363 If you want to use your old config.sh but override some of the items
364 with command line options, you need to use B<Configure -O>.
368 If you are willing to accept all the defaults, and you want terse
373 Note: for development releases (odd subreleases, like 5.9, as opposed
374 to maintenance releases which have even subreleases, like 5.6 and 5.8)
375 if you want to use Configure -d, you will also need to supply -Dusedevel
376 to Configure, because the default answer to the question "do you really
377 want to Configure a development version?" is "no". The -Dusedevel
378 skips that sanity check.
380 For example for my Solaris system, I usually use
382 sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
384 =head2 GNU-style configure
386 If you prefer the GNU-style configure command line interface, you can
387 use the supplied configure.gnu command, e.g.
389 CC=gcc ./configure.gnu
391 The configure.gnu script emulates a few of the more common configure
394 ./configure.gnu --help
398 (The file is called configure.gnu to avoid problems on systems
399 that would not distinguish the files "Configure" and "configure".)
401 See L<Cross-compilation> below for information on cross-compiling.
403 =head2 Installation Directories
405 The installation directories can all be changed by answering the
406 appropriate questions in Configure. For convenience, all the
407 installation questions are near the beginning of Configure.
408 Do not include trailing slashes on directory names.
410 I highly recommend running Configure interactively to be sure it puts
411 everything where you want it. At any point during the Configure
412 process, you can answer a question with &-d and Configure will use
413 the defaults from then on. Alternatively, you can
415 grep '^install' config.sh
417 after Configure has run to verify the installation paths.
419 The defaults are intended to be reasonable and sensible for most
420 people building from sources. Those who build and distribute binary
421 distributions or who export perl to a range of systems will probably
422 need to alter them. If you are content to just accept the defaults,
423 you can safely skip the next section.
425 The directories set up by Configure fall into three broad categories.
429 =item Directories for the perl distribution
431 By default, Configure will use the following directories for 5.9.0.
432 $version is the full perl version number, including subversion, e.g.
433 5.9.0 or 5.9.1, and $archname is a string like sun4-sunos,
434 determined by Configure. The full definitions of all Configure
435 variables are in the file Porting/Glossary.
437 Configure variable Default value
440 $scriptdir $prefix/bin
441 $privlib $prefix/lib/perl5/$version
442 $archlib $prefix/lib/perl5/$version/$archname
443 $man1dir $prefix/man/man1
444 $man3dir $prefix/man/man3
448 Actually, Configure recognizes the SVR3-style
449 /usr/local/man/l_man/man1 directories, if present, and uses those
450 instead. Also, if $prefix contains the string "perl", the library
451 directories are simplified as described below. For simplicity, only
452 the common style is shown here.
454 =item Directories for site-specific add-on files
456 After perl is installed, you may later wish to add modules (e.g. from
457 CPAN) or scripts. Configure will set up the following directories to
458 be used for installing those add-on modules and scripts.
460 Configure variable Default value
462 $sitebin $siteprefix/bin
463 $sitescript $siteprefix/bin
464 $sitelib $siteprefix/lib/perl5/site_perl/$version
465 $sitearch $siteprefix/lib/perl5/site_perl/$version/$archname
466 $siteman1dir $siteprefix/man/man1
467 $siteman3dir $siteprefix/man/man3
471 By default, ExtUtils::MakeMaker will install architecture-independent
472 modules into $sitelib and architecture-dependent modules into $sitearch.
474 =item Directories for vendor-supplied add-on files
476 Lastly, if you are building a binary distribution of perl for
477 distribution, Configure can optionally set up the following directories
478 for you to use to distribute add-on modules.
480 Configure variable Default value
482 (The next ones are set only if vendorprefix is set.)
483 $vendorbin $vendorprefix/bin
484 $vendorscript $vendorprefix/bin
485 $vendorlib $vendorprefix/lib/perl5/vendor_perl/$version
486 $vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname
487 $vendorman1dir $vendorprefix/man/man1
488 $vendorman3dir $vendorprefix/man/man3
489 $vendorhtml1dir (none)
490 $vendorhtml3dir (none)
492 These are normally empty, but may be set as needed. For example,
493 a vendor might choose the following settings:
496 $siteprefix /usr/local
499 This would have the effect of setting the following:
503 $privlib /usr/lib/perl5/$version
504 $archlib /usr/lib/perl5/$version/$archname
505 $man1dir /usr/man/man1
506 $man3dir /usr/man/man3
508 $sitebin /usr/local/bin
509 $sitescript /usr/local/bin
510 $sitelib /usr/local/lib/perl5/site_perl/$version
511 $sitearch /usr/local/lib/perl5/site_perl/$version/$archname
512 $siteman1dir /usr/local/man/man1
513 $siteman3dir /usr/local/man/man3
516 $vendorscript /usr/bin
517 $vendorlib /usr/lib/perl5/vendor_perl/$version
518 $vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
519 $vendorman1dir /usr/man/man1
520 $vendorman3dir /usr/man/man3
522 Note how in this example, the vendor-supplied directories are in the
523 /usr hierarchy, while the directories reserved for the end-user are in
524 the /usr/local hierarchy.
526 The entire installed library hierarchy is installed in locations with
527 version numbers, keeping the installations of different versions distinct.
528 However, later installations of Perl can still be configured to search the
529 installed libraries corresponding to compatible earlier versions.
530 See L<"Coexistence with earlier versions of perl5"> below for more details
531 on how Perl can be made to search older version directories.
533 Of course you may use these directories however you see fit. For
534 example, you may wish to use $siteprefix for site-specific files that
535 are stored locally on your own disk and use $vendorprefix for
536 site-specific files that are stored elsewhere on your organization's
537 network. One way to do that would be something like
539 sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
543 As a final catch-all, Configure also offers an $otherlibdirs
544 variable. This variable contains a colon-separated list of additional
545 directories to add to @INC. By default, it will be empty.
546 Perl will search these directories (including architecture and
547 version-specific subdirectories) for add-on modules and extensions.
549 For example, if you have a bundle of perl libraries from a previous
550 installation, perhaps in a strange place:
552 Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
556 There is one other way of adding paths to @INC at perl build time, and
557 that is by setting the APPLLIB_EXP C pre-processor token to a colon-
558 separated list of directories, like this
560 sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
562 The directories defined by APPLLIB_EXP get added to @INC I<first>,
563 ahead of any others, and so provide a way to override the standard perl
564 modules should you, for example, want to distribute fixes without
565 touching the perl distribution proper. And, like otherlib dirs,
566 version and architecture specific subdirectories are also searched, if
567 present, at run time. Of course, you can still search other @INC
568 directories ahead of those in APPLLIB_EXP by using any of the standard
569 run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
573 In versions 5.005_57 and earlier, the default was to store module man
574 pages in a version-specific directory, such as
575 /usr/local/lib/perl5/$version/man/man3. The default for 5.005_58 and
576 after is /usr/local/man/man3 so that most users can find the man pages
577 without resetting MANPATH.
579 You can continue to use the old default from the command line with
581 sh Configure -Dman3dir=/usr/local/lib/perl5/5.9.0/man/man3
583 Some users also prefer to use a .3pm suffix. You can do that with
585 sh Configure -Dman3ext=3pm
587 Again, these are just the defaults, and can be changed as you run
592 Currently, the standard perl installation does not do anything with
593 HTML documentation, but that may change in the future. Further, some
594 add-on modules may wish to install HTML documents. The html Configure
595 variables listed above are provided if you wish to specify where such
596 documents should be placed. The default is "none", but will likely
597 eventually change to something useful based on user feedback.
601 Some users prefer to append a "/share" to $privlib and $sitelib
602 to emphasize that those directories can be shared among different
605 Note that these are just the defaults. You can actually structure the
606 directories any way you like. They don't even have to be on the same
609 Further details about the installation directories, maintenance and
610 development subversions, and about supporting multiple versions are
611 discussed in L<"Coexistence with earlier versions of perl5"> below.
613 If you specify a prefix that contains the string "perl", then the
614 library directory structure is slightly simplified. Instead of
615 suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
617 Thus, for example, if you Configure with
618 -Dprefix=/opt/perl, then the default library directories for 5.9.0 are
620 Configure variable Default value
621 $privlib /opt/perl/lib/5.9.0
622 $archlib /opt/perl/lib/5.9.0/$archname
623 $sitelib /opt/perl/lib/site_perl/5.9.0
624 $sitearch /opt/perl/lib/site_perl/5.9.0/$archname
626 =head2 Changing the installation directory
628 Configure distinguishes between the directory in which perl (and its
629 associated files) should be installed and the directory in which it
630 will eventually reside. For most sites, these two are the same; for
631 sites that use AFS, this distinction is handled automatically.
632 However, sites that use software such as depot to manage software
633 packages, or users building binary packages for distribution may also
634 wish to install perl into a different directory and use that
635 management software to move perl to its final destination. This
636 section describes how to do that.
638 Suppose you want to install perl under the /tmp/perl5 directory. You
639 could edit config.sh and change all the install* variables to point to
640 /tmp/perl5 instead of /usr/local, or you could simply use the
641 following command line:
643 sh Configure -Dinstallprefix=/tmp/perl5
645 (replace /tmp/perl5 by a directory of your choice).
647 Beware, though, that if you go to try to install new add-on
648 modules, they too will get installed in under '/tmp/perl5' if you
649 follow this example. The next section shows one way of dealing with
652 =head2 Creating an installable tar archive
654 If you need to install perl on many identical systems, it is
655 convenient to compile it once and create an archive that can be
656 installed on multiple systems. Suppose, for example, that you want to
657 create an archive that can be installed in /opt/perl.
658 Here's one way to do that:
660 # Set up to install perl into a different directory,
661 # e.g. /tmp/perl5 (see previous part).
662 sh Configure -Dinstallprefix=/tmp/perl5 -Dprefix=/opt/perl -des
665 make install # This will install everything into /tmp/perl5.
667 # Edit $archlib/Config.pm and $archlib/.packlist to change all the
668 # install* variables back to reflect where everything will
669 # really be installed. (That is, change /tmp/perl5 to /opt/perl
670 # everywhere in those files.)
671 # Check the scripts in $scriptdir to make sure they have the correct
672 # #!/wherever/perl line.
673 tar cvf ../perl5-archive.tar .
674 # Then, on each machine where you want to install perl,
675 cd /opt/perl # Or wherever you specified as $prefix
676 tar xvf perl5-archive.tar
678 Alternatively, the DESTDIR variable is honored during C<make install>.
679 The DESTDIR is automatically prepended to all the installation paths
680 (and there is no need to edit anything). With DESTDIR, the above
681 example can we written as:
683 sh Configure -Dprefix=/opt/perl -des
686 make install DESTDIR=/tmp/perl5
687 cd /tmp/perl5/opt/perl
688 tar cvf /tmp/perl5-archive.tar .
690 =head2 Site-wide Policy settings
692 After Configure runs, it stores a number of common site-wide "policy"
693 answers (such as installation directories and the local perl contact
694 person) in the Policy.sh file. If you want to build perl on another
695 system using the same policy defaults, simply copy the Policy.sh file
696 to the new system and Configure will use it along with the appropriate
697 hint file for your system.
699 Alternatively, if you wish to change some or all of those policy
704 to ensure that Configure doesn't re-use them.
706 Further information is in the Policy_sh.SH file itself.
708 If the generated Policy.sh file is unsuitable, you may freely edit it
709 to contain any valid shell commands. It will be run just after the
710 platform-specific hints files.
712 =head2 Configure-time Options
714 There are several different ways to Configure and build perl for your
715 system. For most users, the defaults are sensible and will work.
716 Some users, however, may wish to further customize perl. Here are
717 some of the main things you can change.
721 On some platforms, perl can be compiled with
722 support for threads. To enable this, run
724 sh Configure -Dusethreads
726 Currently, you need to specify -Dusethreads on the Configure command
727 line so that the hint files can make appropriate adjustments.
729 The default is to compile without thread support.
731 Perl has two different internal threads implementations. The current
732 model (available internally since 5.6, and as a user-level module
733 since 5.8) is called interpreter-based implementation (ithreads),
734 with one interpreter per thread, and explicit sharing of data.
736 The 5.005 version (5005threads) is considered obsolete, buggy, and
739 By default, Configure selects ithreads if -Dusethreads is specified.
741 (You need to also use the PerlIO layer, explained later, if you decide
742 to use ithreads, to guarantee the good interworking of threads and I/O.)
744 However, if you wish, you can select the unsupported old 5005threads behavior
746 sh Configure -Dusethreads -Duse5005threads
748 If you decide to use ithreads, the 'threads' module allows their use,
749 and the 'Thread' module offers an interface to both 5005threads and
750 ithreads (whichever has been configured).
752 When building threaded for certain library calls like the getgr*() and
753 the getpw*() there is a dynamically sized result buffer: the buffer
754 starts small but Perl will keep growing the buffer until the result fits.
755 To get a fixed upper limit you will have to recompile Perl with
756 PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want.
757 One way to do this is to run Configure with
758 C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>
760 =head2 Large file support.
762 Since Perl 5.6.0, Perl has supported large files (files larger than
763 2 gigabytes), and in many common platforms like Linux or Solaris this
764 support is on by default.
766 This is both good and bad. It is good in that you can use large files,
767 seek(), stat(), and -s them. It is bad in that if you are interfacing Perl
768 using some extension, the components you are connecting to must also
769 be large file aware: if Perl thinks files can be large but the other
770 parts of the software puzzle do not understand the concept, bad things
771 will happen. One popular extension suffering from this ailment is the
772 Apache extension mod_perl.
774 There's also one known limitation with the current large files
775 implementation: unless you also have 64-bit integers (see the next
776 section), you cannot use the printf/sprintf non-decimal integer
777 formats like C<%x> to print filesizes. You can use C<%d>, though.
779 =head2 64 bit support.
781 If your platform does not have 64 bits natively, but can simulate them
782 with compiler flags and/or C<long long> or C<int64_t>, you can build a
783 perl that uses 64 bits.
785 There are actually two modes of 64-bitness: the first one is achieved
786 using Configure -Duse64bitint and the second one using Configure
787 -Duse64bitall. The difference is that the first one is minimal and
788 the second one maximal. The first works in more places than the second.
790 The C<use64bitint> does only as much as is required to get 64-bit
791 integers into Perl (this may mean, for example, using "long longs")
792 while your memory may still be limited to 2 gigabytes (because your
793 pointers could still be 32-bit). Note that the name C<64bitint> does
794 not imply that your C compiler will be using 64-bit C<int>s (it might,
795 but it doesn't have to): the C<use64bitint> means that you will be
796 able to have 64 bits wide scalar values.
798 The C<use64bitall> goes all the way by attempting to switch also
799 integers (if it can), longs (and pointers) to being 64-bit. This may
800 create an even more binary incompatible Perl than -Duse64bitint: the
801 resulting executable may not run at all in a 32-bit box, or you may
802 have to reboot/reconfigure/rebuild your operating system to be 64-bit
805 Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint
808 NOTE: 64-bit support is still experimental on most platforms.
809 Existing support only covers the LP64 data model. In particular, the
810 LLP64 data model is not yet supported. 64-bit libraries and system
811 APIs on many platforms have not stabilized--your mileage may vary.
815 In some systems you may be able to use long doubles to enhance the
816 range and precision of your double precision floating point numbers
817 (that is, Perl's numbers). Use Configure -Duselongdouble to enable
818 this support (if it is available).
822 You can "Configure -Dusemorebits" to turn on both the 64-bit support
823 and the long double support.
825 =head2 Selecting File IO mechanisms
827 Executive summary: as of Perl 5.8, you should use the default "PerlIO"
828 as the IO mechanism unless you have a good reason not to.
830 In more detail: previous versions of perl used the standard IO
831 mechanisms as defined in stdio.h. Versions 5.003_02 and later of perl
832 introduced alternate IO mechanisms via a "PerlIO" abstraction, but up
833 until and including Perl 5.6, the stdio mechanism was still the default
834 and the only supported mechanism.
836 Starting from Perl 5.8, the default mechanism is to use the PerlIO
837 abstraction, because it allows better control of I/O mechanisms,
838 instead of having to work with (often, work around) vendors' I/O
841 This PerlIO abstraction can be (but again, unless you know what you
842 are doing, should not be) disabled either on the Configure command
845 sh Configure -Uuseperlio
847 or interactively at the appropriate Configure prompt.
849 With the PerlIO abstraction layer, there is another possibility for
850 the underlying IO calls, AT&T's "sfio". This has superior performance
851 to stdio.h in many cases, and is extensible by the use of "discipline"
852 modules ("Native" PerlIO has them too). Sfio currently only builds on
853 a subset of the UNIX platforms perl supports. Because the data
854 structures are completely different from stdio, perl extension modules
855 or external libraries may not work. This configuration exists to
856 allow these issues to be worked on.
858 This option requires the 'sfio' package to have been built and installed.
859 The latest sfio is available from http://www.research.att.com/sw/tools/sfio/
861 You select this option by
863 sh Configure -Duseperlio -Dusesfio
865 If you have already selected -Duseperlio, and if Configure detects
866 that you have sfio, then sfio will be the default suggested by
869 Note: On some systems, sfio's iffe configuration script fails to
870 detect that you have an atexit function (or equivalent). Apparently,
871 this is a problem at least for some versions of Linux and SunOS 4.
872 Configure should detect this problem and warn you about problems with
873 _exit vs. exit. If you have this problem, the fix is to go back to
874 your sfio sources and correct iffe's guess about atexit.
876 =head2 Algorithmic Complexity Attacks on Hashes
878 In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
879 Processing such hashes would consume large amounts of CPU time,
880 enabling a "Denial of Service" attack against Perl. Such hashes may be
881 a problem for example for mod_perl sites, sites with Perl CGI scripts
882 and web services, that process data originating from external sources.
884 In Perl 5.8.1 a security feature was introduced to make it harder
885 to create such degenerate hashes.
887 Because of this feature the keys(), values(), and each() functions may
888 return the hash elements in different order between different runs of
889 Perl even with the same data. One can still revert to the old
890 repeatable order by setting the environment variable PERL_HASH_SEED,
891 see L<perlrun/PERL_HASH_SEED>. Another option is to add
892 -DUSE_HASH_SEED_EXPLICIT to the compilation flags (for example by
893 using C<Configure -Accflags=-DUSE_HAS_SEED_EXPLICIT>), in which case
894 one has to explicitly set the PERL_HASH_SEED environment variable to
895 enable the security feature, or by adding -DNO_HASH_SEED to the compilation
896 flags to completely disable the randomisation feature.
898 B<Perl has never guaranteed any ordering of the hash keys>, and the
899 ordering has already changed several times during the lifetime of
900 Perl 5. Also, the ordering of hash keys has always been, and
901 continues to be, affected by the insertion order.
903 Note that because of this randomisation for example the Data::Dumper
904 results will be different between different runs of Perl since
905 Data::Dumper by default dumps hashes "unordered". The use of the
906 Data::Dumper C<Sortkeys> option is recommended.
910 Perl can be configured to be 'socksified', that is, to use the SOCKS
911 TCP/IP proxy protocol library. SOCKS is used to give applications
912 access to transport layer network proxies. Perl supports only SOCKS
913 Version 5. You can find more about SOCKS from http://www.socks.nec.com/
915 =head2 Dynamic Loading
917 By default, Configure will compile perl to use dynamic loading if
918 your system supports it. If you want to force perl to be compiled
919 statically, you can either choose this when Configure prompts you or
920 you can use the Configure command line option -Uusedl.
922 =head2 Building a shared Perl library
924 Currently, for most systems, the main perl executable is built by
925 linking the "perl library" libperl.a with perlmain.o, your static
926 extensions (usually just DynaLoader.a) and various extra libraries,
929 On some systems that support dynamic loading, it may be possible to
930 replace libperl.a with a shared libperl.so. If you anticipate building
931 several different perl binaries (e.g. by embedding libperl into
932 different programs, or by using the optional compiler extension), then
933 you might wish to build a shared libperl.so so that all your binaries
934 can share the same library.
936 The disadvantages are that there may be a significant performance
937 penalty associated with the shared libperl.so, and that the overall
938 mechanism is still rather fragile with respect to different versions
941 In terms of performance, on my test system (Solaris 2.5_x86) the perl
942 test suite took roughly 15% longer to run with the shared libperl.so.
943 Your system and typical applications may well give quite different
946 The default name for the shared library is typically something like
947 libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 or simply
948 libperl.so. Configure tries to guess a sensible naming convention
949 based on your C library name. Since the library gets installed in a
950 version-specific architecture-dependent directory, the exact name
951 isn't very important anyway, as long as your linker is happy.
953 For some systems (mostly SVR4), building a shared libperl is required
954 for dynamic loading to work, and hence is already the default.
956 You can elect to build a shared libperl by
958 sh Configure -Duseshrplib
960 To build a shared libperl, the environment variable controlling shared
961 library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
962 NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
963 for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
964 the Perl build directory because that's where the shared libperl will
965 be created. Configure arranges makefile to have the correct shared
966 library search settings. You can find the name of the environment
967 variable Perl thinks works in your your system by
969 grep ldlibpthname config.sh
971 However, there are some special cases where manually setting the
972 shared library path might be required. For example, if you want to run
973 something like the following with the newly-built but not-yet-installed
976 cd t; ./perl misc/failing_test.t
978 ./perl -Ilib ~/my_mission_critical_test
980 then you need to set up the shared library path explicitly.
983 LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
985 for Bourne-style shells, or
987 setenv LD_LIBRARY_PATH `pwd`
989 for Csh-style shells. (This procedure may also be needed if for some
990 unexpected reason Configure fails to set up makefile correctly.) (And
991 again, it may be something other than LD_LIBRARY_PATH for you, see above.)
993 You can often recognize failures to build/use a shared libperl from error
994 messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
996 18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
998 There is also an potential problem with the shared perl library if you
999 want to have more than one "flavor" of the same version of perl (e.g.
1000 with and without -DDEBUGGING). For example, suppose you build and
1001 install a standard Perl 5.8.0 with a shared library. Then, suppose you
1002 try to build Perl 5.8.0 with -DDEBUGGING enabled, but everything else
1003 the same, including all the installation directories. How can you
1004 ensure that your newly built perl will link with your newly built
1005 libperl.so.8 rather with the installed libperl.so.8? The answer is
1006 that you might not be able to. The installation directory is encoded
1007 in the perl binary with the LD_RUN_PATH environment variable (or
1008 equivalent ld command-line option). On Solaris, you can override that
1009 with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
1010 LD_PRELOAD, specifying the exact filename you wish to be used; and on
1011 Digital Unix, you can override LD_LIBRARY_PATH by setting the
1012 _RLD_ROOT environment variable to point to the perl build directory.
1014 In other words, it is generally not a good idea to try to build a perl
1015 with a shared library if $archlib/CORE/$libperl already exists from a
1018 A good workaround is to specify a different directory for the
1019 architecture-dependent library for your -DDEBUGGING version of perl.
1020 You can do this by changing all the *archlib* variables in config.sh to
1021 point to your new architecture-dependent library.
1023 =head2 Malloc Issues
1025 Perl relies heavily on malloc(3) to grow data structures as needed,
1026 so perl's performance can be noticeably affected by the performance of
1027 the malloc function on your system. The perl source is shipped with a
1028 version of malloc that has been optimized for the typical requests from
1029 perl, so there's a chance that it may be both faster and use less memory
1030 than your system malloc.
1032 However, if your system already has an excellent malloc, or if you are
1033 experiencing difficulties with extensions that use third-party libraries
1034 that call malloc, then you should probably use your system's malloc.
1035 (Or, you might wish to explore the malloc flags discussed below.)
1039 =item Using the system malloc
1041 To build without perl's malloc, you can use the Configure command
1043 sh Configure -Uusemymalloc
1045 or you can answer 'n' at the appropriate interactive Configure prompt.
1047 =item -DPERL_POLLUTE_MALLOC
1049 NOTE: This flag is enabled automatically on some platforms if you just
1050 run Configure to accept all the defaults on those platforms.
1052 Perl's malloc family of functions are normally called Perl_malloc(),
1053 Perl_realloc(), Perl_calloc() and Perl_mfree().
1054 These names do not clash with the system versions of these functions.
1056 If this flag is enabled, however, Perl's malloc family of functions
1057 will have the same names as the system versions. This may be required
1058 sometimes if you have libraries that like to free() data that may have
1059 been allocated by Perl_malloc() and vice versa.
1061 Note that enabling this option may sometimes lead to duplicate symbols
1062 from the linker for malloc et al. In such cases, the system probably
1063 does not allow its malloc functions to be fully replaced with custom
1066 =item -DPERL_DEBUGGING_MSTATS
1068 This flag enables debugging mstats, which is required to use the
1069 Devel::Peek::mstat() function. You cannot enable this unless you are
1070 using Perl's malloc, so a typical Configure command would be
1072 sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc='y'
1074 to enable this option.
1078 =head2 Building a debugging perl
1080 You can run perl scripts under the perl debugger at any time with
1081 B<perl -d your_script>. If, however, you want to debug perl itself,
1082 you probably want to do
1084 sh Configure -Doptimize='-g'
1086 This will do two independent things: First, it will force compilation
1087 to use cc -g so that you can use your system's debugger on the
1088 executable. (Note: Your system may actually require something like
1089 cc -g2. Check your man pages for cc(1) and also any hint file for
1090 your system.) Second, it will add -DDEBUGGING to your ccflags
1091 variable in config.sh so that you can use B<perl -D> to access perl's
1092 internal state. (Note: Configure will only add -DDEBUGGING by default
1093 if you are not reusing your old config.sh. If you want to reuse your
1094 old config.sh, then you can just edit it and change the optimize and
1095 ccflags variables by hand and then propagate your changes as shown in
1096 L<"Propagating your changes to config.sh"> below.)
1098 You can actually specify -g and -DDEBUGGING independently, but usually
1099 it's convenient to have both.
1101 If you are using a shared libperl, see the warnings about multiple
1102 versions of perl under L<Building a shared Perl library>.
1106 Perl ships with a number of standard extensions. These are contained
1107 in the ext/ subdirectory.
1109 By default, Configure will offer to build every extension which appears
1110 to be supported. For example, Configure will offer to build GDBM_File
1111 only if it is able to find the gdbm library. (See examples below.)
1112 Configure does not contain code to test for POSIX compliance, so POSIX
1113 is always built by default as well. If you wish to skip POSIX, you can
1114 set the Configure variable useposix=false either in a hint file or from
1115 the Configure command line.
1117 If you unpack any additional extensions in the ext/ directory before
1118 running Configure, then Configure will offer to build those additional
1119 extensions as well. Most users probably shouldn't have to do this --
1120 it is usually easier to build additional extensions later after perl
1121 has been installed. However, if you wish to have those additional
1122 extensions statically linked into the perl binary, then this offers a
1123 convenient way to do that in one step. (It is not necessary, however;
1124 you can build and install extensions just fine even if you don't have
1125 dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
1127 If you have dynamic loading, another way of specifying extra modules
1128 is described in L<"Adding extra modules to the build"> below.
1130 You can learn more about each of the supplied extensions by consulting the
1131 documentation in the individual .pm modules, located under the
1134 Even if you do not have dynamic loading, you must still build the
1135 DynaLoader extension; you should just build the stub dl_none.xs
1136 version. (Configure will suggest this as the default.)
1138 To disable certain extensions so that they are not built, use
1139 the -Dnoextensions=... and -Donlyextensions=... options. They both
1140 accept a space-separated list of extensions. The extensions listed
1141 in C<noextensions> are removed from the list of extensions to build,
1142 while the C<onlyextensions> is rather more severe and builds only
1143 the listed extensions. The latter should be used with extreme caution
1144 since certain extensions are used by many other extensions and modules:
1145 such modules include Fcntl and IO. The order of processing these
1146 options is first C<only> (if present), then C<no> (if present).
1148 Another, older way to turn off various extensions (which is still good
1149 to know if you have to work with older Perl) exists. Here are the
1150 Configure command-line variables you can set to turn off various
1151 extensions. All others are included by default.
1154 DynaLoader (Must always be included as a static extension)
1161 Threads use5005threads
1163 Thus to skip the NDBM_File extension, you can use
1165 sh Configure -Ui_ndbm
1167 Again, this is taken care of automatically if you don't have the ndbm
1170 Of course, you may always run Configure interactively and select only
1171 the extensions you want.
1173 Note: The DB_File module will only work with version 1.x of Berkeley
1174 DB or newer releases of version 2. Configure will automatically detect
1175 this for you and refuse to try to build DB_File with earlier
1176 releases of version 2.
1178 If you re-use your old config.sh but change your system (e.g. by
1179 adding libgdbm) Configure will still offer your old choices of extensions
1180 for the default answer, but it will also point out the discrepancy to
1183 Finally, if you have dynamic loading (most modern systems do)
1184 remember that these extensions do not increase the size of your perl
1185 executable, nor do they impact start-up time, so you probably might as
1186 well build all the ones that will work on your system.
1188 =head2 Including locally-installed libraries
1190 Perl5 comes with interfaces to number of database extensions, including
1191 dbm, ndbm, gdbm, and Berkeley db. For each extension, if
1192 Configure can find the appropriate header files and libraries, it will
1193 automatically include that extension. The gdbm and db libraries
1194 are not included with perl. See the library documentation for
1195 how to obtain the libraries.
1197 If your database header (.h) files are not in a directory normally
1198 searched by your C compiler, then you will need to include the
1199 appropriate -I/your/directory option when prompted by Configure. If
1200 your database library (.a) files are not in a directory normally
1201 searched by your C compiler and linker, then you will need to include
1202 the appropriate -L/your/directory option when prompted by Configure.
1203 See the examples below.
1209 =item gdbm in /usr/local
1211 Suppose you have gdbm and want Configure to find it and build the
1212 GDBM_File extension. This example assumes you have gdbm.h
1213 installed in /usr/local/include/gdbm.h and libgdbm.a installed in
1214 /usr/local/lib/libgdbm.a. Configure should figure all the
1215 necessary steps out automatically.
1217 Specifically, when Configure prompts you for flags for
1218 your C compiler, you should include -I/usr/local/include.
1220 When Configure prompts you for linker flags, you should include
1223 If you are using dynamic loading, then when Configure prompts you for
1224 linker flags for dynamic loading, you should again include
1227 Again, this should all happen automatically. This should also work if
1228 you have gdbm installed in any of (/usr/local, /opt/local, /usr/gnu,
1229 /opt/gnu, /usr/GNU, or /opt/GNU).
1231 =item gdbm in /usr/you
1233 Suppose you have gdbm installed in some place other than /usr/local/,
1234 but you still want Configure to find it. To be specific, assume you
1235 have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a. You
1236 still have to add -I/usr/you/include to cc flags, but you have to take
1237 an extra step to help Configure find libgdbm.a. Specifically, when
1238 Configure prompts you for library directories, you have to add
1239 /usr/you/lib to the list.
1241 It is possible to specify this from the command line too (all on one
1245 -Dlocincpth="/usr/you/include" \
1246 -Dloclibpth="/usr/you/lib"
1248 locincpth is a space-separated list of include directories to search.
1249 Configure will automatically add the appropriate -I directives.
1251 loclibpth is a space-separated list of library directories to search.
1252 Configure will automatically add the appropriate -L directives. If
1253 you have some libraries under /usr/local/ and others under
1254 /usr/you, then you have to include both, namely
1257 -Dlocincpth="/usr/you/include /usr/local/include" \
1258 -Dloclibpth="/usr/you/lib /usr/local/lib"
1262 =head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3
1264 Perl interface for DB3 is part of Berkeley DB, but if you want to
1265 compile standard Perl DB/ODBM/NDBM interfaces, you must follow
1266 following instructions.
1268 Berkeley DB3 from Sleepycat Software is by default installed without
1269 DB1 compatibility code (needed for DB_File interface) and without
1270 links to compatibility files. So if you want to use packages written
1271 for DB/ODBM/NDBM interfaces, you need to configure DB3 with
1272 --enable-compat185 (and optionally with --enable-dump185) and create
1273 additional references (suppose you are installing DB3 with
1276 ln -s libdb-3.so /usr/lib/libdbm.so
1277 ln -s libdb-3.so /usr/lib/libndbm.so
1278 echo '#define DB_DBM_HSEARCH 1' >dbm.h
1279 echo '#include <db.h>' >>dbm.h
1280 install -m 0644 dbm.h /usr/include/dbm.h
1281 install -m 0644 dbm.h /usr/include/ndbm.h
1283 Optionally, if you have compiled with --enable-compat185 (not needed
1286 ln -s libdb-3.so /usr/lib/libdb1.so
1287 ln -s libdb-3.so /usr/lib/libdb.so
1289 ODBM emulation seems not to be perfect, but is quite usable,
1292 lib/odbm.............FAILED at test 9
1293 Failed 1/64 tests, 98.44% okay
1295 =head2 What if it doesn't work?
1297 If you run into problems, try some of the following ideas.
1298 If none of them help, then see L<"Reporting Problems"> below.
1302 =item Running Configure Interactively
1304 If Configure runs into trouble, remember that you can always run
1305 Configure interactively so that you can check (and correct) its
1308 All the installation questions have been moved to the top, so you don't
1309 have to wait for them. Once you've handled them (and your C compiler and
1310 flags) you can type &-d at the next Configure prompt and Configure
1311 will use the defaults from then on.
1313 If you find yourself trying obscure command line incantations and
1314 config.over tricks, I recommend you run Configure interactively
1315 instead. You'll probably save yourself time in the long run.
1319 The perl distribution includes a number of system-specific hints files
1320 in the hints/ directory. If one of them matches your system, Configure
1321 will offer to use that hint file.
1323 Several of the hint files contain additional important information.
1324 If you have any problems, it is a good idea to read the relevant hint file
1325 for further information. See hints/solaris_2.sh for an extensive example.
1326 More information about writing good hints is in the hints/README.hints
1329 =item *** WHOA THERE!!! ***
1331 Occasionally, Configure makes a wrong guess. For example, on SunOS
1332 4.1.3, Configure incorrectly concludes that tzname[] is in the
1333 standard C library. The hint file is set up to correct for this. You
1336 *** WHOA THERE!!! ***
1337 The recommended value for $d_tzname on this machine was "undef"!
1338 Keep the recommended value? [y]
1340 You should always keep the recommended value unless, after reading the
1341 relevant section of the hint file, you are sure you want to try
1344 If you are re-using an old config.sh, the word "previous" will be
1345 used instead of "recommended". Again, you will almost always want
1346 to keep the previous value, unless you have changed something on your
1349 For example, suppose you have added libgdbm.a to your system
1350 and you decide to reconfigure perl to use GDBM_File. When you run
1351 Configure again, you will need to add -lgdbm to the list of libraries.
1352 Now, Configure will find your gdbm include file and library and will
1355 *** WHOA THERE!!! ***
1356 The previous value for $i_gdbm on this machine was "undef"!
1357 Keep the previous value? [y]
1359 In this case, you do not want to keep the previous value, so you
1360 should answer 'n'. (You'll also have to manually add GDBM_File to
1361 the list of dynamic extensions to build.)
1363 =item Changing Compilers
1365 If you change compilers or make other significant changes, you should
1366 probably not re-use your old config.sh. Simply remove it or
1367 rename it, e.g. mv config.sh config.sh.old. Then rerun Configure
1368 with the options you want to use.
1370 This is a common source of problems. If you change from cc to
1371 gcc, you should almost always remove your old config.sh.
1373 =item Propagating your changes to config.sh
1375 If you make any changes to config.sh, you should propagate
1376 them to all the .SH files by running
1380 You will then have to rebuild by running
1385 =item config.over and config.arch
1387 You can also supply a shell script config.over to over-ride
1388 Configure's guesses. It will get loaded up at the very end, just
1389 before config.sh is created. You have to be careful with this,
1390 however, as Configure does no checking that your changes make sense.
1391 This file is usually good for site-specific customizations.
1393 There is also another file that, if it exists, is loaded before the
1394 config.over, called config.arch. This file is intended to be per
1395 architecture, not per site, and usually it's the architecture-specific
1396 hints file that creates the config.arch.
1400 Many of the system dependencies are contained in config.h.
1401 Configure builds config.h by running the config_h.SH script.
1402 The values for the variables are taken from config.sh.
1404 If there are any problems, you can edit config.h directly. Beware,
1405 though, that the next time you run Configure, your changes will be
1410 If you have any additional changes to make to the C compiler command
1411 line, they can be made in cflags.SH. For instance, to turn off the
1412 optimizer on toke.c, find the line in the switch structure for
1413 toke.c and put the command optimize='-g' before the ;; . You
1414 can also edit cflags directly, but beware that your changes will be
1415 lost the next time you run Configure.
1417 To explore various ways of changing ccflags from within a hint file,
1418 see the file hints/README.hints.
1420 To change the C flags for all the files, edit config.sh and change either
1421 $ccflags or $optimize, and then re-run
1428 If you don't have sh, you'll have to copy the sample file
1429 Porting/config.sh to config.sh and edit your config.sh to reflect your
1430 system's peculiarities. See Porting/pumpkin.pod for more information.
1431 You'll probably also have to extensively modify the extension building
1434 =item Digital UNIX/Tru64 UNIX and BIN_SH
1436 In Digital UNIX/Tru64 UNIX, Configure might abort with
1438 Build a threading Perl? [n]
1439 Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
1441 This indicates that Configure is being run with a broken Korn shell
1442 (even though you think you are using a Bourne shell by using
1443 "sh Configure" or "./Configure"). The Korn shell bug has been reported
1444 to Compaq as of February 1999 but in the meanwhile, the reason ksh is
1445 being used is that you have the environment variable BIN_SH set to
1446 'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh
1447 (a ksh). Unset the environment variable and rerun Configure.
1449 =item HP-UX 11, pthreads, and libgdbm
1451 If you are running Configure with -Dusethreads in HP-UX 11, be warned
1452 that POSIX threads and libgdbm (the GNU dbm library) compiled before
1453 HP-UX 11 do not mix. This will cause a basic test run by Configure to
1456 Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
1457 Return Pointer is 0xc082bf33
1458 sh: 5345 Quit(coredump)
1460 and Configure will give up. The cure is to recompile and install
1461 libgdbm under HP-UX 11.
1463 =item Porting information
1465 Specific information for the OS/2, Plan 9, VMS and Win32 ports is in the
1466 corresponding README files and subdirectories. Additional information,
1467 including a glossary of all those config.sh variables, is in the Porting
1468 subdirectory. Especially Porting/Glossary should come in handy.
1470 Ports for other systems may also be available. You should check out
1471 http://www.cpan.org/ports for current information on ports to
1472 various other operating systems.
1474 If you plan to port Perl to a new architecture study carefully the
1475 section titled "Philosophical Issues in Patching and Porting Perl"
1476 in the file Porting/pumpkin.pod and the file Porting/patching.pod.
1477 Study also how other non-UNIX ports have solved problems.
1481 =head1 Adding extra modules to the build
1483 You can specify extra modules or module bundles to be fetched from the
1484 CPAN and installed as part of the Perl build. Either use the -Dextras=...
1485 command line parameter to Configure, for example like this:
1487 Configure -Dextras="Compress::Zlib Bundle::LWP DBI"
1489 or answer first 'y' to the question 'Install any extra modules?' and
1490 then answer "Compress::Zlib Bundle::LWP DBI" to the 'Extras?' question.
1491 The module or the bundle names are as for the CPAN module 'install' command.
1492 This will only work if those modules are to be built as dynamic
1493 extensions. If you wish to include those extra modules as static
1494 extensions, see L<"Extensions"> above.
1496 Notice that because the CPAN module will be used to fetch the extra
1497 modules, you will need access to the CPAN, either via the Internet,
1498 or via a local copy such as a CD-ROM or a local CPAN mirror. If you
1499 do not, using the extra modules option will die horribly.
1501 Also notice that you yourself are responsible for satisfying any extra
1502 dependencies such as external headers or libraries BEFORE trying the build.
1503 For example: you will need to have the zlib.h header and the libz
1504 library installed for the Compress::Zlib, or the Foo database specific
1505 headers and libraries installed for the DBD::Foo module. The Configure
1506 process or the Perl build process will not help you with these.
1510 suidperl is an optional component, which is built or installed by default.
1513 On some systems, setuid and setgid scripts (scripts written
1514 in the C shell, Bourne shell, or Perl, for example, with the
1515 set user or group ID permissions enabled) are insecure due to
1516 a race condition in the kernel. For those systems, Perl versions
1517 5 and 4 attempt to work around this vulnerability with an optional
1518 component, a special program named suidperl, also known as sperl.
1519 This program attempts to emulate the set-user-ID and set-group-ID
1520 features of the kernel.
1522 Because of the buggy history of suidperl, and the difficulty
1523 of properly security auditing as large and complex piece of
1524 software as Perl, we cannot recommend using suidperl and the feature
1525 should be considered deprecated.
1526 Instead use for example 'sudo': http://www.courtesan.com/sudo/
1530 This will look for all the includes. The output is stored in makefile.
1531 The only difference between Makefile and makefile is the dependencies at
1532 the bottom of makefile. If you have to make any changes, you should edit
1533 makefile, not Makefile since the Unix make command reads makefile first.
1534 (On non-Unix systems, the output may be stored in a different file.
1535 Check the value of $firstmakefile in your config.sh if in doubt.)
1537 Configure will offer to do this step for you, so it isn't listed
1542 This will attempt to make perl in the current directory.
1544 =head2 Expected errors
1546 These errors are normal, and can be ignored:
1549 make: [extra.pods] Error 1 (ignored)
1551 make: [extras.make] Error 1 (ignored)
1553 =head2 What if it doesn't work?
1555 If you can't compile successfully, try some of the following ideas.
1556 If none of them help, and careful reading of the error message and
1557 the relevant manual pages on your system doesn't help,
1558 then see L<"Reporting Problems"> below.
1564 If you used a hint file, try reading the comments in the hint file
1565 for further tips and information.
1569 If you can successfully build miniperl, but the process crashes
1570 during the building of extensions, you should run
1574 to test your version of miniperl.
1578 If you have any locale-related environment variables set, try unsetting
1579 them. I have some reports that some versions of IRIX hang while
1580 running B<./miniperl configpm> with locales other than the C locale.
1581 See the discussion under L<"make test"> below about locales and the
1582 whole L<"Locale problems"> section in the file pod/perllocale.pod.
1583 The latter is especially useful if you see something like this
1585 perl: warning: Setting locale failed.
1586 perl: warning: Please check that your locale settings:
1589 are supported and installed on your system.
1590 perl: warning: Falling back to the standard locale ("C").
1596 If you get varargs problems with gcc, be sure that gcc is installed
1597 correctly and that you are not passing -I/usr/include to gcc. When using
1598 gcc, you should probably have i_stdarg='define' and i_varargs='undef'
1599 in config.sh. The problem is usually solved by running fixincludes
1600 correctly. If you do change config.sh, don't forget to propagate
1601 your changes (see L<"Propagating your changes to config.sh"> below).
1602 See also the L<"vsprintf"> item below.
1606 If you get error messages such as the following (the exact line
1607 numbers and function name may vary in different versions of perl):
1609 util.c: In function `Perl_form':
1610 util.c:1107: number of arguments doesn't match prototype
1611 proto.h:125: prototype declaration
1613 it might well be a symptom of the gcc "varargs problem". See the
1614 previous L<"varargs"> item.
1616 =item LD_LIBRARY_PATH
1618 If you run into dynamic loading problems, check your setting of
1619 the LD_LIBRARY_PATH environment variable. If you're creating a static
1620 Perl library (libperl.a rather than libperl.so) it should build
1621 fine with LD_LIBRARY_PATH unset, though that may depend on details
1622 of your local set-up.
1626 If Configure seems to be having trouble finding library functions,
1627 try not using nm extraction. You can do this from the command line
1630 sh Configure -Uusenm
1632 or by answering the nm extraction question interactively.
1633 If you have previously run Configure, you should not reuse your old
1636 =item umask not found
1638 If the build processes encounters errors relating to umask(), the problem
1639 is probably that Configure couldn't find your umask() system call.
1640 Check your config.sh. You should have d_umask='define'. If you don't,
1641 this is probably the L<"nm extraction"> problem discussed above. Also,
1642 try reading the hints file for your system for further information.
1646 If you run into problems with vsprintf in compiling util.c, the
1647 problem is probably that Configure failed to detect your system's
1648 version of vsprintf(). Check whether your system has vprintf().
1649 (Virtually all modern Unix systems do.) Then, check the variable
1650 d_vprintf in config.sh. If your system has vprintf, it should be:
1654 If Configure guessed wrong, it is likely that Configure guessed wrong
1655 on a number of other common functions too. This is probably
1656 the L<"nm extraction"> problem discussed above.
1660 If you run into problems relating to do_aspawn or do_spawn, the
1661 problem is probably that Configure failed to detect your system's
1662 fork() function. Follow the procedure in the previous item
1663 on L<"nm extraction">.
1665 =item __inet_* errors
1667 If you receive unresolved symbol errors during Perl build and/or test
1668 referring to __inet_* symbols, check to see whether BIND 8.1 is
1669 installed. It installs a /usr/local/include/arpa/inet.h that refers to
1670 these symbols. Versions of BIND later than 8.1 do not install inet.h
1671 in that location and avoid the errors. You should probably update to a
1672 newer version of BIND (and remove the files the old one left behind).
1673 If you can't, you can either link with the updated resolver library provided
1674 with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the Perl build and
1675 test process to avoid the problem.
1677 =item *_r() prototype NOT found
1679 On a related note, if you see a bunch of complaints like the above about
1680 reentrant functions - specifically networking-related ones - being present
1681 but without prototypes available, check to see if BIND 8.1 (or possibly
1682 other BIND 8 versions) is (or has been) installed. They install
1683 header files such as netdb.h into places such as /usr/local/include (or into
1684 another directory as specified at build/install time), at least optionally.
1685 Remove them or put them in someplace that isn't in the C preprocessor's
1686 header file include search path (determined by -I options plus defaults,
1687 normally /usr/include).
1689 =item #error "No DATAMODEL_NATIVE specified"
1691 This is a common error when trying to build perl on Solaris 2.6 with a
1692 gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
1693 changed, so you need to update your gcc installation. You can either
1694 rerun the fixincludes script from gcc or take the opportunity to
1695 update your gcc installation.
1699 If you can't compile successfully, try turning off your compiler's
1700 optimizer. Edit config.sh and change the line
1708 then propagate your changes with B<sh Configure -S> and rebuild
1709 with B<make depend; make>.
1711 =item Missing functions
1713 If you have missing routines, you probably need to add some library or
1714 other, or you need to undefine some feature that Configure thought was
1715 there but is defective or incomplete. Look through config.h for
1716 likely suspects. If Configure guessed wrong on a number of functions,
1717 you might have the L<"nm extraction"> problem discussed above.
1721 Some compilers will not compile or optimize the larger files (such as
1722 toke.c) without some extra switches to use larger jump offsets or
1723 allocate larger internal tables. You can customize the switches for
1724 each file in cflags. It's okay to insert rules for specific files into
1725 makefile since a default rule only takes effect in the absence of a
1728 =item Missing dbmclose
1730 SCO prior to 3.2.4 may be missing dbmclose(). An upgrade to 3.2.4
1731 that includes libdbm.nfs (which includes dbmclose()) may be available.
1733 =item Note (probably harmless): No library found for -lsomething
1735 If you see such a message during the building of an extension, but
1736 the extension passes its tests anyway (see L<"make test"> below),
1737 then don't worry about the warning message. The extension
1738 Makefile.PL goes looking for various libraries needed on various
1739 systems; few systems will need all the possible libraries listed.
1740 For example, a system may have -lcposix or -lposix, but it's
1741 unlikely to have both, so most users will see warnings for the one
1742 they don't have. The phrase 'probably harmless' is intended to
1743 reassure you that nothing unusual is happening, and the build
1744 process is continuing.
1746 On the other hand, if you are building GDBM_File and you get the
1749 Note (probably harmless): No library found for -lgdbm
1751 then it's likely you're going to run into trouble somewhere along
1752 the line, since it's hard to see how you can use the GDBM_File
1753 extension without the -lgdbm library.
1755 It is true that, in principle, Configure could have figured all of
1756 this out, but Configure and the extension building process are not
1757 quite that tightly coordinated.
1759 =item sh: ar: not found
1761 This is a message from your shell telling you that the command 'ar'
1762 was not found. You need to check your PATH environment variable to
1763 make sure that it includes the directory with the 'ar' command. This
1764 is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
1767 =item db-recno failure on tests 51, 53 and 55
1769 Old versions of the DB library (including the DB library which comes
1770 with FreeBSD 2.1) had broken handling of recno databases with modified
1771 bval settings. Upgrade your DB library or OS.
1773 =item Bad arg length for semctl, is XX, should be ZZZ
1775 If you get this error message from the ext/IPC/SysV/t/sem test, your System
1776 V IPC may be broken. The XX typically is 20, and that is what ZZZ
1777 also should be. Consider upgrading your OS, or reconfiguring your OS
1778 to include the System V semaphores.
1780 =item ext/IPC/SysV/t/sem........semget: No space left on device
1782 Either your account or the whole system has run out of semaphores. Or
1783 both. Either list the semaphores with "ipcs" and remove the unneeded
1784 ones (which ones these are depends on your system and applications)
1785 with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
1790 If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
1791 tools you may be in for some trouble. For example creating archives
1792 with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
1793 may lead into linking problems. Either recompile your GNU binutils
1794 under your current operating system release, or modify your PATH not
1795 to include the GNU utils before running Configure, or specify the
1796 vendor-supplied utilities explicitly to Configure, for example by
1797 Configure -Dar=/bin/ar.
1799 =item THIS PACKAGE SEEMS TO BE INCOMPLETE
1801 The F<Configure> program has not been able to find all the files which
1802 make up the complete Perl distribution. You may have a damaged source
1803 archive file (in which case you may also have seen messages such as
1804 C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
1805 archive file>), or you may have obtained a structurally-sound but
1806 incomplete archive. In either case, try downloading again from the
1807 official site named at the start of this document. If you do find
1808 that any site is carrying a corrupted or incomplete source code
1809 archive, please report it to the site's maintainer.
1811 =item invalid token: ##
1813 You are using a non-ANSI-compliant C compiler. See L<WARNING: This
1814 version requires a compiler that supports ANSI C.>
1818 Some additional things that have been reported for either perl4 or perl5:
1820 Genix may need to use libc rather than libc_s, or #undef VARARGS.
1822 NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
1824 UTS may need one or more of -K or -g, and undef LSTAT.
1826 FreeBSD can fail the ext/IPC/SysV/t/sem.t test if SysV IPC has not been
1827 configured in the kernel. Perl tries to detect this, though, and
1828 you will get a message telling what to do.
1830 HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
1831 Patch Bundle" has been reported to break the io/fs test #18 which
1832 tests whether utime() can change timestamps. The Y2K patch seems to
1833 break utime() so that over NFS the timestamps do not get changed
1834 (on local filesystems utime() still works).
1836 Building Perl on a system that has also BIND (headers and libraries)
1837 installed may run into troubles because BIND installs its own netdb.h
1838 and socket.h, which may not agree with the operating system's ideas of
1839 the same files. Similarly, including -lbind may conflict with libc's
1840 view of the world. You may have to tweak -Dlocincpth and -Dloclibpth
1845 =head2 Cross-compilation
1847 Starting from Perl 5.8 Perl has the beginnings of cross-compilation
1848 support. What is known to work is running Configure in a
1849 cross-compilation environment and building the miniperl executable.
1850 What is known not to work is building the perl executable because
1851 that would require building extensions: Dynaloader statically and
1852 File::Glob dynamically, for extensions one needs MakeMaker and
1853 MakeMaker is not yet cross-compilation aware, and neither is
1856 Since the functionality is so lacking, it must be considered
1857 highly experimental. It is so experimental that it is not even
1858 mentioned during an interactive Configure session, a direct command
1859 line invocation (detailed shortly) is required to access the
1862 NOTE: Perl is routinely built using cross-compilation
1863 in the EPOC environment, in the WinCE, and in the OpenZaurus
1864 project, but all those use something slightly different setup
1865 than what described here. For the WinCE setup, read the
1866 wince/README.compile. For the OpenZaurus setup, read the
1869 The one environment where this cross-compilation setup has
1870 successfully been used as of this writing is the Compaq iPAQ running
1871 ARM Linux. The build host was Intel Linux, the networking setup was
1872 PPP + SSH. The exact setup details are beyond the scope of this
1873 document, see http://www.handhelds.org/ for more information.
1875 To run Configure in cross-compilation mode the basic switch is
1876 C<-Dusecrosscompile>.
1878 sh ./Configure -des -Dusecrosscompile -D...
1880 This will make the cpp symbol USE_CROSS_COMPILE and the %Config
1881 symbol C<usecrosscompile> available.
1883 During the Configure and build, certain helper scripts will be created
1884 into the Cross/ subdirectory. The scripts are used to execute a
1885 cross-compiled executable, and to transfer files to and from the
1886 target host. The execution scripts are named F<run-*> and the
1887 transfer scripts F<to-*> and F<from-*>. The part after the dash is
1888 the method to use for remote execution and transfer: by default the
1889 methods are B<ssh> and B<scp>, thus making the scripts F<run-ssh>,
1890 F<to-scp>, and F<from-scp>.
1892 To configure the scripts for a target host and a directory (in which
1893 the execution will happen and which is to and from where the transfer
1894 happens), supply Configure with
1896 -Dtargethost=so.me.ho.st -Dtargetdir=/tar/get/dir
1898 The targethost is what e.g. ssh will use as the hostname, the targetdir
1899 must exist (the scripts won't create it), the targetdir defaults to /tmp.
1900 You can also specify a username to use for ssh/rsh logins
1904 but in case you don't, "root" will be used.
1906 Because this is a cross-compilation effort, you will also need to specify
1907 which target environment and which compilation environment to use.
1908 This includes the compiler, the header files, and the libraries.
1909 In the below we use the usual settings for the iPAQ cross-compilation
1912 -Dtargetarch=arm-linux
1914 -Dusrinc=/skiff/local/arm-linux/include
1915 -Dincpth=/skiff/local/arm-linux/include
1916 -Dlibpth=/skiff/local/arm-linux/lib
1918 If the name of the C<cc> has the usual GNU C semantics for cross
1919 compilers, that is, CPU-OS-gcc, the names of the C<ar>, C<nm>, and
1920 C<ranlib> will also be automatically chosen to be CPU-OS-ar and so on.
1921 (The C<ld> requires more thought and will be chosen later by Configure
1922 as appropriate.) Also, in this case the incpth, libpth, and usrinc
1923 will be guessed by Configure (unless explicitly set to something else,
1924 in which case Configure's guesses with be appended).
1926 In addition to the default execution/transfer methods you can also
1927 choose B<rsh> for execution, and B<rcp> or B<cp> for transfer,
1930 -Dtargetrun=rsh -Dtargetto=rcp -Dtargetfrom=cp
1932 Putting it all together:
1934 sh ./Configure -des -Dusecrosscompile \
1935 -Dtargethost=so.me.ho.st \
1936 -Dtargetdir=/tar/get/dir \
1938 -Dtargetarch=arm-linux \
1939 -Dcc=arm-linux-gcc \
1940 -Dusrinc=/skiff/local/arm-linux/include \
1941 -Dincpth=/skiff/local/arm-linux/include \
1942 -Dlibpth=/skiff/local/arm-linux/lib \
1945 or if you are happy with the defaults
1947 sh ./Configure -des -Dusecrosscompile \
1948 -Dtargethost=so.me.ho.st \
1949 -Dcc=arm-linux-gcc \
1954 This will run the regression tests on the perl you just made. If
1955 'make test' doesn't say "All tests successful" then something went
1956 wrong. See the file t/README in the t subdirectory.
1958 Note that you can't run the tests in background if this disables
1959 opening of /dev/tty. You can use 'make test-notty' in that case but
1960 a few tty tests will be skipped.
1962 =head2 What if make test doesn't work?
1964 If make test bombs out, just cd to the t directory and run ./TEST
1965 by hand to see if it makes any difference. If individual tests
1966 bomb, you can run them by hand, e.g.,
1970 Another way to get more detailed information about failed tests and
1971 individual subtests is to cd to the t directory and run
1975 (this assumes that most basic tests succeed, since harness uses
1976 complicated constructs). For extension and library tests you
1977 need a little bit more: you need to setup your environment variable
1978 PERL_CORE to a true value (like "1"), and you need to supply the
1979 right Perl library path:
1982 ./perl -I../lib ../ext/Socket/Socket.t
1983 ./perl -I../lib ../lib/less.t
1985 (For csh-like shells on UNIX; adjust appropriately for other platforms.)
1986 You should also read the individual tests to see if there are any helpful
1987 comments that apply to your system. You may also need to setup your
1988 shared library path if you get errors like:
1990 /sbin/loader: Fatal Error: cannot map libperl.so
1992 See L</"Building a shared Perl library"> earlier in this document.
1998 Note: One possible reason for errors is that some external programs
1999 may be broken due to the combination of your environment and the way
2000 B<make test> exercises them. For example, this may happen if you have
2001 one or more of these environment variables set: LC_ALL LC_CTYPE
2002 LC_COLLATE LANG. In some versions of UNIX, the non-English locales
2003 are known to cause programs to exhibit mysterious errors.
2005 If you have any of the above environment variables set, please try
2011 LC_ALL=C;export LC_ALL
2013 for Bourne or Korn shell) from the command line and then retry
2014 make test. If the tests then succeed, you may have a broken program that
2015 is confusing the testing. Please run the troublesome test by hand as
2016 shown above and see whether you can locate the program. Look for
2017 things like: exec, `backquoted command`, system, open("|...") or
2018 open("...|"). All these mean that Perl is trying to run some
2021 =item Timing problems
2023 Several tests in the test suite check timing functions, such as
2024 sleep(), and see if they return in a reasonable amount of time.
2025 If your system is quite busy and doesn't respond quickly enough,
2026 these tests might fail. If possible, try running the tests again
2027 with the system under a lighter load. These timing-sensitive
2028 and load-sensitive tests include F<t/op/alarm.t>,
2029 F<ext/Time/HiRes/HiRes.t>, F<lib/Benchmark.t>,
2030 F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
2034 On some systems, particularly those with smaller amounts of RAM, some
2035 of the tests in t/op/pat.t may fail with an "Out of memory" message.
2036 For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
2037 test 85 will fail if run under either t/TEST or t/harness.
2039 Try stopping other jobs on the system and then running the test by itself:
2041 cd t; ./perl op/pat.t
2043 to see if you have any better luck. If your perl still fails this
2044 test, it does not necessarily mean you have a broken perl. This test
2045 tries to exercise the regular expression subsystem quite thoroughly,
2046 and may well be far more demanding than your normal usage.
2048 =item Failures from lib/File/Temp/t/security saying "system possibly insecure"
2050 First, such warnings are not necessarily serious or indicative of a
2051 real security threat. That being said, they bear investigating.
2053 Note that each of the tests is run twice. The first time is in the
2054 directory returned by File::Spec->tmpdir() (often /tmp on Unix
2055 systems), and the second time in the directory from which the test was
2056 run (usually the 't' directory, if the test was run as part of 'make
2059 The tests may fail for the following reasons:
2061 (1) If the directory the tests are being run in is owned by somebody
2062 other than the user running the tests, or by root (uid 0).
2064 This failure can happen if the Perl source code distribution is
2065 unpacked in such a way that the user ids in the distribution package
2066 are used as-is. Some tar programs do this.
2068 (2) If the directory the tests are being run in is writable by group or
2069 by others, and there is no sticky bit set for the directory. (With
2070 UNIX/POSIX semantics, write access to a directory means the right to
2071 add or remove files in that directory. The 'sticky bit' is a feature
2072 used in some UNIXes to give extra protection to files: if the bit is
2073 set for a directory, no one but the owner (or root) can remove that
2074 file even if the permissions would otherwise allow file removal by
2077 This failure may or may not be a real problem: it depends on the
2078 permissions policy used on this particular system. This failure can
2079 also happen if the system either doesn't support the sticky bit (this
2080 is the case with many non-UNIX platforms: in principle File::Temp
2081 should know about these platforms and skip the tests), or if the system
2082 supports the sticky bit but for some reason or reasons it is not being
2083 used. This is, for example, the case with HP-UX: as of HP-UX release
2084 11.00, the sticky bit is very much supported, but HP-UX doesn't use it
2085 on its /tmp directory as shipped. Also, as with the permissions, some
2086 local policy might dictate that the stickiness is not used.
2088 (3) If the system supports the POSIX 'chown giveaway' feature and if
2089 any of the parent directories of the temporary file back to the root
2090 directory are 'unsafe', using the definitions given above in (1) and
2091 (2). For Unix systems, this is usually not an issue if you are
2092 building on a local disk. See the documentation for the File::Temp
2093 module for more information about 'chown giveaway'.
2095 See the documentation for the File::Temp module for more information
2096 about the various security aspects of temporary files.
2102 This will put perl into the public directory you specified to
2103 Configure; by default this is /usr/local/bin. It will also try
2104 to put the man pages in a reasonable place. It will not nroff the man
2105 pages, however. You may need to be root to run B<make install>. If you
2106 are not root, you must own the directories in question and you should
2107 ignore any messages about chown not working.
2109 =head2 Installing perl under different names
2111 If you want to install perl under a name other than "perl" (for example,
2112 when installing perl with special features enabled, such as debugging),
2113 indicate the alternate name on the "make install" line, such as:
2115 make install PERLNAME=myperl
2117 You can separately change the base used for versioned names (like
2118 "perl5.005") by setting PERLNAME_VERBASE, like
2120 make install PERLNAME=perl5 PERLNAME_VERBASE=perl
2122 This can be useful if you have to install perl as "perl5" (e.g. to
2123 avoid conflicts with an ancient version in /usr/bin supplied by your vendor).
2124 Without this the versioned binary would be called "perl55.005".
2126 =head2 Installed files
2128 If you want to see exactly what will happen without installing
2129 anything, you can run
2131 ./perl installperl -n
2132 ./perl installman -n
2134 make install will install the following:
2139 perl5.nnn where nnn is the current release number. This
2140 will be a link to perl.
2142 sperl5.nnn If you requested setuid emulation.
2143 a2p awk-to-perl translator
2147 cppstdin This is used by perl -P, if your cc -E can't
2149 c2ph, pstruct Scripts for handling C structures in header files.
2150 s2p sed-to-perl translator
2151 find2perl find-to-perl translator
2152 h2ph Extract constants and simple macros from C headers
2153 h2xs Converts C .h header files to Perl extensions.
2154 perlbug Tool to report bugs in Perl.
2155 perldoc Tool to read perl's pod documentation.
2156 pl2pm Convert Perl 4 .pl files to Perl 5 .pm modules
2157 pod2html, Converters from perl's pod documentation format
2158 pod2latex, to other useful formats.
2164 splain Describe Perl warnings and errors
2165 dprofpp Perl code profile post-processor
2169 in $privlib and $archlib specified to
2170 Configure, usually under /usr/local/lib/perl5/.
2174 man pages in $man1dir, usually /usr/local/man/man1.
2176 pages in $man3dir, usually /usr/local/man/man3.
2177 pod/*.pod in $privlib/pod/.
2179 Installperl will also create the directories listed above
2180 in L<"Installation Directories">.
2182 Perl's *.h header files and the libperl library are also installed
2183 under $archlib so that any user may later build new modules, run the
2184 optional Perl compiler, or embed the perl interpreter into another
2185 program even if the Perl source is no longer available.
2187 Sometimes you only want to install the version-specific parts of the perl
2188 installation. For example, you may wish to install a newer version of
2189 perl alongside an already installed production version of perl without
2190 disabling installation of new modules for the production version.
2191 To only install the version-specific parts of the perl installation, run
2193 Configure -Dversiononly
2195 or answer 'y' to the appropriate Configure prompt. Alternatively,
2196 you can just manually run
2198 ./perl installperl -v
2200 and skip installman altogether.
2201 See also L<"Maintaining completely separate versions"> for another
2204 =head1 Coexistence with earlier versions of perl5
2206 Perl 5.9 is not binary compatible with earlier versions of Perl.
2207 In other words, you will have to recompile your XS modules.
2209 In general, you can usually safely upgrade from one version of Perl (e.g.
2210 5.8.0) to another similar version (e.g. 5.8.2) without re-compiling
2211 all of your add-on extensions. You can also safely leave the old version
2212 around in case the new version causes you problems for some reason.
2213 For example, if you want to be sure that your script continues to run
2214 with 5.8.2, simply replace the '#!/usr/local/bin/perl' line at the
2215 top of the script with the particular version you want to run, e.g.
2216 #!/usr/local/bin/perl5.8.2.
2218 Usually, most extensions will probably not need to be recompiled to
2219 use with a newer version of Perl (the Perl 5.6 to Perl 5.8 transition
2220 being an exception). Here is how it is supposed to work. (These
2221 examples assume you accept all the Configure defaults.)
2223 Suppose you already have version 5.005_03 installed. The directories
2224 searched by 5.005_03 are
2226 /usr/local/lib/perl5/5.00503/$archname
2227 /usr/local/lib/perl5/5.00503
2228 /usr/local/lib/perl5/site_perl/5.005/$archname
2229 /usr/local/lib/perl5/site_perl/5.005
2231 Beginning with 5.6.0 the version number in the site libraries are
2232 fully versioned. Now, suppose you install version 5.6.0. The directories
2233 searched by version 5.6.0 will be
2235 /usr/local/lib/perl5/5.6.0/$archname
2236 /usr/local/lib/perl5/5.6.0
2237 /usr/local/lib/perl5/site_perl/5.6.0/$archname
2238 /usr/local/lib/perl5/site_perl/5.6.0
2240 /usr/local/lib/perl5/site_perl/5.005/$archname
2241 /usr/local/lib/perl5/site_perl/5.005
2242 /usr/local/lib/perl5/site_perl/
2244 Notice the last three entries -- Perl understands the default structure
2245 of the $sitelib directories and will look back in older, compatible
2246 directories. This way, modules installed under 5.005_03 will continue
2247 to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
2248 suppose that you upgrade a module to one which requires features
2249 present only in 5.6.0. That new module will get installed into
2250 /usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
2251 but will not interfere with the 5.005_03 version.
2253 The last entry, /usr/local/lib/perl5/site_perl/, is there so that
2254 5.6.0 and above will look for 5.004-era pure perl modules.
2256 Lastly, suppose you now install 5.8.0, which is not binary compatible
2257 with 5.6.0. The directories searched by 5.8.0 (if you don't change the
2258 Configure defaults) will be:
2260 /usr/local/lib/perl5/5.8.0/$archname
2261 /usr/local/lib/perl5/5.8.0
2262 /usr/local/lib/perl5/site_perl/5.8.0/$archname
2263 /usr/local/lib/perl5/site_perl/5.8.0
2265 /usr/local/lib/perl5/site_perl/5.6.0
2267 /usr/local/lib/perl5/site_perl/5.005
2269 /usr/local/lib/perl5/site_perl/
2271 Note that the earlier $archname entries are now gone, but pure perl
2272 modules from earlier versions will still be found.
2274 Assuming the users in your site are still actively using perl 5.6.0 and
2275 5.005 after you installed 5.8.0, you can continue to install add-on
2276 extensions using any of perl 5.8.0, 5.6.0, or 5.005. The installations
2277 of these different versions remain distinct, but remember that the
2278 newer versions of perl are automatically set up to search the
2279 compatible site libraries of the older ones. This means that
2280 installing a new XS extension with 5.005 will make it visible to both
2281 5.005 and 5.6.0, but not to 5.8.0. Installing a pure perl module with
2282 5.005 will make it visible to all three versions. Later, if you
2283 install the same extension using, say, perl 5.8.0, it will override the
2284 5.005-installed version, but only for perl 5.8.0.
2286 This way, you can choose to share compatible extensions, but also upgrade
2287 to a newer version of an extension that may be incompatible with earlier
2288 versions, without breaking the earlier versions' installations.
2290 =head2 Maintaining completely separate versions
2292 Many users prefer to keep all versions of perl in completely
2293 separate directories. This guarantees that an update to one version
2294 won't interfere with another version. (The defaults guarantee this for
2295 libraries after 5.6.0, but not for executables. TODO?) One convenient
2296 way to do this is by using a separate prefix for each version, such as
2298 sh Configure -Dprefix=/opt/perl5.8.2
2300 and adding /opt/perl5.8.2/bin to the shell PATH variable. Such users
2301 may also wish to add a symbolic link /usr/local/bin/perl so that
2302 scripts can still start with #!/usr/local/bin/perl.
2304 Others might share a common directory for maintenance sub-versions
2305 (e.g. 5.8 for all 5.8.x versions), but change directory with
2308 If you are installing a development subversion, you probably ought to
2309 seriously consider using a separate directory, since development
2310 subversions may not have all the compatibility wrinkles ironed out
2313 =head2 Upgrading from 5.005 or 5.6 to 5.8.0
2315 B<Perl 5.9.0 is binary incompatible with Perl 5.8.x, Perl 5.6.x, 5.005,
2316 and any earlier Perl release.> Perl modules having binary parts
2317 (meaning that a C compiler is used) will have to be recompiled to be
2318 used with 5.9.0. If you find you do need to rebuild an extension with
2319 5.9.0, you may safely do so without disturbing the older
2320 installations. (See L<"Coexistence with earlier versions of perl5">
2323 See your installed copy of the perllocal.pod file for a (possibly
2324 incomplete) list of locally installed modules. Note that you want
2325 perllocal.pod, not perllocale.pod, for installed module information.
2327 =head1 Coexistence with perl4
2329 You can safely install perl5 even if you want to keep perl4 around.
2331 By default, the perl5 libraries go into /usr/local/lib/perl5/, so
2332 they don't override the perl4 libraries in /usr/local/lib/perl/.
2334 In your /usr/local/bin directory, you should have a binary named
2335 perl4.036. That will not be touched by the perl5 installation
2336 process. Most perl4 scripts should run just fine under perl5.
2337 However, if you have any scripts that require perl4, you can replace
2338 the #! line at the top of them by #!/usr/local/bin/perl4.036 (or
2339 whatever the appropriate pathname is). See pod/perltrap.pod for
2340 possible problems running perl4 scripts under perl5.
2342 =head1 cd /usr/include; h2ph *.h sys/*.h
2344 Some perl scripts need to be able to obtain information from the
2345 system header files. This command will convert the most commonly used
2346 header files in /usr/include into files that can be easily interpreted
2347 by perl. These files will be placed in the architecture-dependent
2348 library ($archlib) directory you specified to Configure.
2350 Note: Due to differences in the C and perl languages, the conversion
2351 of the header files is not perfect. You will probably have to
2352 hand-edit some of the converted files to get them to parse correctly.
2353 For example, h2ph breaks spectacularly on type casting and certain
2356 =head1 installhtml --help
2358 Some sites may wish to make perl documentation available in HTML
2359 format. The installhtml utility can be used to convert pod
2360 documentation into linked HTML files and install them.
2362 Currently, the supplied ./installhtml script does not make use of the
2363 html Configure variables. This should be fixed in a future release.
2365 The following command-line is an example of one used to convert
2370 --podpath=lib:ext:pod:vms \
2372 --htmldir=/perl/nmanual \
2373 --htmlroot=/perl/nmanual \
2374 --splithead=pod/perlipc \
2375 --splititem=pod/perlfunc \
2376 --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
2379 See the documentation in installhtml for more details. It can take
2380 many minutes to execute a large installation and you should expect to
2381 see warnings like "no title", "unexpected directive" and "cannot
2382 resolve" as the files are processed. We are aware of these problems
2383 (and would welcome patches for them).
2385 You may find it helpful to run installhtml twice. That should reduce
2386 the number of "cannot resolve" warnings.
2388 =head1 cd pod && make tex && (process the latex files)
2390 Some sites may also wish to make the documentation in the pod/ directory
2391 available in TeX format. Type
2393 (cd pod && make tex && <process the latex files>)
2395 =head1 Minimizing the Perl installation
2397 The following section is meant for people worrying about squeezing the
2398 Perl installation into minimal systems (for example when installing
2399 operating systems, or in really small filesystems).
2401 Leaving out as many extensions as possible is an obvious way:
2402 Encode, with its big conversion tables, consumes a lot of
2403 space. On the other hand, you cannot throw away everything. The
2404 Fcntl module is pretty essential. If you need to do network
2405 programming, you'll appreciate the Socket module, and so forth: it all
2406 depends on what do you need to do.
2408 In the following we offer two different slimmed down installation
2409 recipes. They are informative, not normative: the choice of files
2410 depends on what you need.
2412 Firstly, the bare minimum to run this script
2416 foreach my $f (</*>) {
2420 in Solaris is as follows (under $Config{prefix}):
2423 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/autosplit.ix
2424 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_expandspec.al
2425 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_find_symbol_anywhere.al
2426 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_findfile.al
2427 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/Glob.so
2428 ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/autosplit.ix
2429 ./lib/perl5/5.6.1/sun4-solaris-64int/Config.pm
2430 ./lib/perl5/5.6.1/sun4-solaris-64int/XSLoader.pm
2431 ./lib/perl5/5.6.1/sun4-solaris-64int/DynaLoader.pm
2432 ./lib/perl5/5.6.1/sun4-solaris-64int/CORE/libperl.so
2433 ./lib/perl5/5.6.1/strict.pm
2434 ./lib/perl5/5.6.1/warnings.pm
2435 ./lib/perl5/5.6.1/Carp.pm
2436 ./lib/perl5/5.6.1/Exporter.pm
2437 ./lib/perl5/5.6.1/File/Glob.pm
2438 ./lib/perl5/5.6.1/AutoLoader.pm
2439 ./lib/perl5/5.6.1/vars.pm
2440 ./lib/perl5/5.6.1/warnings/register.pm
2441 ./lib/perl5/5.6.1/Carp/Heavy.pm
2442 ./lib/perl5/5.6.1/Exporter/Heavy.pm
2444 Secondly, Debian perl-base package contains the following files,
2445 size about 1.2MB in its i386 version:
2447 /usr/share/doc/perl/Documentation
2448 /usr/share/doc/perl/README.Debian
2449 /usr/share/doc/perl/copyright
2450 /usr/share/doc/perl/AUTHORS.gz
2451 /usr/share/doc/perl/changelog.Debian.gz
2452 /usr/share/man/man1/perl.1.gz
2453 /usr/share/perl/5.6.1/AutoLoader.pm
2454 /usr/share/perl/5.6.1/Carp.pm
2455 /usr/share/perl/5.6.1/Carp/Heavy.pm
2456 /usr/share/perl/5.6.1/Cwd.pm
2457 /usr/share/perl/5.6.1/Exporter.pm
2458 /usr/share/perl/5.6.1/Exporter/Heavy.pm
2459 /usr/share/perl/5.6.1/File/Spec.pm
2460 /usr/share/perl/5.6.1/File/Spec/Unix.pm
2461 /usr/share/perl/5.6.1/FileHandle.pm
2462 /usr/share/perl/5.6.1/Getopt/Long.pm
2463 /usr/share/perl/5.6.1/IO/Socket/INET.pm
2464 /usr/share/perl/5.6.1/IO/Socket/UNIX.pm
2465 /usr/share/perl/5.6.1/IPC/Open2.pm
2466 /usr/share/perl/5.6.1/IPC/Open3.pm
2467 /usr/share/perl/5.6.1/SelectSaver.pm
2468 /usr/share/perl/5.6.1/Symbol.pm
2469 /usr/share/perl/5.6.1/Text/Tabs.pm
2470 /usr/share/perl/5.6.1/Text/Wrap.pm
2471 /usr/share/perl/5.6.1/attributes.pm
2472 /usr/share/perl/5.6.1/auto/Getopt/Long/GetOptions.al
2473 /usr/share/perl/5.6.1/auto/Getopt/Long/FindOption.al
2474 /usr/share/perl/5.6.1/auto/Getopt/Long/Configure.al
2475 /usr/share/perl/5.6.1/auto/Getopt/Long/config.al
2476 /usr/share/perl/5.6.1/auto/Getopt/Long/Croak.al
2477 /usr/share/perl/5.6.1/auto/Getopt/Long/autosplit.ix
2478 /usr/share/perl/5.6.1/base.pm
2479 /usr/share/perl/5.6.1/constant.pm
2480 /usr/share/perl/5.6.1/fields.pm
2481 /usr/share/perl/5.6.1/integer.pm
2482 /usr/share/perl/5.6.1/lib.pm
2483 /usr/share/perl/5.6.1/locale.pm
2484 /usr/share/perl/5.6.1/overload.pm
2485 /usr/share/perl/5.6.1/strict.pm
2486 /usr/share/perl/5.6.1/vars.pm
2487 /usr/share/perl/5.6.1/warnings.pm
2488 /usr/share/perl/5.6.1/warnings/register.pm
2490 /usr/lib/perl/5.6.1/Config.pm
2491 /usr/lib/perl/5.6.1/Data/Dumper.pm
2492 /usr/lib/perl/5.6.1/DynaLoader.pm
2493 /usr/lib/perl/5.6.1/Errno.pm
2494 /usr/lib/perl/5.6.1/Fcntl.pm
2495 /usr/lib/perl/5.6.1/File/Glob.pm
2496 /usr/lib/perl/5.6.1/IO.pm
2497 /usr/lib/perl/5.6.1/IO/File.pm
2498 /usr/lib/perl/5.6.1/IO/Handle.pm
2499 /usr/lib/perl/5.6.1/IO/Pipe.pm
2500 /usr/lib/perl/5.6.1/IO/Seekable.pm
2501 /usr/lib/perl/5.6.1/IO/Select.pm
2502 /usr/lib/perl/5.6.1/IO/Socket.pm
2503 /usr/lib/perl/5.6.1/POSIX.pm
2504 /usr/lib/perl/5.6.1/Socket.pm
2505 /usr/lib/perl/5.6.1/XSLoader.pm
2506 /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.so
2507 /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.bs
2508 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_findfile.al
2509 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_expandspec.al
2510 /usr/lib/perl/5.6.1/auto/DynaLoader/dl_find_symbol_anywhere.al
2511 /usr/lib/perl/5.6.1/auto/DynaLoader/autosplit.ix
2512 /usr/lib/perl/5.6.1/auto/DynaLoader/DynaLoader.a
2513 /usr/lib/perl/5.6.1/auto/DynaLoader/extralibs.ld
2514 /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.so
2515 /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.bs
2516 /usr/lib/perl/5.6.1/auto/File/Glob/Glob.bs
2517 /usr/lib/perl/5.6.1/auto/File/Glob/Glob.so
2518 /usr/lib/perl/5.6.1/auto/File/Glob/autosplit.ix
2519 /usr/lib/perl/5.6.1/auto/IO/IO.so
2520 /usr/lib/perl/5.6.1/auto/IO/IO.bs
2521 /usr/lib/perl/5.6.1/auto/POSIX/POSIX.bs
2522 /usr/lib/perl/5.6.1/auto/POSIX/POSIX.so
2523 /usr/lib/perl/5.6.1/auto/POSIX/autosplit.ix
2524 /usr/lib/perl/5.6.1/auto/POSIX/load_imports.al
2525 /usr/lib/perl/5.6.1/auto/Socket/Socket.so
2526 /usr/lib/perl/5.6.1/auto/Socket/Socket.bs
2528 =head1 Reporting Problems
2530 If you have difficulty building perl, and none of the advice in this file
2531 helps, and careful reading of the error message and the relevant manual
2532 pages on your system doesn't help either, then you should send a message
2533 to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with
2534 an accurate description of your problem.
2536 Please include the output of the ./myconfig shell script that comes with
2537 the distribution. Alternatively, you can use the perlbug program that
2538 comes with the perl distribution, but you need to have perl compiled
2539 before you can use it. (If you have not installed it yet, you need to
2540 run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
2542 Please try to make your message brief but clear. Trim out unnecessary
2543 information. Do not include large files (such as config.sh or a complete
2544 Configure or make log) unless absolutely necessary. Do not include a
2545 complete transcript of your build session. Just include the failing
2546 commands, the relevant error messages, and whatever preceding commands
2547 are necessary to give the appropriate context. Plain text should
2548 usually be sufficient--fancy attachments or encodings may actually
2549 reduce the number of people who read your message. Your message
2550 will get relayed to over 400 subscribers around the world so please
2551 try to keep it brief but clear.
2553 =head1 DOCUMENTATION
2555 Read the manual entries before running perl. The main documentation
2556 is in the pod/ subdirectory and should have been installed during the
2557 build process. Type B<man perl> to get started. Alternatively, you
2558 can type B<perldoc perl> to use the supplied perldoc script. This is
2559 sometimes useful for finding things in the library modules.
2561 Under UNIX, you can produce a documentation book in postscript form,
2562 along with its table of contents, by going to the pod/ subdirectory and
2565 ./roffitall -groff # If you have GNU groff installed
2566 ./roffitall -psroff # If you have psroff
2568 This will leave you with two postscript files ready to be printed.
2569 (You may need to fix the roffitall command to use your local troff
2572 Note that you must have performed the installation already before running
2573 the above, since the script collects the installed files to generate
2578 Original author: Andy Dougherty doughera@lafayette.edu , borrowing very
2579 heavily from the original README by Larry Wall, with lots of helpful
2580 feedback and additions from the perl5-porters@perl.org folks.
2582 If you have problems, corrections, or questions, please see
2583 L<"Reporting Problems"> above.
2585 =head1 REDISTRIBUTION
2587 This document is part of the Perl package and may be distributed under
2588 the same terms as perl itself, with the following additional request:
2589 If you are distributing a modified version of perl (perhaps as part of
2590 a larger package) please B<do> modify these installation instructions
2591 and the contact information to match your distribution.